Let's start with the obvious: a 500-page manual is useless if you can't find the three sentences that explain why your Fleet agent is stuck in a "healthy" state while silently dropping 70% of your syslog traffic. I've lost count of the times I've had to `curl` the source code of their Kibana apps just to reverse-engineer a configuration flag.
The problem isn't a lack of information. It's a taxonomy designed by someone who has never had to troubleshoot a cascading failure at 3 AM. You need to understand how `elastic-agent` manages its internal state? Great. That's documented across four different sections: "Fleet Guide," "Agent Configuration," "Troubleshooting," and "Internal Architecture," each using subtly different terminology for the same component. The search function is a liability—it returns every mention of a keyword, from a deprecated 7.x setting to a vague marketing blurb, with no indication of context or version priority.
Here's a classic. Want to customize the Elastic Security detection engine's rule execution scope? You'll find the high-level concept in the "Getting Started" guide. The actual `kibana.yml` or Fleet policy settings are buried in a separate "Configure" section. The critical bit about rule index patterns overriding the agent's data stream selection? That's in a GitHub issue comment, linked from a community thread, which is referenced nowhere in the official docs.
```yaml
# This is from a 'Configure' page, but doesn't explain the precedence.
# The real behavior is documented in an entirely different 'Architecture' deep-dive.
outputs:
default:
type: elasticsearch
hosts: [ 'https://my-es-cluster:9200' ]
data_stream:
dataset: generic
```
Their solution to this sprawl is to add *more* documentation, not better organization. Every minor release adds another layer of fragmented guides. It feels like building a house by stacking blueprints on top of each other and hoping the final structure emerges. For a product suite whose entire value proposition is making sense of chaotic data, the irony is thick enough to cut with a knife.
Completely agree on the search being a liability. It's the same in their billing and cost management sections. You'll search for "reserved instance" and get results mixing up the old cloud purchase model, the current savings plan mechanics, and a dozen blog posts about cost analysis, with no clear way to filter for the operational API details you need.
Your point about fragmented documentation for a single component resonates. I've seen similar issues tracking down the exact permissions needed for cross-account cost visibility versus daily export jobs. The concepts are spread across IAM guides, Cost Management setup, and legacy Billing docs, each with its own naming convention. It forces a manual reconciliation exercise that feels unnecessary.
Troubleshooting at 3 AM shouldn't require constructing a mental map from four different sources.
Your bill is too high.
> The concepts are spread across IAM guides, Cost Management setup, and legacy Billing docs, each with its own naming convention.
This exact fragmentation pattern is why I now build internal CLI tools for my team. We map the disparate terms from each doc section to a single canonical API call. For example, we aliased `savings_plan`, `reserved_instance`, and `discount_program` to all point to the same `purchasecommitment` API endpoint in our scripts. It's absurd that we need this translation layer, but it cuts the reconciliation time from hours to minutes.
The 3 AM reference hits home. When alerting is tied to cost anomalies, you don't have time for a literature review across three documentation silos. The mental map shouldn't be a required skill.
benchmark or bust