[Fleet] Document apm fleet integration

[jalvz]

Overview

The apm package will be released in 7.12 as experimental. Package versions have a version independent of the stack; for this release we will ship 0.1.0. Later we'll probably align with stack versioning.

The documentation template file is at https://github.com/elastic/apm-server/blob/master/apmpackage/apm/0.1.0/_dev/docs/README.template.md

Run make update to generate the actual readme file that will be shown in the APM integration page: https://github.com/elastic/apm-server/tree/master/apmpackage/apm/0.1.0/docs

Topics for consideration

Usage

• apm-server will use data streams with a new indexing strategy. Indices are named after event type, service name, and namespace. Details: https://docs.google.com/document/d/1y56a9fjkLi6Zen5qGC_JKYM9ljYpBA5W0fgdWilcwYc/edit?ts=5f6c1aab#

• The service name part of an index is case insensitive and with special characters removed.

• If customers don't use RUM, it is recommended that they run Elastic Agent (and therefore apm-server) on the edge machines.

• We do not support running apm-server under Elastic Agent standalone: https://www.elastic.co/guide/en/fleet/current/run-elastic-agent-standalone.html

• Sourcemaps need to be uploaded directly to Elasticsearch, not apm-server. In the future we might have something so users can upload sourcemaps to Kibana.

Limitations

• ILM: we install default ILM policies for all event types, but users need to query Elasticsearch directly to override them. Same for pipelines.

• Can't use an Elastic Agent enrolled in a previous release: [Fleet] handle API key upgrade/renewal kibana#85777

• No onboarding document: [APM] Getting started: Change logic to check whether APM Server was setup when running under fleet kibana#86462

• For sourcemaps and agent central config features customer need to create api keys and them enter those api keys in the apm policy editor. This will be improved in future releases.

• Not all settings are supported, the whole list is at https://github.com/elastic/apm-server/blob/master/apmpackage/apm/0.1.0/manifest.yml#L28
  Crucially, mem.queue.* settings are not supported (yet).

References

7.12 meta issue: #4558
GA meta issue: #4636

[bmorelli25]

Docs are going to be kinda all over the place while we figure out the best path forward. Here's what we're thinking of adding for 7.12:

• APM Server reference
  • Top-level TOC heading for the APM integration: docs: APM integration #4928
    • About
    • Limitations
    • Datastream naming recommendations
    • How to configure (linking out to Fleet user guide)
• Fleet user guide
  • APM/traces quickstart guide Traces quickstart observability-docs#426
  • All integrations will have their configs defined in the Fleet user guide. For the apm input, we'll source the content from the apm-server repo so it's easy to update. Eventually, this will (hopefully) be generated.
  • Top-level TOC heading for Data streams Add data stream docs to Fleet user guide observability-docs#429
    • Elastic Agent data stream naming scheme information
    • Deleting data
• APM integration
  • Minor cleanup, including adding links to relevant documentation pages. docs: APM integration #4928

Other tasks:

• Update ela.st links
• Add cross-doc links to both the obs-docs and apm-server repos Add missing links to APM integration observability-docs#451 & docs: Add additional APM integration information #4969
  - [ ] Add docs on how to upload a source map to ES We're going to hold off on this for now
• Add docs explaining how to edit templates, ILM, etc. docs: Add additional APM integration information #4969

@jalvz if you have concerns or recommendations, please let me know

[bmorelli25]

All documentation for 7.12 has been added.