Add stats-to-mapping CLI for regenerating upstream apm-server field mappings

[carsonip]

Motivation/summary

The five files that hold apm-server's field mappings live in three external repositories:

• monitoring-beats.json and monitoring-beats-mb.json (elastic/elasticsearch stack-monitoring templates)
• metricbeat/module/beat/_meta/fields.yml and metricbeat/module/beat/stats/_meta/fields.yml (elastic/beats)
• elastic_agent/data_stream/apm_server_metrics/fields/beat-stats-fields.yml (elastic/integrations)

When apm-server adds, removes, or renames a metric, those five files must be hand-edited in three separate repos. The previously closed #13638 added a Python script that automated the regen by reading a single /stats snapshot and rewriting each file in place. That PR was closed without merging, leaving us back at hand-editing.

This PR ports the Python script to Go and homes it in apm-server at cmd/stats-to-mapping, so a developer can regenerate the upstream mappings by piping apm-server:5066/stats into the binary with the five file paths as arguments. No Python venv, no ruamel.yaml dependency.

This is the consumer side of the contract that #20993 (eager monitoring counters) restored: with that PR merged, a single /stats capture from a freshly started apm-server enumerates every counter the server defines, so stats-to-mapping produces a complete mapping set without needing to drive every error path during capture.

What this changes

• New cmd/stats-to-mapping Go program. Same five-file contract as the closed Python script. Output is intentionally not byte-equal to the Python original — the Go implementation byte-splices the unchanged regions of input files (preserving comments, quoting, and surrounding whitespace) and re-emits the modified subtrees with stdlib JSON / YAML, sorted alphabetically.
• goType recognises non-integer JSON numbers and emits type: float. The only such value today is apm-server.sampling.tail.storage.disk_usage_threshold_pct (introduced in #20464); upstream already types it as float, so this matches existing convention.
• Golden-file tests in cmd/stats-to-mapping/testdata/. The committed stats.json was captured from a TBS-enabled apm-server built from #20993's eager-monitoring-counters branch, so the goldens reflect the full enumerated metric set the tool will see in production once that PR ships.
• README at cmd/stats-to-mapping/README.md covering build, invocation, supported files, and how the goldens were generated.

Checklist

• Update CHANGELOG.asciidoc — n/a, dev tooling, not a user-facing apm-server change.
• Documentation has been updated — README is in cmd/stats-to-mapping/.

How to test these changes

go test ./cmd/stats-to-mapping/...
go vet ./cmd/stats-to-mapping/...

End-to-end against fresh upstream files:

go build -o /tmp/stats-to-mapping ./cmd/stats-to-mapping

# Capture stats from a running apm-server (TBS-enabled if you want the tail.storage.* fields):
curl -s http://127.0.0.1:5066/stats > /tmp/stats.json

# Run against local checkouts of the three upstream repos:
/tmp/stats-to-mapping \
  ~/elastic/elasticsearch/x-pack/plugin/core/template-resources/src/main/resources/monitoring-beats.json \
  ~/elastic/elasticsearch/x-pack/plugin/core/template-resources/src/main/resources/monitoring-beats-mb.json \
  ~/elastic/beats/metricbeat/module/beat/_meta/fields.yml \
  ~/elastic/beats/metricbeat/module/beat/stats/_meta/fields.yml \
  ~/elastic/integrations/packages/elastic_agent/data_stream/apm_server_metrics/fields/beat-stats-fields.yml \
  < /tmp/stats.json

# Inspect with `git diff` in each upstream repo.

Related issues

Supersedes the closed #13638. Unblocks the periodic upstream-mapping-sync work in #15533 and #13475. Best paired with #20993 so the captured /stats snapshot is the complete enumeration.

[github-actions]

🤖 GitHub comments

Just comment with:

• run docs-build : Re-trigger the docs validation. (use unformatted text in the comment!)

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 0a713d8

[mergify]

This pull request does not have a backport label. Could you fix it @carsonip? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

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

[carsonip]

Closing this in favor of elastic/apm-tools#245 — moving the tool to apm-tools, since the testdata goldens are ~10k lines and the rest of the active devtools live there. The drift problem this is part of is now tracked in #21000.