{"owner":"elastic","repo":"beats","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"## Repository Overview\n\nElastic Beats is a Go monorepo containing lightweight data shippers for the Elastic Stack. The module path is `github.com/elastic/beats/v7`. Go version: see `.go-version`.\n\n## Build System\n\nThe primary build tool is **Mage** (Go-based). Makefile wraps mage for some targets. Each beat has its own `magefile.go`; shared build logic lives in `dev-tools/mage/`.\n\n### Per-Beat Commands (run from the beat's directory, e.g. `cd filebeat`)\n\n```bash\nmage build              # Build the beat binary\nmage unitTest           # Run Go unit tests\nmage integTest          # Run integration tests (requires Docker)\nmage goIntegTest        # Go integration tests only\nmage pythonIntegTest    # Python integration tests only\nmage update             # Regenerate fields, configs, dashboards, includes\nmage fields             # Regenerate fields.yml and fields.go\nmage config             # Regenerate config files\nmage check              # Run checks (lint, headers, go mod)\nmage docker:composeUp   # Start integration test containers, wait until healthy\nmage docker:composeDown # Stop integration test containers\nmage crossBuild         # Cross-compile for all platforms\nSNAPSHOT=true DEV=true PLATFORMS=$GOOS/$GOARCH PACKAGES=tar.gz mage package  # Build and package the beat\n```\n\nFor `mage package`, set `PLATFORMS` to match the current OS/architecture. Check with `go env GOOS GOARCH` before running. Common values: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`. `PACKAGES` sets the format: `tar.gz`, `zip`, `rpm`, `deb`, `docker` (comma-separated).\n\n### Running Tests\n\n**Do not run all unit or integration tests** (e.g. `mage unitTest` from root) unless explicitly requested. They take too long and require too many dependencies. Always run tests scoped to the package you're working on:\n\n```bash\n# Run a single test or package tests\ncd filebeat  # or any beat directory\ngo test -v -race -run TestName ./path/to/package/...\n\n# Stress test to find flaky tests (runs a test repeatedly with x/tools/cmd/stress)\n# It runs FOREVER (stress -timeout is per-run, not total); bound it with an outer `timeout`.\ntimeout 5m script/stresstest.sh [--tags integration] [--race] ./path/to/package ^TestName$ -p 32 [-failfast]\n```\n\n### Integration Tests\n\nIntegration tests may need external dependencies that can be started with mage\nor manually. The Go test binary is built automatically via `TestMain`.\n\n```bash\n# Run integration tests for a specific package\ngo test -v -race -run TestName -tags integration ./path/to/package/...\n```\n\n### Running a Beat\n\n```bash\nDEV=true mage build\n./filebeat -e --strict.perms=false -c filebeat.yml -path.home=<temp_dir>\n```\n\nAlways pass `--strict.perms=false` during development — it disables strict config\nfile permission checks. Set `-path.home` to a temporary directory to avoid\nwriting data/logs into the source tree.\n\n### Pre-Push Check\n\nBefore pushing, run `mage check` from the beat directory — it's a required CI check and catches lint, header, and module issues early.\n\n### Root-Level Commands\n\n```bash\nmage fmt                     # Format code + add license headers\nmake check                   # Full check suite (lint, headers, go mod, python)\n```\n\n### Linting\n\n```bash\n# Running golangci-lint for the whole codebase is slow, prefer running only on changed lines by default.\ngolangci-lint run --max-issues-per-linter 0 --max-same-issues 0 --new-from-merge-base upstream/main\n```\n\n## Architecture\n\n### Beats\n\n| Beat | Description |\n|------|-------------|\n| `filebeat` | Lightweight agent that ships log files and journals |\n| `metricbeat` | Collects metrics from systems and services |\n| `heartbeat` | Monitors availability of services and endpoints, detecting uptime/downtime |\n| `auditbeat` | Gathers audit data from systems to track security events, user activities, and compliance requirements |\n| `packetbeat` | Analyzes network traffic by capturing and inspecting packets for application and network visibility |\n| `winlogbeat` | Collects Windows Event logs for centralized monitoring and troubleshooting of Windows systems |\n| `x-pack/osquerybeat` | Manages and queries Osquery endpoints (Elastic license) |\n| `x-pack/dockerlogbeat` | Ships Docker container logs as a Docker log driver plugin (Elastic license) |\n| `x-pack/otel` | OTel Collector components that wrap beats as receivers, processors, and exporters for the Elastic Distribution of OpenTelemetry (Elastic license) |\n\nEach beat follows the pattern: `cmd/` (CLI entry), `beater/` (implements `beat.Beater` interface from `libbeat/beat/beat.go`), `module/` or `input/` (data collection).\n\n### libbeat (shared framework)\n\nAll beats build on `libbeat/`, which provides:\n- `beat/` — `Beater` interface (Run/Stop), `Beat` struct, `Pipeline`/`Client` for event publishing\n- `outputs/` — Output plugins (Elasticsearch, Logstash, Kafka, Redis, etc.)\n- `processors/` — Event processing pipeline\n- `publisher/` — Internal publishing pipeline\n- `cmd/` — Shared CLI infrastructure and beat instance bootstrapping\n- `autodiscover/` — Dynamic service discovery (Docker, Kubernetes)\n- `management/` — Elastic Agent management integration\n- `statestore/` — Persistent state\n\n### x-pack\n\n`x-pack/` contains Elastic-licensed extensions for each beat and x-pack-only beats. Each `x-pack/{beat}` extends the corresponding OSS beat with additional modules, inputs, or features.\n\n### Licensing Boundary\n\nOSS code (Apache 2.0) **cannot** import from `x-pack/` or `elastic-agent-client`. This is enforced by `depguard` in `.golangci.yml`. X-pack code can import OSS code freely.\n\n## Code Rules\n\n- Logging: accept `*logp.Logger` as a parameter. For tests prefer `logptest`\n- Use `github.com/stretchr/testify` in tests — always add a message explaining the failure. Use `assert` by default, `require` only when you actually need to interrupt the test\n- Use `github.com/gofrs/uuid/v5`\n- Write unit tests for new functionality. Use table-driven tests when appropriate\n- Document exported functions and types\n- Keep comments concise, focused on \"why\" not \"what\"\n- Update documentation when changing behavior\n\n## Code References\n\nWhen referencing code, always use exact locations and names:\n- Format: `filepath:line_number` or `filepath:start-end`\n- Use specific element names (functions, methods, variables)\n- Quote exact text from code and logs — zero paraphrasing\n\n## Changelog\n\nPRs require a changelog fragment in `changelog/fragments/` (CI enforced unless `skip-changelog` label is applied). Create using `elastic-agent-changelog-tool`:\n\n```bash\ngo run github.com/elastic/elastic-agent-changelog-tool@latest new --component <beat> --kind <kind>\n```\n\nFragment format (`changelog/fragments/<timestamp>-<slug>.yaml`):\n```yaml\nkind: bug-fix          # bug-fix, enhancement, breaking-change, deprecation, known-issue\nsummary: Short description of the change\ncomponent: filebeat    # the affected beat/component\n```\n\n## Commits and PRs\n\nWhen writing commit messages, explain WHAT changed and WHY — the rationale and motivation, not just a description of the diff. The commit title is used as the squash-merge message. Add a trailer line `Assisted-By: <tool name>` for each AI tool used.\n\nWhen creating PRs, follow the template in `.github/PULL_REQUEST_TEMPLATE.md`\n"},"files":{"AGENTS.md":"## Repository Overview\n\nElastic Beats is a Go monorepo containing lightweight data shippers for the Elastic Stack. The module path is `github.com/elastic/beats/v7`. Go version: see `.go-version`.\n\n## Build System\n\nThe primary build tool is **Mage** (Go-based). Makefile wraps mage for some targets. Each beat has its own `magefile.go`; shared build logic lives in `dev-tools/mage/`.\n\n### Per-Beat Commands (run from the beat's directory, e.g. `cd filebeat`)\n\n```bash\nmage build              # Build the beat binary\nmage unitTest           # Run Go unit tests\nmage integTest          # Run integration tests (requires Docker)\nmage goIntegTest        # Go integration tests only\nmage pythonIntegTest    # Python integration tests only\nmage update             # Regenerate fields, configs, dashboards, includes\nmage fields             # Regenerate fields.yml and fields.go\nmage config             # Regenerate config files\nmage check              # Run checks (lint, headers, go mod)\nmage docker:composeUp   # Start integration test containers, wait until healthy\nmage docker:composeDown # Stop integration test containers\nmage crossBuild         # Cross-compile for all platforms\nSNAPSHOT=true DEV=true PLATFORMS=$GOOS/$GOARCH PACKAGES=tar.gz mage package  # Build and package the beat\n```\n\nFor `mage package`, set `PLATFORMS` to match the current OS/architecture. Check with `go env GOOS GOARCH` before running. Common values: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`. `PACKAGES` sets the format: `tar.gz`, `zip`, `rpm`, `deb`, `docker` (comma-separated).\n\n### Running Tests\n\n**Do not run all unit or integration tests** (e.g. `mage unitTest` from root) unless explicitly requested. They take too long and require too many dependencies. Always run tests scoped to the package you're working on:\n\n```bash\n# Run a single test or package tests\ncd filebeat  # or any beat directory\ngo test -v -race -run TestName ./path/to/package/...\n\n# Stress test to find flaky tests (runs a test repeatedly with x/tools/cmd/stress)\n# It runs FOREVER (stress -timeout is per-run, not total); bound it with an outer `timeout`.\ntimeout 5m script/stresstest.sh [--tags integration] [--race] ./path/to/package ^TestName$ -p 32 [-failfast]\n```\n\n### Integration Tests\n\nIntegration tests may need external dependencies that can be started with mage\nor manually. The Go test binary is built automatically via `TestMain`.\n\n```bash\n# Run integration tests for a specific package\ngo test -v -race -run TestName -tags integration ./path/to/package/...\n```\n\n### Running a Beat\n\n```bash\nDEV=true mage build\n./filebeat -e --strict.perms=false -c filebeat.yml -path.home=<temp_dir>\n```\n\nAlways pass `--strict.perms=false` during development — it disables strict config\nfile permission checks. Set `-path.home` to a temporary directory to avoid\nwriting data/logs into the source tree.\n\n### Pre-Push Check\n\nBefore pushing, run `mage check` from the beat directory — it's a required CI check and catches lint, header, and module issues early.\n\n### Root-Level Commands\n\n```bash\nmage fmt                     # Format code + add license headers\nmake check                   # Full check suite (lint, headers, go mod, python)\n```\n\n### Linting\n\n```bash\n# Running golangci-lint for the whole codebase is slow, prefer running only on changed lines by default.\ngolangci-lint run --max-issues-per-linter 0 --max-same-issues 0 --new-from-merge-base upstream/main\n```\n\n## Architecture\n\n### Beats\n\n| Beat | Description |\n|------|-------------|\n| `filebeat` | Lightweight agent that ships log files and journals |\n| `metricbeat` | Collects metrics from systems and services |\n| `heartbeat` | Monitors availability of services and endpoints, detecting uptime/downtime |\n| `auditbeat` | Gathers audit data from systems to track security events, user activities, and compliance requirements |\n| `packetbeat` | Analyzes network traffic by capturing and inspecting packets for application and network visibility |\n| `winlogbeat` | Collects Windows Event logs for centralized monitoring and troubleshooting of Windows systems |\n| `x-pack/osquerybeat` | Manages and queries Osquery endpoints (Elastic license) |\n| `x-pack/dockerlogbeat` | Ships Docker container logs as a Docker log driver plugin (Elastic license) |\n| `x-pack/otel` | OTel Collector components that wrap beats as receivers, processors, and exporters for the Elastic Distribution of OpenTelemetry (Elastic license) |\n\nEach beat follows the pattern: `cmd/` (CLI entry), `beater/` (implements `beat.Beater` interface from `libbeat/beat/beat.go`), `module/` or `input/` (data collection).\n\n### libbeat (shared framework)\n\nAll beats build on `libbeat/`, which provides:\n- `beat/` — `Beater` interface (Run/Stop), `Beat` struct, `Pipeline`/`Client` for event publishing\n- `outputs/` — Output plugins (Elasticsearch, Logstash, Kafka, Redis, etc.)\n- `processors/` — Event processing pipeline\n- `publisher/` — Internal publishing pipeline\n- `cmd/` — Shared CLI infrastructure and beat instance bootstrapping\n- `autodiscover/` — Dynamic service discovery (Docker, Kubernetes)\n- `management/` — Elastic Agent management integration\n- `statestore/` — Persistent state\n\n### x-pack\n\n`x-pack/` contains Elastic-licensed extensions for each beat and x-pack-only beats. Each `x-pack/{beat}` extends the corresponding OSS beat with additional modules, inputs, or features.\n\n### Licensing Boundary\n\nOSS code (Apache 2.0) **cannot** import from `x-pack/` or `elastic-agent-client`. This is enforced by `depguard` in `.golangci.yml`. X-pack code can import OSS code freely.\n\n## Code Rules\n\n- Logging: accept `*logp.Logger` as a parameter. For tests prefer `logptest`\n- Use `github.com/stretchr/testify` in tests — always add a message explaining the failure. Use `assert` by default, `require` only when you actually need to interrupt the test\n- Use `github.com/gofrs/uuid/v5`\n- Write unit tests for new functionality. Use table-driven tests when appropriate\n- Document exported functions and types\n- Keep comments concise, focused on \"why\" not \"what\"\n- Update documentation when changing behavior\n\n## Code References\n\nWhen referencing code, always use exact locations and names:\n- Format: `filepath:line_number` or `filepath:start-end`\n- Use specific element names (functions, methods, variables)\n- Quote exact text from code and logs — zero paraphrasing\n\n## Changelog\n\nPRs require a changelog fragment in `changelog/fragments/` (CI enforced unless `skip-changelog` label is applied). Create using `elastic-agent-changelog-tool`:\n\n```bash\ngo run github.com/elastic/elastic-agent-changelog-tool@latest new --component <beat> --kind <kind>\n```\n\nFragment format (`changelog/fragments/<timestamp>-<slug>.yaml`):\n```yaml\nkind: bug-fix          # bug-fix, enhancement, breaking-change, deprecation, known-issue\nsummary: Short description of the change\ncomponent: filebeat    # the affected beat/component\n```\n\n## Commits and PRs\n\nWhen writing commit messages, explain WHAT changed and WHY — the rationale and motivation, not just a description of the diff. The commit title is used as the squash-merge message. Add a trailer line `Assisted-By: <tool name>` for each AI tool used.\n\nWhen creating PRs, follow the template in `.github/PULL_REQUEST_TEMPLATE.md`\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"## Repository Overview\n\nElastic Beats is a Go monorepo containing lightweight data shippers for the Elastic Stack. The module path is `github.com/elastic/beats/v7`. Go version: see `.go-version`.\n\n## Build System\n\nThe primary build tool is **Mage** (Go-based). Makefile wraps mage for some targets. Each beat has its own `magefile.go`; shared build logic lives in `dev-tools/mage/`.\n\n### Per-Beat Commands (run from the beat's directory, e.g. `cd filebeat`)\n\n```bash\nmage build              # Build the beat binary\nmage unitTest           # Run Go unit tests\nmage integTest          # Run integration tests (requires Docker)\nmage goIntegTest        # Go integration tests only\nmage pythonIntegTest    # Python integration tests only\nmage update             # Regenerate fields, configs, dashboards, includes\nmage fields             # Regenerate fields.yml and fields.go\nmage config             # Regenerate config files\nmage check              # Run checks (lint, headers, go mod)\nmage docker:composeUp   # Start integration test containers, wait until healthy\nmage docker:composeDown # Stop integration test containers\nmage crossBuild         # Cross-compile for all platforms\nSNAPSHOT=true DEV=true PLATFORMS=$GOOS/$GOARCH PACKAGES=tar.gz mage package  # Build and package the beat\n```\n\nFor `mage package`, set `PLATFORMS` to match the current OS/architecture. Check with `go env GOOS GOARCH` before running. Common values: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`. `PACKAGES` sets the format: `tar.gz`, `zip`, `rpm`, `deb`, `docker` (comma-separated).\n\n### Running Tests\n\n**Do not run all unit or integration tests** (e.g. `mage unitTest` from root) unless explicitly requested. They take too long and require too many dependencies. Always run tests scoped to the package you're working on:\n\n```bash\n# Run a single test or package tests\ncd filebeat  # or any beat directory\ngo test -v -race -run TestName ./path/to/package/...\n\n# Stress test to find flaky tests (runs a test repeatedly with x/tools/cmd/stress)\n# It runs FOREVER (stress -timeout is per-run, not total); bound it with an outer `timeout`.\ntimeout 5m script/stresstest.sh [--tags integration] [--race] ./path/to/package ^TestName$ -p 32 [-failfast]\n```\n\n### Integration Tests\n\nIntegration tests may need external dependencies that can be started with mage\nor manually. The Go test binary is built automatically via `TestMain`.\n\n```bash\n# Run integration tests for a specific package\ngo test -v -race -run TestName -tags integration ./path/to/package/...\n```\n\n### Running a Beat\n\n```bash\nDEV=true mage build\n./filebeat -e --strict.perms=false -c filebeat.yml -path.home=<temp_dir>\n```\n\nAlways pass `--strict.perms=false` during development — it disables strict config\nfile permission checks. Set `-path.home` to a temporary directory to avoid\nwriting data/logs into the source tree.\n\n### Pre-Push Check\n\nBefore pushing, run `mage check` from the beat directory — it's a required CI check and catches lint, header, and module issues early.\n\n### Root-Level Commands\n\n```bash\nmage fmt                     # Format code + add license headers\nmake check                   # Full check suite (lint, headers, go mod, python)\n```\n\n### Linting\n\n```bash\n# Running golangci-lint for the whole codebase is slow, prefer running only on changed lines by default.\ngolangci-lint run --max-issues-per-linter 0 --max-same-issues 0 --new-from-merge-base upstream/main\n```\n\n## Architecture\n\n### Beats\n\n| Beat | Description |\n|------|-------------|\n| `filebeat` | Lightweight agent that ships log files and journals |\n| `metricbeat` | Collects metrics from systems and services |\n| `heartbeat` | Monitors availability of services and endpoints, detecting uptime/downtime |\n| `auditbeat` | Gathers audit data from systems to track security events, user activities, and compliance requirements |\n| `packetbeat` | Analyzes network traffic by capturing and inspecting packets for application and network visibility |\n| `winlogbeat` | Collects Windows Event logs for centralized monitoring and troubleshooting of Windows systems |\n| `x-pack/osquerybeat` | Manages and queries Osquery endpoints (Elastic license) |\n| `x-pack/dockerlogbeat` | Ships Docker container logs as a Docker log driver plugin (Elastic license) |\n| `x-pack/otel` | OTel Collector components that wrap beats as receivers, processors, and exporters for the Elastic Distribution of OpenTelemetry (Elastic license) |\n\nEach beat follows the pattern: `cmd/` (CLI entry), `beater/` (implements `beat.Beater` interface from `libbeat/beat/beat.go`), `module/` or `input/` (data collection).\n\n### libbeat (shared framework)\n\nAll beats build on `libbeat/`, which provides:\n- `beat/` — `Beater` interface (Run/Stop), `Beat` struct, `Pipeline`/`Client` for event publishing\n- `outputs/` — Output plugins (Elasticsearch, Logstash, Kafka, Redis, etc.)\n- `processors/` — Event processing pipeline\n- `publisher/` — Internal publishing pipeline\n- `cmd/` — Shared CLI infrastructure and beat instance bootstrapping\n- `autodiscover/` — Dynamic service discovery (Docker, Kubernetes)\n- `management/` — Elastic Agent management integration\n- `statestore/` — Persistent state\n\n### x-pack\n\n`x-pack/` contains Elastic-licensed extensions for each beat and x-pack-only beats. Each `x-pack/{beat}` extends the corresponding OSS beat with additional modules, inputs, or features.\n\n### Licensing Boundary\n\nOSS code (Apache 2.0) **cannot** import from `x-pack/` or `elastic-agent-client`. This is enforced by `depguard` in `.golangci.yml`. X-pack code can import OSS code freely.\n\n## Code Rules\n\n- Logging: accept `*logp.Logger` as a parameter. For tests prefer `logptest`\n- Use `github.com/stretchr/testify` in tests — always add a message explaining the failure. Use `assert` by default, `require` only when you actually need to interrupt the test\n- Use `github.com/gofrs/uuid/v5`\n- Write unit tests for new functionality. Use table-driven tests when appropriate\n- Document exported functions and types\n- Keep comments concise, focused on \"why\" not \"what\"\n- Update documentation when changing behavior\n\n## Code References\n\nWhen referencing code, always use exact locations and names:\n- Format: `filepath:line_number` or `filepath:start-end`\n- Use specific element names (functions, methods, variables)\n- Quote exact text from code and logs — zero paraphrasing\n\n## Changelog\n\nPRs require a changelog fragment in `changelog/fragments/` (CI enforced unless `skip-changelog` label is applied). Create using `elastic-agent-changelog-tool`:\n\n```bash\ngo run github.com/elastic/elastic-agent-changelog-tool@latest new --component <beat> --kind <kind>\n```\n\nFragment format (`changelog/fragments/<timestamp>-<slug>.yaml`):\n```yaml\nkind: bug-fix          # bug-fix, enhancement, breaking-change, deprecation, known-issue\nsummary: Short description of the change\ncomponent: filebeat    # the affected beat/component\n```\n\n## Commits and PRs\n\nWhen writing commit messages, explain WHAT changed and WHY — the rationale and motivation, not just a description of the diff. The commit title is used as the squash-merge message. Add a trailer line `Assisted-By: <tool name>` for each AI tool used.\n\nWhen creating PRs, follow the template in `.github/PULL_REQUEST_TEMPLATE.md`\n","category":"root","tokens":1816}]}