elastic / elastic/beats

[docs-patrol] Document new osquery profiling workflow and journald compatibility fallback

Open
#49,586 2 comments 0 reactions 1 assignee Claimed by @marc-gr View on GitHub
needs_team
Dominant language
Go
Stars
12.7k
Forks
5k
Avg merge
2d 15m
Merged PRs (30d)
385

Description

Recent code changes in the repository have introduced documentation drift. The following changes need corresponding documentation updates.

## Changes Requiring Documentation Updates

### 1. Osquery query profiling added new config + event flow that is not documented end-to-end

**Commit(s):**
- d09baafc22f8022c3b5b83623fd5e4a805207f41
- 3e72f7f24d013838c3b760f90e469bebf5a3f222

**What changed:**
- New stream-level `profile` option for scheduled queries (`x-pack/osquerybeat/internal/config/config.go:47-48`).
- Profile events are only published when a stream with dataset `osquery_manager.query_profile` exists; otherwise they are dropped (`x-pack/osquerybeat/internal/pub/publisher.go:117-123`, `250-253`).
- New `osquery.elastic_options.query_profile_storage.*` and `osquery.elastic_options.install.*` config trees, including `allow_insecure_url` and TLS options, were added to reference config (`x-pack/osquerybeat/_meta/config/beat.reference.yml.tmpl:10-53`, mirrored in `x-pack/osquerybeat/osquerybeat.reference.yml`).
- Profile event payload fields (`type: osquery_profile`, `osquery_profile`, optional `query.name`, `action_id`, `response_id`) are emitted (`x-pack/osquerybeat/internal/pub/publisher.go:258-275`).

**Documentation impact:**
- Osquerybeat docs should describe the profiling workflow and prerequisites (how to enable `profile`, required dataset stream, and drop behavior when missing).
- Exported fields documentation should cover `osquery_profile` event content; current exported fields doc does not include it (`x-pack/osquerybeat/docs/fields.asciidoc`).

### 2. Journald reader now conditionally uses `--boot all` by journalctl version, but docs do not mention this behavior

**Commit(s):**
- f6662a962a3e7cd516d3b62a2c7f7cd883a94f05

**What changed:**
- Filebeat now probes `journalctl --version` and only uses `--boot all` when supported (>=242) (`filebeat/input/journald/pkg/journalctl/reader.go:130-163`, `169-173`).
- On detection failure, it logs and omits `--boot all` (`filebeat/input/journald/pkg/journalctl/reader.go:137-138`).

**Documentation impact:**
- `docs/reference/filebeat/filebeat-input-journald.md` should explain the version-gated behavior and fallback so users on older distributions understand why multi-boot behavior differs.

## Suggested Actions

- [ ] Add osquerybeat user docs for query profiling configuration and required `osquery_manager.query_profile` stream wiring.
- [ ] Add/refresh osquerybeat exported fields docs for profile events (`osquery_profile` payload and related fields).
- [ ] Update journald input docs to describe `journalctl` version detection and conditional `--boot all` usage.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Docs Patrol](https://github.com/elastic/beats/actions/runs/23346904861)

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
> - [x] expires on Mar 27, 2026, 2:33 PM UTC

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.