elastic / elastic/docs-content

Document policy_namespace filtering/routing for Elastic Agent status-change events

Open
#8,113 1 comment 0 reactions 0 assignees View on GitHub
Team:SKI
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.