Core configuration optionsedit

activeedit

A boolean specifying if the agent should be active or not. If active, the agent will instrument incoming HTTP requests and track errors.

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

DefaultTypeDynamic

true

Boolean

true

Java System PropertiesProperty fileEnvironment

elastic.apm.active

active

ELASTIC_APM_ACTIVE

instrumentedit

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.

Note

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

DefaultTypeDynamic

true

Boolean

false

Java System PropertiesProperty fileEnvironment

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.

Note

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_instrumentationsedit.

DefaultTypeDynamic

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). Note: the above service name auto discovery mechanisms require APM Server 7.0+. 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 PropertiesProperty fileEnvironment

elastic.apm.service_name

service_name

ELASTIC_APM_SERVICE_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.

DefaultTypeDynamic

<none>

String

false

Java System PropertiesProperty fileEnvironment

elastic.apm.service_version

service_version

ELASTIC_APM_SERVICE_VERSION

environmentedit

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

Note

The APM UI does not fully support the environment setting yet. You can use the query bar to filter for a specific environment, but by default the environments will be mixed together. Also keep that in mind when creating alerts.

DefaultTypeDynamic

<none>

String

false

Java System PropertiesProperty fileEnvironment

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.

DefaultTypeDynamic

1.0

Double

true

Java System PropertiesProperty fileEnvironment

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.

DefaultTypeDynamic

500

Integer

true

Java System PropertiesProperty fileEnvironment

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.

Note

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

Note

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).

DefaultTypeDynamic

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

List

true

Java System PropertiesProperty fileEnvironment

elastic.apm.sanitize_field_names

sanitize_field_names

ELASTIC_APM_SANITIZE_FIELD_NAMES

disable_instrumentationsedit

A list of instrumentations which should be disabled. Valid options are annotations, apache-httpclient, concurrent, dispatcher-servlet, elasticsearch-restclient, executor, http-client, incubating, jax-rs, jax-ws, jdbc, jsf, okhttp, opentracing, public-api, render, scheduled, servlet-api, servlet-api-async, servlet-input-stream, servlet-service-name, spring-mvc, spring-resttemplate, spring-service-name, urlconnection. If you want to try out incubating features, set the value to an empty string.

DefaultTypeDynamic

incubating

Collection

false

Java System PropertiesProperty fileEnvironment

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.

DefaultTypeDynamic

(?-i)*Nested*Exception

List

true

Java System PropertiesProperty fileEnvironment

elastic.apm.unnest_exceptions

unnest_exceptions

ELASTIC_APM_UNNEST_EXCEPTIONS

trace_methods ( [1.3.0] Added in 1.3.0. Enhancements in 1.4.0 )edit

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

The syntax is modifier fully.qualified.class.Name#methodName(fully.qualified.parameter.Type). You can use wildcards for the class name, the method name and the parameter types. The * wildcard matches zero or more characters. That means that a wildcard in a package name also matches sub-packages Specifying the parameter types is optional. The modifier can be omitted or one of public, protected, private or *.

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#*
Note

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).

Note

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.

DefaultTypeDynamic

<none>

List

false

Java System PropertiesProperty fileEnvironment

elastic.apm.trace_methods

trace_methods

ELASTIC_APM_TRACE_METHODS