Core configuration optionsedit

recording ( [1.15.0] Added in 1.15.0. )edit

This option was available in older versions through the active key. The old key is still supported in newer versions, but it is now deprecated.

A boolean specifying if the agent should be recording or not. When recording, the agent instruments incoming HTTP requests, tracks errors and collects and sends metrics. When not recording, the agent works as a noop, not collecting data and not communicating with the APM sever, except for polling the central configuration endpoint. As this is a reversible switch, agent threads are not being killed when inactivated, but they will be mostly idle in this state, so the overhead should be negligible.

You can use this setting to dynamically disable Elastic APM at runtime.

dynamic config

Default Type Dynamic

true

Boolean

true

Java System Properties Property file Environment

elastic.apm.recording

recording

ELASTIC_APM_RECORDING

enabled ( [1.18.0] Added in 1.18.0. )edit

Setting to false will completely disable the agent, including instrumentation and remote config polling. If you want to dynamically change the status of the agent, use recording instead.

Default Type Dynamic

true

Boolean

false

Java System Properties Property file Environment

elastic.apm.enabled

enabled

ELASTIC_APM_ENABLED

instrument ( [1.0.0] Added in 1.0.0. Changing this value at runtime is possible since version 1.15.0 )edit

A boolean specifying if the agent should instrument the application to collect performance metrics for the app. When set to false, Elastic APM will not affect your application at all.

Both active and instrument needs to be true for instrumentation to be running.

Changing this value at runtime can slow down the application temporarily.

dynamic config

Default Type Dynamic

true

Boolean

true

Java System Properties Property file Environment

elastic.apm.instrument

instrument

ELASTIC_APM_INSTRUMENT

service_nameedit

This is used to keep all the errors and transactions of your service together and is the primary filter in the Elastic APM user interface.

The service name must conform to this regular expression: ^[a-zA-Z0-9 _-]+$. In less regexy terms: Your service name must only contain characters from the ASCII alphabet, numbers, dashes, underscores and spaces.

When relying on auto-discovery of the service name in Servlet environments (including Spring Boot), there is currently a caveat related to metrics. The consequence is that the Metrics tab of a service does not show process-global metrics like CPU utilization. The reason is that metrics are reported with the detected default service name for the JVM, for example tomcat-application. That is because there may be multiple web applications deployed to a single JVM/servlet container. However, you can view those metrics by selecting the tomcat-application service name, for example. Future versions of the Elastic APM stack will have better support for that scenario. A workaround is to explicitly set the service_name which means all applications deployed to the same servlet container will have the same name or to disable the corresponding *-service-name detecting instrumentations via disable_instrumentations ( [1.0.0] Added in 1.0.0. Changing this value at runtime is possible since version 1.15.0 ).

Service name auto discovery mechanisms require APM Server 7.0+.

Default Type Dynamic

For Spring-based application, uses the spring.application.name property, if set. For Servlet-based applications, uses the display-name of the web.xml, if available. Falls back to the servlet context path the application is mapped to (unless mapped to the root context). Falls back to the name of the main class or jar file. If the service name is set explicitly, it overrides all of the above.

String

false

Java System Properties Property file Environment

elastic.apm.service_name

service_name

ELASTIC_APM_SERVICE_NAME

service_node_name ( [1.11.0] Added in 1.11.0. )edit

If set, this name is used to distinguish between different nodes of a service, therefore it should be unique for each JVM within a service. If not set, data aggregations will be done based on a container ID (where valid) or on the reported hostname (automatically discovered or manually configured through hostname).

JVM metrics views rely on aggregations that are based on the service node name. If you have multiple JVMs installed on the same host reporting data for the same service name, you must set a unique node name for each in order to view metrics at the JVM level.

Metrics views can utilize this configuration since APM Server 7.5

Default Type Dynamic

<none>

String

false

Java System Properties Property file Environment

elastic.apm.service_node_name

service_node_name

ELASTIC_APM_SERVICE_NODE_NAME

service_versionedit

A version string for the currently deployed version of the service. If you don’t version your deployments, the recommended value for this field is the commit identifier of the deployed revision, e.g. the output of git rev-parse HEAD.

Default Type Dynamic

<none>

String

false

Java System Properties Property file Environment

elastic.apm.service_version

service_version

ELASTIC_APM_SERVICE_VERSION

hostname ( [1.10.0] Added in 1.10.0. )edit

Allows for the reported hostname to be manually specified. If unset the hostname will be looked up.

Default Type Dynamic

<none>

String

false

Java System Properties Property file Environment

elastic.apm.hostname

hostname

ELASTIC_APM_HOSTNAME

