elastic / elastic/beats

[docs-patrol] Document Heartbeat APM cross-linking and AWS S3 SQS health status

Open
#52,143 1 comment 0 reactions 0 assignees View on GitHub
needs_team
Dominant language
Go
Stars
12.7k
Forks
5k
Avg merge
2d 1h
Merged PRs (30d)
370

Description

Recent code changes have introduced user-visible behavior that is not reflected in the reference documentation.

## Changes Requiring Documentation Updates

### 1. AWS S3 SQS health-status behavior

**Commit(s):** `a70481df587616165a43405770bebbe870f35b0b` and `bb6e64cfd436f52a1d8de81d75a83d7951aeb9c5`

**What changed:** `x-pack/filebeat/input/awss3/health.go:18-31` adds aggregated Fleet health reporting with consecutive-failure thresholds. `health.go:133-208` reports persistent processing failures, SQS delete/finalize failures, and poison-pill deletion as degraded conditions, including a data-loss warning. The v2 path invokes these signals in `x-pack/filebeat/input/awss3/v2_sqs.go:129-171`.

**Documentation impact:** `docs/reference/filebeat/filebeat-input-aws-s3.md:19-21` documents visibility-timeout handling and message retry behavior, but does not explain when the input becomes `Degraded`, what delete/finalize failures mean, or that a poison-pill message may be deleted with data missing. Operators cannot interpret the new health status.

### 2. Heartbeat synthetics/APM cross-linking

**Commit:** `e483b2b7f817f01a7d59731a4bd9a263ac1f15ef`

**What changed:** `x-pack/heartbeat/monitors/browser/synthexec/synthexec.go:149-166,193-196` injects `ELASTIC_SYNTHETICS_TRACE_ID`, `ELASTIC_SYNTHETICS_MONITOR_ID`, `ELASTIC_SYNTHETICS_MONITOR_TYPE`, and `ELASTIC_SYNTHETICS_MONITOR_LOCATION` into the synthetics runner. `heartbeat/monitors/wrappers/summarizer/plugstatestat.go:161-169` sets `monitor.check_group` before execution so it can be used as the APM trace correlation identifier.

**Documentation impact:** `docs/reference/heartbeat/monitor-options.md:33-35` only documents the optional `service.name` APM integration and contains no explanation of the automatic synthetics journey/APM cross-linking, supported monitor context, or correlation through `monitor.check_group`. Users cannot discover or correctly configure/use this behavior.

## Suggested Actions

- [ ] Add an AWS S3 input section describing aggregated SQS health status, retry thresholds, delete/finalize failure semantics, and poison-pill/data-loss reporting for both legacy and v2 paths.
- [ ] Document Heartbeat synthetics/APM cross-linking, including prerequisites, supported monitor types/context, injected correlation metadata, and the relationship to `monitor.check_group`.

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

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

Contributor guide

Open the contributing guide

Research direction

Start by reading the referenced health.go and v2_sqs.go files alongside docs/reference/filebeat/filebeat-input-aws-s3.md, then review the synthetics executor and summarizer files with docs/reference/heartbeat/monitor-options.md. Done means both pages explain the reported health states, failure and data-loss semantics, APM cross-linking prerequisites, supported context, injected metadata, and monitor.check_group correlation.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.