elastic / elastic/docs-content
Document policy_namespace filtering/routing for Elastic Agent status-change events
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
## Summary
We should add docs explaining how to use the new `policy_namespace` field on Elastic Agent status-change events to filter and route alerting/use cases without changing write routing.
Context: Fleet status-change events continue writing to `logs-elastic_agent.status_change-default`, and `policy_namespace` preserves the originating agent policy namespace in each event.
Contact: @juliaElastic
## What should be documented
1. **Field purpose and behavior**
- `policy_namespace` contains the namespace from the agent policy at write time.
- Fallback behavior is `default` when policy is missing/unresolvable.
2. **How to query/filter with ES|QL**
- Example using wildcard source and namespace filter:
```esql
FROM logs-elastic_agent.status_change-*
| WHERE policy_namespace == "custom_namespace"
```
- Clarify difference between filtering by `data_stream.namespace` vs `policy_namespace` for this stream.
3. **How this helps routing/separation use cases**
- Users can keep existing default stream behavior while segmenting rules/dashboards by namespace via query filters.
4. **Impact on existing alerting content**
- Existing content hardcoding `logs-elastic_agent.status_change-default` still works for default behavior.
- Namespace-aware filtering should use `policy_namespace` (or wildcard `FROM` + filter), per updated templates.
## Suggested doc locations
- [Monitor Elastic Agents](https://elastic.co/docs/reference/fleet/monitor-elastic-agent)
- [Elastic Agent data streams for Fleet](https://elastic.co/docs/reference/fleet/data-streams)
## References
- https://github.com/elastic/kibana/issues/286395#issuecomment-5449537988
- https://github.com/elastic/kibana/pull/287194
- https://github.com/elastic/integrations/pull/20904
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the Monitor Elastic Agents and Elastic Agent data streams documentation pages named in the issue, then review the referenced Kibana and integrations changes for the intended terminology and examples. Done means both pages explain policy_namespace behavior, ES|QL filtering, routing implications, and compatibility with existing alerting content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- elasticsearch
- Domain
- documentation, observability
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100