environmentedit

The name of the environment this service is deployed in, e.g. "production" or "staging".

Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See environment selector in the APM app for more information.

This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2.

Default Type Dynamic

<none>

String

false

Java System Properties Property file Environment

elastic.apm.environment

environment

ELASTIC_APM_ENVIRONMENT

transaction_sample_rate (performance)edit

By default, the agent will sample every transaction (e.g. request to your service). To reduce overhead and storage requirements, you can set the sample rate to a value between 0.0 and 1.0. We still record overall time and the result for unsampled transactions, but no context information, labels, or spans.

dynamic config

Default Type Dynamic

1.0

Double

true

Java System Properties Property file Environment

elastic.apm.transaction_sample_rate

transaction_sample_rate

ELASTIC_APM_TRANSACTION_SAMPLE_RATE

transaction_max_spans (performance)edit

Limits the amount 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 prevent overloading the agent and the APM server with too much work for such edge cases.

A message will be logged when the max number of spans has been exceeded but only at a rate of once every 5 minutes to ensure performance is not impacted.

dynamic config

Default Type Dynamic

500

Integer

true

Java System Properties Property file Environment

elastic.apm.transaction_max_spans

transaction_max_spans

ELASTIC_APM_TRANSACTION_MAX_SPANS

sanitize_field_names (security)edit

Sometimes it is necessary to sanitize the data sent to Elastic APM, e.g. remove sensitive data.

Configure a list of wildcard patterns of field names which should be sanitized. These apply for example to HTTP headers and application/x-www-form-urlencoded data.

This option supports the wildcard *, which matches zero or more characters. Examples: /foo/*/bar/*/baz*, *foo*. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive.

Data in the query string is considered non-sensitive, as sensitive information should not be sent in the query string. See https://www.owasp.org/index.php/Information_exposure_through_query_strings_in_url for more information

Review the data captured by Elastic APM carefully to make sure it does not capture sensitive information. If you do find sensitive data in the Elasticsearch index, you should add an additional entry to this list (make sure to also include the default entries).

dynamic config

Default Type Dynamic

password, passwd, pwd, secret, *key, *token*, *session*, *credit*, *card*, authorization, set-cookie

List

true

Java System Properties Property file Environment

elastic.apm.sanitize_field_names

sanitize_field_names

ELASTIC_APM_SANITIZE_FIELD_NAMES

disable_instrumentations ( [1.0.0] Added in 1.0.0. Changing this value at runtime is possible since version 1.15.0 )edit

A list of instrumentations which should be disabled. Valid options are annotations, apache-commons-exec, apache-httpclient, asynchttpclient, bootdelegation, concurrent, dubbo, elasticsearch-restclient, exception-handler, executor, executor-collection, experimental, fork-join, grails, grpc, hibernate-search, http-client, jax-rs, jax-ws, jdbc, jdk-httpclient, jedis, jms, jsf, kafka, lettuce, log4j, logging, micrometer, mongodb-client, okhttp, opentracing, process, public-api, quartz, redis, redisson, render, scala-future, scheduled, servlet-api, servlet-api-async, servlet-input-stream, slf4j, spring-mvc, spring-resttemplate, spring-service-name, spring-view-render, ssl-context, timer-task, urlconnection. If you want to try out experimental features, set the value to an empty string.

Changing this value at runtime can slow down the application temporarily.

dynamic config

Default Type Dynamic

experimental

Collection

true

Java System Properties Property file Environment

elastic.apm.disable_instrumentations

disable_instrumentations

ELASTIC_APM_DISABLE_INSTRUMENTATIONS

unnest_exceptionsedit

When reporting exceptions, un-nests the exceptions matching the wildcard pattern. This can come in handy for Spring’s org.springframework.web.util.NestedServletException, for example.

This option supports the wildcard *, which matches zero or more characters. Examples: /foo/*/bar/*/baz*, *foo*. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive.

dynamic config

Default Type Dynamic

(?-i)*Nested*Exception

List

true

Java System Properties Property file Environment

elastic.apm.unnest_exceptions

unnest_exceptions

ELASTIC_APM_UNNEST_EXCEPTIONS

ignore_exceptions ( [1.11.0] Added in 1.11.0. )edit

A list of exceptions that should be ignored and not reported as errors. This allows to ignore exceptions thrown in regular control flow that are not actual errors

This option supports the wildcard *, which matches zero or more characters. Examples: /foo/*/bar/*/baz*, *foo*. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive.

Examples:

  • com.mycompany.ExceptionToIgnore: using fully qualified name
  • *ExceptionToIgnore: using wildcard to avoid package name
  • *exceptiontoignore: case-insensitive by default

