[Heartbeat] Pass synthetics monitor context for APM cross-linking

[shahzad31]

What does this PR do?

When Heartbeat spawns the @elastic/synthetics runner for browser/api monitors, it now injects the monitor execution context as environment variables so the synthetics runner's APM plugin can cross-link a journey execution with the APM data of the application it traces:

• ELASTIC_SYNTHETICS_TRACE_ID — the monitor.check_group of the current attempt
• ELASTIC_SYNTHETICS_MONITOR_ID — stdfields.ID
• ELASTIC_SYNTHETICS_MONITOR_TYPE — stdfields.Type (browser/api)
• ELASTIC_SYNTHETICS_MONITOR_LOCATION — stdfields.RunFrom.ID

Only non-empty values are emitted so the synthetics agent can fall back to its own defaults.

Trace id == check_group

The trace id must equal the monitor.check_group published on the heartbeat documents so APM data can be joined back to the exact journey execution. monitor.check_group is owned by the summarizer (formatted as <uuid>-<attempt>) and was previously only written after the job ran. This PR sets it in the state plugins' BeforeEachEvent (before the synthetics process is spawned), and synthexec reads it off the event to use as the trace id. This keeps the two identical, including across retries (the root job re-runs with the bumped attempt). When run outside the summarizer (e.g. unit tests), it falls back to the synthexec stream enricher's own check group.

This is the Heartbeat side of the Synthetics ⇄ APM cross-linking effort and the counterpart to elastic/synthetics#595.

Why is it important?

It lets the Synthetics waterfall be correlated with APM traces of the monitored application, enabling end-to-end performance analysis across Elastic Observability. See elastic/apm#823.

Scope / follow-ups (intentionally out of this PR)

• The synthetics APM plugin only activates when apm.traceUrls is configured (see feat: support cross-linking synthetics & apm synthetics#595); enabling it from Heartbeat is a follow-up.
• APM agent + Kibana UI work tracked under Correlate Synthetics monitor execution with APM  apm#823.

Checklist

• Unit test for the env builder (TestSyntheticsCrosslinkEnv)
• Unit test for reading the check group off the event (TestCheckGroupFromEvent)
• Unit test for the state plugins setting monitor.check_group early (TestStateStatusPluginBeforeEachEventSetsCheckGroup)
• Manual end-to-end validation once the synthetics-side plugin enablement lands

How to test this PR locally

go test -tags synthetics -run 'TestSyntheticsCrosslinkEnv|TestCheckGroupFromEvent' ./x-pack/heartbeat/monitors/browser/synthexec/
go test ./heartbeat/monitors/wrappers/...

Related issues

• feat: support cross-linking synthetics & apm synthetics#595
• Correlate Synthetics monitor execution with APM  apm#823

[botelastic]

This pull request doesn't have a Team:<team> label.

[github-actions]

🤖 GitHub comments

Just comment with:

• run docs-build : Re-trigger the docs validation. (use unformatted text in the comment!)
• /test : Run the Buildkite pipeline.

[mergify]

This pull request does not have a backport label.
If this is a bug or security fix, could you label this PR @shahzad31? 🙏.
For such, you'll need to label your PR with:

• The upcoming major version of the Elastic Stack
• The upcoming minor version of the Elastic Stack (if you're not pushing a breaking change)

To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-8./d is the label to automatically backport to the 8./d branch. /d is the digit
• backport-active-all is the label that automatically backports to all active branches.
• backport-active-8 is the label that automatically backports to all active minor branches for the 8 major.
• backport-active-9 is the label that automatically backports to all active minor branches for the 9 major.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 27d73b9d-9c43-4e85-a252-6d382204c62e

📥 Commits

Reviewing files that changed from the base of the PR and between 24b3ef5 and 96a99b4.

📒 Files selected for processing (5)

• changelog/fragments/1780480871-heartbeat-synthetics-apm-crosslink-env.yaml
• heartbeat/monitors/wrappers/summarizer/plugstatestat.go
• heartbeat/monitors/wrappers/summarizer/plugstatestat_test.go
• x-pack/heartbeat/monitors/browser/synthexec/synthexec.go
• x-pack/heartbeat/monitors/browser/synthexec/synthexec_test.go

---

📝 Walkthrough

Walkthrough

commonSSP.setCheckGroup is added to plugstatestat.go, formatting monitor.check_group as <base-check-group>-<attempt> and writing it onto the beat.Event. Both BrowserStateStatusPlugin.BeforeEachEvent and LightweightStateStatusPlugin.BeforeEachEvent are updated to call this helper. In synthexec.go, a new checkGroupFromEvent function reads monitor.check_group from the event (falling back to senr.checkGroup), and syntheticsCrosslinkEnv builds ELASTIC_SYNTHETICS_* environment variables from it plus monitor identity/location fields. runCmd gains a traceID parameter and appends these vars to the subprocess environment. All logp.L() calls in synthexec.go are replaced with a new synthexecLog() helper. Tests and a changelog fragment are included.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

• 🛠️ Update Documentation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}