APM integration for Elastic Agent
editAPM integration for Elastic Agent
editThis functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
Elastic Agent is a single, unified way to add monitoring for logs, metrics, and other types of data to each host. The APM integration for Elastic Agent assigns the APM input to a specified policy, and installs Elasticsearch templates and ingest node pipelines for APM data. When Elastic Agent is assigned a policy with an APM input, Elastic Agent will run the APM Server binary locally and listen for APM data.
Get started
editReady to jump in? Read through the APM integration limitations, then head over to the quick start guide: Get application traces into the Elastic Stack.
Architecture
editIf RUM is enabled, you must run Elastic Agent centrally. If RUM is disabled, Elastic Agent can be run on edge machines. To do this, download and enroll an Elastic Agent on the same machines that your instrumented services run on.
Limitations
editThe APM integration has the following limitations:
- Index lifecycle management (ILM)
-
A default ILM policy, named
traces-apm.traces-default_policyis created for all event types. This policy moves indices to a warm data tier after 30 days. No default cold or delete data tier is defined. It is not possible to configure this policy in APM Server or Elastic Agent– it must be configured with Elasticsearch or Kibana. See Customize built-in ILM policies for more information. - Onboarding
- APM Server no longer writes an onboarding document when setting up.
-
Incompatible with
apm_userrole -
The built-in
apm_userrole is not compatible with the APM integration as it only provides read access toapm-*indices. The new data stream naming scheme does not follow this pattern, so users with theapm_userrole will not be able to viewapmdata.To grant a user access to APM data in Kibana, provide read access to the relevant indices listed in Data streams. You may also wish to grant users additional privileges for features like spaces and machine learning.
- Standalone mode
- Standalone mode is not currently supported. An Elastic Agent with the APM integration enabled must be managed by fleet.
- Service names
- Service names are case-insensitive and must be unique. See Service names for more information.
- Upgrading from prior Elastic Agent versions
- Due to changing API key permissions, an Elastic Agent enrolled before version 7.12 is not compatible with the APM integration. You must enroll a new Elastic Agent to use the integration.
Terminology
edit- Agents
-
Elastic Agent and APM agents are different components:
Elastic Agent is a single, unified agent that you can deploy to hosts or containers to collect data and send it to the Elastic Stack. Behind the scenes, Elastic Agent runs APM Server to listen for
apmdata.APM agents are open source libraries written in the same language as your service. You may only need one, or you might use all of them. You install them into your service as you would install any other library. They instrument your code and collect performance data and errors at runtime. This data is sent to APM Server.
- Central management/configuration
-
Fleet central management and APM agent central configuration are two different features that can be accessed in Kibana:
Fleet central management serves as the communication channel with your Elastic Agents; agents check in for the latest updates on a regular basis.
APM agent central configuration allows you to fine-tune your agent configuration from within the APM app. Changes are automatically propagated to your APM agents, so there’s no need to redeploy your services.
Package versioning
editThe APM package is versioned separately from the Elastic Stack.
The current version is 0.1.0. In the future, we may align with Elastic Stack versioning.