2019-07-10 23:29:29 +02:00
|
|
|
[role="xpack"]
|
|
|
|
[[agent-configuration]]
|
|
|
|
=== APM Agent configuration
|
|
|
|
|
2019-11-20 16:36:59 +01:00
|
|
|
APM Agent configuration allows you to fine-tune your agent configuration directly in Kibana.
|
2019-07-10 23:29:29 +02:00
|
|
|
Best of all, changes are automatically propagated to your APM agents so there's no need to redeploy.
|
|
|
|
|
2019-11-20 16:36:59 +01:00
|
|
|
To get started, simply choose the services and environments you wish to configure.
|
|
|
|
The APM app will let you know when your configurations have been applied by your agents.
|
2019-07-10 23:29:29 +02:00
|
|
|
|
|
|
|
[role="screenshot"]
|
|
|
|
image::apm/images/apm-agent-configuration.png[APM Agent configuration in Kibana]
|
|
|
|
|
|
|
|
[float]
|
|
|
|
==== Precedence
|
|
|
|
|
|
|
|
Configurations set with APM Agent configuration take precedence over configurations set locally in the Agent.
|
|
|
|
However, if APM Server is slow to respond, is offline, reports an error, etc.,
|
|
|
|
APM agents will use local defaults until they're able to update the configuration.
|
|
|
|
For this reason, it is still important to set custom default configurations locally in each of your agents.
|
|
|
|
|
|
|
|
[float]
|
|
|
|
==== APM Server setup
|
|
|
|
|
|
|
|
This feature requires {apm-server-ref}/setup-kibana-endpoint.html[Kibana endpoint configuration] in APM Server.
|
|
|
|
|
|
|
|
Why is additional configuration needed in APM Server?
|
|
|
|
That's because APM Server acts as a proxy between the agents and Kibana.
|
|
|
|
Kibana communicates any changed settings to APM Server so that your agents only need to poll APM Server to determine which settings have changed.
|
|
|
|
|
|
|
|
[float]
|
|
|
|
==== Supported configurations
|
|
|
|
|
2019-11-20 16:36:59 +01:00
|
|
|
[float]
|
|
|
|
===== `CAPTURE_BODY`
|
|
|
|
|
|
|
|
added[7.5.0] Can be `"off"`, `"errors"`, `"transactions"`, or `"all"`. Defaults to `"off"`.
|
|
|
|
|
|
|
|
For transactions that are HTTP requests, the Agent can optionally capture the request body, e.g., POST variables.
|
|
|
|
Remember, request bodies often contain sensitive values like passwords, credit card numbers, etc.
|
|
|
|
If your service handles sensitive data, enable this feature with care.
|
|
|
|
Turning on body capturing can also significantly increase the overhead the overhead of the Agent,
|
|
|
|
and the Elasticsearch index size.
|
|
|
|
|
|
|
|
[float]
|
|
|
|
===== `TRANSACTION_MAX_SPANS`
|
|
|
|
|
|
|
|
added[7.5.0] A number between `0` and `32000`. Defaults to `500`.
|
|
|
|
|
|
|
|
Limit the number of spans that are recorded per transaction.
|
|
|
|
This is helpful in cases where a transaction creates a very high amount of spans, e.g., thousands of SQL queries.
|
|
|
|
Setting an upper limit will help prevent the Agent and the APM Server from being overloaded.
|
|
|
|
|
2019-07-10 23:29:29 +02:00
|
|
|
[float]
|
|
|
|
===== `TRANSACTION_SAMPLE_RATE`
|
|
|
|
|
|
|
|
added[7.3.0] A sample rate between `0.000` and `1.0`. Default configuration is `1.0` (100% of traces).
|
|
|
|
|
|
|
|
Adjusting the sampling rate controls what percent of requests are traced.
|
|
|
|
`1.0` means _all_ requests are traced. If you set the `TRANSACTION_SAMPLE_RATE` to a value below `1.0`,
|
|
|
|
the agent will randomly sample only a subset of transactions.
|
|
|
|
Unsampled transactions only record the name of the transaction, the overall transaction time, and the result.
|
2019-08-14 21:30:09 +02:00
|
|
|
|
|
|
|
IMPORTANT: In a distributed trace, the sampling decision is propagated by the initializing Agent.
|
|
|
|
This means if you're using multiple agents, only the originating service's sampling rate will be used.
|
|
|
|
Be sure to set sensible defaults in _all_ of your agents, especially the
|
|
|
|
{apm-rum-ref}/configuration.html#transaction-sample-rate[JavaScript RUM Agent].
|