You can now centralize the management of your Elastic APM agent configurations directly from Kibana, eliminating the need to manually edit configuration files on each service.
Let’s see this in action. Imagine you have a Java application monitored by the Elastic APM agent.
# Old way: manual config file
apm_server.url: "http://apm-server:8200"
service_name: "my-java-app"
environment: "production"
# ... many other options
Now, with central management, you’ll configure this through Kibana’s UI.
First, navigate to Observability -> APM. On the left-hand navigation, you’ll find Agent configurations.
Here, you can create a new configuration. Let’s call it java-app-defaults.
Within this configuration, you can set various agent properties. For example, to ensure all Java agents using this config send data to your APM Server at http://apm-server.elastic.co:8200, you’d enter http://apm-server.elastic.co:8200 into the APM Server URL field.
To set the default service name for all applications using this config, you’d type my-global-java-service into the Service name field.
And for the environment, you can set it to staging by entering staging in the Environment field.
You can configure almost every setting available in the agent’s elastic-apm.properties file (for Java) or its equivalent in other languages. This includes things like:
- Sampling: Set
Transaction sample rateto0.5to sample 50% of transactions. - Capture body: Enable
Capture bodyand setCapture body contenttoallto capture request and response bodies for debugging. - Custom labels: Add
Custom labelsliketeam: backendorregion: us-east-1. - Trace propagation headers: Specify
Trace propagation headersliketraceparent,tracestateif you need to propagate context across different tracing systems. - Disable features: Turn off specific features by setting
Enable metricstofalseorEnable distributed tracingtofalse.
Once you’ve created and saved your java-app-defaults configuration, you need to associate it with your actual APM agents. This is done by adding a specific JVM argument to your Java application’s startup command:
java -javaagent:/path/to/elastic-apm-agent.jar \
-Delastic.apm.agent_config.id="java-app-defaults" \
-Delastic.apm.service_name="my-specific-java-app" \
-Delastic.apm.environment="staging-us-east-1" \
-jar my-application.jar
Notice how we explicitly set the agent_config.id to java-app-defaults. This tells the agent to fetch its base configuration from Kibana. Any settings not explicitly overridden on the command line (or in an environment variable) will be inherited from the java-app-defaults configuration in Kibana.
This means if you later decide to change the APM Server URL for all your Java apps, you only need to update it in the java-app-defaults configuration in Kibana, and all your running agents will pick up the change on their next configuration refresh (which happens periodically).
The agent_config.id mechanism is how the agent knows which configuration to pull from Kibana. If you omit agent_config.id, the agent will fall back to reading its configuration from local files or environment variables, and Kibana’s central management will have no effect on that particular agent.
This central management works by the APM agent periodically polling Kibana for its assigned configuration. The agent uses its service_name and environment to identify which configuration is relevant. You can also assign configurations directly to specific agents using their unique application_id or service.node.name for more granular control.
One subtle but powerful aspect is how configuration precedence works. Settings defined directly on the agent (via JVM arguments, environment variables, or local config files) always override settings in a centrally managed configuration. This allows you to use central management for common defaults while still providing specific overrides for individual services or environments.
The next step after mastering central configuration is to explore how to automate the deployment of agents and their configurations using Elastic Fleet.