Core configuration options

edit

Recording ( [1.7.0] Added in 1.7.0. )

edit

dynamic config

A boolean specifying if the agent should be recording or not. When recording, the agent captures 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 server, except for polling the central configuration endpoint. As this is a reversible switch, agent threads are not 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.

Setting Recording to false influences the behavior of the Public API. When the agent is not active it won’t keep track of transactions, spans and any related properties on those.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_RECORDING

ElasticApm:Recording

Default Type

true

Boolean

Enabled ( [1.7.0] Added in 1.7.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.

Setting Enabled to false influences the behavior of the Public API. When the agent is not active it won’t keep track of transactions, spans and any related properties on those.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_ENABLED

ElasticApm:Enabled

Default Type

true

Boolean

ServiceName

edit

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. Characters in service name which don’t match regular expression will be replaced by _ symbol.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SERVICE_NAME

ElasticApm:ServiceName

Default Type

Name of the entry assembly

String

ServiceNodeName ( [1.3] Added in 1.3. )

edit

Optional name used to differentiate between nodes in a service. If not set, data aggregations will be done based on a container ID (where valid) or on the reported hostname (automatically discovered).

This feature requires APM Server versions >= 7.5

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SERVICE_NODE_NAME

ElasticApm:ServiceNodeName

Default Type

<none>

String

ServiceVersion

edit

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.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SERVICE_VERSION

ElasticApm:ServiceVersion

Default Type

Informational version of the entry assembly

String

HostName ( [1.7] Added in 1.7. )

edit

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

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_HOSTNAME

ElasticApm:HostName

Default Type

<none>

String

Environment ( [1.1] Added in 1.1. )

edit

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 Kibana UI 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.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_ENVIRONMENT

ElasticApm:Environment

Default Type

See note below

String

On ASP.NET Core application the agent uses EnvironmentName from IHostingEnvironment as default environment name.

TransactionSampleRate

edit

dynamic config

By default, the agent will sample every transaction (e.g. a 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. The agent will still record the overall time and result for unsampled transactions, but no context information, labels, or spans will be recorded.

When parsing the value for this option, the agent doesn’t consider the current culture. It also expects that a period (.) is used to separate the integer and the fraction of a floating-point number.

This setting can be changed after agent’s start.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_TRANSACTION_SAMPLE_RATE

ElasticApm:TransactionSampleRate

Default Type

1.0

Double

TransactionMaxSpans (performance) ( [1.1.1] Added in 1.1.1. )

edit

dynamic config

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, for example, thousands of SQL queries. Setting an upper limit helps prevent overloading the Agent and APM server in these edge cases.

A value of 0 means that spans will never be collected. Setting -1 means that spans will never be dropped. The Agent will revert to the default value if the value is set below -1.

This setting can be changed after agent’s start.

Environment variable name IConfiguration key

ELASTIC_APM_TRANSACTION_MAX_SPANS

ElasticApm:TransactionMaxSpans

Default Type

500

Integer

CentralConfig ( [1.1] Added in 1.1. )

edit

If set to true, the agent makes periodic requests to the APM Server to fetch the latest APM Agent configuration.

Environment variable name IConfiguration key

ELASTIC_APM_CENTRAL_CONFIG

ElasticApm:CentralConfig

Default Type

true

Boolean

SanitizeFieldNames ( [1.2] Added in 1.2. )

edit

dynamic config

Sometimes it is necessary to sanitize, i.e., remove, sensitive data sent to Elastic APM. This config accepts 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 setting only applies to values that are captured automatically by the agent. If you capture the request body manually with the public API, this configuration doesn’t apply, and the agent won’t sanitize the body.

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

You should review the data captured by Elastic APM carefully to make sure it does not contain sensitive information. If you do find sensitive data in your Elasticsearch index, you should add an additional entry to this list. Make sure to include the default entries as well, as setting a value here will overwrite the defaults.

Data in the query string is considered non-sensitive, as sensitive information should not be sent in the query string. See owasp.org for more information.

Environment variable name IConfiguration key

ELASTIC_APM_SANITIZE_FIELD_NAMES

ElasticApm:SanitizeFieldNames

Default Type

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

List<string>

GlobalLabels ( [1.2] Added in 1.2. )

edit

Labels added to all events. Labels are key=value pairs, where key is the label name and value is the label value. Separate multiple labels with a comma. For example, label1=value1,label2=value2. Any labels set by the application via the agent’s public API will override global labels with the same keys.

Environment variable name IConfiguration key

ELASTIC_APM_GLOBAL_LABELS

ElasticApm:GlobalLabels

Default Type

<empty map>

Map of string to string

This option requires APM Server 7.2 or later. It will have no effect on older versions.