Exception inheritance is not supported, thus you have to explicitly list all the thrown exception types

dynamic config

Default Type Dynamic

<none>

List

true

Java System Properties Property file Environment

elastic.apm.ignore_exceptions

ignore_exceptions

ELASTIC_APM_IGNORE_EXCEPTIONS

capture_body (performance)edit

For transactions that are HTTP requests, the Java agent can optionally capture the request body (e.g. POST variables). For transactions that are initiated by receiving a message from a message broker, the agent can capture the textual message body.

If the HTTP request or the message has a body and this setting is disabled, the body will be shown as [REDACTED].

This option is case-insensitive.

Currently, only UTF-8 encoded plain text HTTP content types are supported. The option capture_body_content_types ( [1.5.0] Added in 1.5.0. performance) determines which content types are captured.

Request bodies often contain sensitive values like passwords, credit card numbers etc. If your service handles data like this, we advise to only enable this feature with care. Turning on body capturing can also significantly increase the overhead in terms of heap usage, network utilisation and Elasticsearch index size.

dynamic config

Valid options: off, errors, transactions, all

Default Type Dynamic

OFF

EventType

true

Java System Properties Property file Environment

elastic.apm.capture_body

capture_body

ELASTIC_APM_CAPTURE_BODY

capture_headers (performance)edit

If set to true, the agent will capture HTTP request and response headers (including cookies), as well as messages' headers/properties when using messaging frameworks like Kafka or JMS.

Setting this to false reduces network bandwidth, disk space and object allocations.

dynamic config

Default Type Dynamic

true

Boolean

true

Java System Properties Property file Environment

elastic.apm.capture_headers

capture_headers

ELASTIC_APM_CAPTURE_HEADERS

global_labels ( [1.7.0] Added in 1.7.0. Requires APM Server 7.2+ )edit

Labels added to all events, with the format key=value[,key=value[,...]]. Any labels set by application via the API will override global labels with the same keys.

This feature requires APM Server 7.2+

Default Type Dynamic

<none>

Map

false

Java System Properties Property file Environment

elastic.apm.global_labels

global_labels

ELASTIC_APM_GLOBAL_LABELS

classes_excluded_from_instrumentationedit

Use to exclude specific classes from being instrumented. In order to exclude entire packages, use wildcards, as in: com.project.exclude.* This option supports the wildcard *, which matches zero or more characters. Examples: /foo/*/bar/*/baz*, *foo*. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive.

Default Type Dynamic

<none>

List

false

Java System Properties Property file Environment

elastic.apm.classes_excluded_from_instrumentation

classes_excluded_from_instrumentation

ELASTIC_APM_CLASSES_EXCLUDED_FROM_INSTRUMENTATION

trace_methods ( [1.0.0] Added in 1.0.0. Changing this value at runtime is possible since version 1.15.0 )edit

A list of methods for which to create a transaction or span.

If you want to monitor a large number of methods, use profiling_inferred_spans_enabled instead.

This works by instrumenting each matching method to include code that creates a span for the method. While creating a span is quite cheap in terms of performance, instrumenting a whole code base or a method which is executed in a tight loop leads to significant overhead.

Using a pointcut-like syntax, you can match based on

  • Method modifier (optional)
    Example: public, protected, private or *
  • Package and class name (wildcards include sub-packages)
    Example: org.example.*
  • Method name (optional since 1.4.0)
    Example: myMeth*d
  • Method argument types (optional)
    Example: (*lang.String, int[])
  • Classes with a specific annotation (optional)
    Example: @*ApplicationScoped
  • Classes with a specific annotation that is itself annotated with the given meta-annotation (optional)
    Example: @@javax.enterpr*se.context.NormalScope

The syntax is modifier @fully.qualified.AnnotationName fully.qualified.ClassName#methodName(fully.qualified.ParameterType).

A few examples:

  • org.example.* [1.4.0] Added in 1.4.0. Omitting the method is possible since 1.4.0
  • org.example.*#* (before 1.4.0, you need to specify a method matcher)
  • org.example.MyClass#myMethod
  • org.example.MyClass#myMethod()
  • org.example.MyClass#myMethod(java.lang.String)
  • org.example.MyClass#myMe*od(java.lang.String, int)
  • private org.example.MyClass#myMe*od(java.lang.String, *)
  • * org.example.MyClas*#myMe*od(*.String, int[])
  • public org.example.services.*Service#*
  • public @java.inject.ApplicationScoped org.example.*
  • public @java.inject.* org.example.*
  • public @@javax.enterprise.context.NormalScope org.example.*

Only use wildcards if necessary. The more methods you match the more overhead will be caused by the agent. Also note that there is a maximum amount of spans per transaction (see transaction_max_spans).

The agent will create stack traces for spans which took longer than span_frames_min_duration. When tracing a large number of methods (for example by using wildcards), this may lead to high overhead. Consider increasing the threshold or disabling stack trace collection altogether.

Common configurations:

Trace all public methods in CDI-Annotated beans:

public @@javax.enterprise.context.NormalScope your.application.package.*
public @@javax.inject.Scope your.application.package.*

This method is only available in the Elastic APM Java Agent.

Changing this value at runtime can slow down the application temporarily.

dynamic config

Default Type Dynamic

<none>

List

true

Java System Properties Property file Environment

elastic.apm.trace_methods

trace_methods

ELASTIC_APM_TRACE_METHODS

trace_methods_duration_threshold ( [1.7.0] Added in 1.7.0. )edit

If trace_methods config option is set, provides a threshold to limit spans based on duration. When set to a value greater than 0, spans representing methods traced based on trace_methods will be discarded by default. Such methods will be traced and reported if one of the following applies: - This method’s duration crossed the configured threshold. - This method ended with Exception. - A method executed as part of the execution of this method crossed the threshold or ended with Exception. - A "forcibly-traced method" (e.g. DB queries, HTTP exits, custom) was executed during the execution of this method. Set to 0 to disable.

Transactions are never discarded, regardless of their duration. This configuration affects only spans. In order not to break span references, all spans leading to an async operation or an exit span (such as a HTTP request or a DB query) are never discarded, regardless of their duration.

If this option and span_min_duration are both configured, the higher of both thresholds will determine which spans will be discarded.

Supports the duration suffixes ms, s and m. Example: 0ms. The default unit for this option is ms.

Default Type Dynamic

0ms

TimeDuration

false

Java System Properties Property file Environment

elastic.apm.trace_methods_duration_threshold

trace_methods_duration_threshold

ELASTIC_APM_TRACE_METHODS_DURATION_THRESHOLD

central_config ( [1.8.0] Added in 1.8.0. )edit

When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration.

dynamic config

Default Type Dynamic

true

Boolean

true

Java System Properties Property file Environment

elastic.apm.central_config

central_config

ELASTIC_APM_CENTRAL_CONFIG

breakdown_metrics ( [1.8.0] Added in 1.8.0. )edit

Disables the collection of breakdown metrics (span.self_time)

Default Type Dynamic

true

Boolean

false

Java System Properties Property file Environment

elastic.apm.breakdown_metrics

breakdown_metrics

ELASTIC_APM_BREAKDOWN_METRICS

config_file ( [1.8.0] Added in 1.8.0. )edit

Sets the path of the agent config file. The special value _AGENT_HOME_ is a placeholder for the folder the elastic-apm-agent.jar is in. The file has to be on the file system. You can not refer to classpath locations.

this option can only be set via system properties, environment variables or the attacher options.

Default Type Dynamic

_AGENT_HOME_/elasticapm.properties

String

false

Java System Properties Property file Environment

elastic.apm.config_file

config_file

ELASTIC_APM_CONFIG_FILE

use_elastic_traceparent_header ( [1.14.0] Added in 1.14.0. )edit

To enable distributed tracing, the agent adds trace context headers to outgoing requests (like HTTP requests, Kafka records, gRPC requests etc.). These headers (traceparent and tracestate) are defined in the W3C Trace Context specification.

When this setting is true, the agent will also add the header elastic-apm-traceparent for backwards compatibility with older versions of Elastic APM agents.

dynamic config

Default Type Dynamic

true

Boolean

true

Java System Properties Property file Environment

elastic.apm.use_elastic_traceparent_header

use_elastic_traceparent_header

ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER

span_min_duration ( [1.16.0] Added in 1.16.0. )edit

Sets the minimum duration of spans. Spans that execute faster than this threshold are attempted to be discarded.

The attempt fails if they lead up to a span that can’t be discarded. Spans that propagate the trace context to downstream services, such as outgoing HTTP requests, can’t be discarded. Additionally, spans that lead to an error or that may be a parent of an async operation can’t be discarded.

However, external calls that don’t propagate context, such as calls to a database, can be discarded using this threshold.

dynamic config

Supports the duration suffixes ms, s and m. Example: 0ms. The default unit for this option is ms.

Default Type Dynamic

0ms

TimeDuration

true

Java System Properties Property file Environment

elastic.apm.span_min_duration

span_min_duration

ELASTIC_APM_SPAN_MIN_DURATION