Skip to content

Latest commit

 

History

History
1290 lines (977 loc) · 48.1 KB

configuration.asciidoc

File metadata and controls

1290 lines (977 loc) · 48.1 KB
Note
 For the best reading experience, please view this documentation at elastic.co.

Configuration

Utilize configuration options to adapt the Elastic APM agent to your needs. There are multiple configuration sources, each with different naming conventions for the property key.

By default, the agent uses environment variables. Additionally, on ASP.NET Core, the agent can plug into the Microsoft.Extensions.Configuration infrastructure.

Dynamic configuration

Configuration options that are marked with the dynamic config badge can be changed at runtime when set from a supported source.

The .NET Agent supports {apm-app-ref}/agent-configuration.html[Central configuration], which allows you to fine-tune certain configurations via the APM app. This feature is enabled in the Agent by default, with CentralConfig (added[1.1]).

Configuration on ASP.NET Core

The UseElasticApm() extension method offers an overload to pass an IConfiguration instance to the APM Agent. To use this type of setup, which is typical in an ASP.NET Core application, your application’s Startup.cs file should contain code similar to the following:

using Elastic.Apm.AspNetCore;

public class Startup
{
    private readonly IConfiguration _configuration;

    public Startup(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        //Registers the agent with an IConfiguration instance:
        app.UseElasticApm(_configuration);

        //Rest of the Configure() method...
    }
}

With this setup, the Agent is able to be configured in the same way as any other library in your application. For example, any configuration source that has been configured on the IConfiguration instance being passed to the APM Agent can be used to set Agent configuration values.

More information is available in the official Microsoft .NET Core configuration docs You can find the key for each APM configuration option in this documentation, under the IConfiguration or Web.config key column of the option’s description.

Note
 It is also possible to call UseElasticApm() without the overload. In this case, the agent will only read configurations from environment variables.
Note
 The UseElasticApm method only turns on ASP.NET Core monitoring. To turn on tracing for everything supported by the Agent on .NET Core, including HTTP and database monitoring, use the UseAllElasticApm method from the Elastic.Apm NetCoreAll package. Learn more in ASP.NET Core setup.

Sample configuration file

Here is a sample appsettings.json configuration file for a typical ASP.NET Core application that has been activated with UseElasticApm(). There are two important takeaways, which are listed as callouts below the example:

{
  "Logging": {
    "LogLevel": { (1)
      "Default": "Warning",
      "Elastic.Apm": "Debug"
    }
  },
  "AllowedHosts": "*",
  "ElasticApm": (2)
    {
      "ServerUrl":  "http://myapmserver:8200",
      "SecretToken":  "apm-server-secret-token",
      "TransactionSampleRate": 1.0
    }
}

  1. With ASP.NET Core, you must set LogLevel for the internal APM logger in the standard Logging section with the Elastic.Apm category name.

  2. The configurations below ElasticApm are fetched by the agent if the corresponding IConfiguration is passed to the agent.

In certain scenarios—​like when you’re not using ASP.NET Core—​you won’t activate the agent with the UseElasticApm() method. In this case, set the agent log level with ElasticApm:LogLevel, as shown in the following appsettings.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ElasticApm":
    {
      "LogLevel":  "Debug",
      "ServerUrl":  "http://myapmserver:8200",
      "SecretToken":  "apm-server-secret-token",
      "TransactionSampleRate": 1.0
    }
}

Configuration for Windows Services

Configuration for Windows services can be provided by setting environment variables for the specific Windows service in the Windows registry. With PowerShell

$environment = [string[]]@(
  "ELASTIC_APM_SERVER_URL=http://localhost:8200", (1)
  "ELASTIC_APM_TRANSACTION_SAMPLE_RATE=1",
  "ELASTIC_APM_ENVIRONMENT=Production",
  "ELASTIC_APM_SERVICE_NAME=MyWindowsService")

Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<service-name> -Name Environment -Value $environment (2)

  1. define the environment variables to use for the Windows service

  2. <service-name> is the name of the Windows service.

The service must then be restarted for the change to take effect

Restart-Service <service-name>

Configuration on ASP.NET

When monitoring ASP.NET applications the agent uses two sources of configuration:

  • Web.config <appSettings> section

  • Environment variables

Web.config takes precedence over environment variables which means that the agent tries first to find a configuration option value by its key in Web.config. If it’s not present, then the agent tries to look for it among environment variables. If it’s not present, the agent falls back to the options default value.

You can find the key of each configuration option in the IConfiguration or Web.config key column of the corresponding option’s description.

Sample configuration file

Below is a sample Web.config configuration file for a ASP.NET application.

<?xml version="1.0" encoding="utf-8"?>
<!-- ... -->
<configuration>
    <!-- ... -->
    <appSettings>
        <!-- ... -->
        <add key="ElasticApm:ServerUrl" value="https://my-apm-server:8200" />
        <add key="ElasticApm:SecretToken" value="apm-server-secret-token" />
        <!-- ... -->
    </appSettings>
    <!-- ... -->
</configuration>

Additionally, on ASP.NET, you can implement your own configuration reader. To do this, implement the IConfigurationReader interface from the Elastic.Apm.Config namespace. Once implemented, you can use the FullFrameworkConfigurationReaderType setting.

FullFrameworkConfigurationReaderType

This setting is .NET Full Framework only.

This setting can point an agent to a custom IConfigurationReader implementation and the agent will read configuration from your IConfigurationReader implementation.

Use type name in AssemblyQualifiedName format (e.g: MyClass, MyNamespace).

Environment variable name Web.config key

ELASTIC_APM_FULL_FRAMEWORK_CONFIGURATION_READER_TYPE

ElasticApm:FullFrameworkConfigurationReaderType
Default Type

None

String

If this setting is set in both the web.config file and as an environment variable, then the web.config file has precedence.

Core configuration options

Recording (added[1.7.0])

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, where it does not collect data or communicate with the APM server, except for polling the central configuration endpoint. This is a reversible switch, so the agent threads are not killed when deactivated, but they will be mostly idle in this state, so the overhead should be negligible.

Use this setting to dynamically disable Elastic APM at runtime.

Warning
 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.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_RECORDING

ElasticApm:Recording
Default Type

true

Boolean

Enabled (added[1.7.0])

Setting this 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.

Warning
 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.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_ENABLED

ElasticApm:Enabled
Default Type

true

Boolean

ServiceName

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.

Note
 The service name must conform to this regular expression: ^[a-zA-Z0-9 -]+$. In other words, your service name must only contain characters from the ASCII alphabet, numbers, dashes, underscores, and spaces. Characters in service names that don’t match the regular expression will be replaced with the symbol.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SERVICE_NAME

ElasticApm:ServiceName
Default Type

Name of the entry assembly

String

ServiceNodeName (added[1.3])

This is an optional name used to differentiate between nodes in a service. If this is not set, data aggregations are done based on a container ID (where valid) or on the reported hostname (automatically discovered).

Note
 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

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 (added[1.7])

This allows for the reported hostname to be manually specified. If this is not set, the hostname will be looked up.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_HOSTNAME

ElasticApm:HostName
Default Type

<none>

String

Environment (added[1.1])

The name of the environment that 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 {apm-app-ref}/filters.html#environment-selector[environment selector] in the Kibana UI for more information.

Note
 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
Note
 On ASP.NET Core application the agent uses EnvironmentName from IHostingEnvironment as default environment name.

TransactionSampleRate

By default, the agent samples every transaction (e.g. a request to your service). To reduce overhead and storage requirements, 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.

Note
 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 the agent starts.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_TRANSACTION_SAMPLE_RATE

ElasticApm:TransactionSampleRate
Default Type

1.0

Double

TransactionMaxSpans (performance) (added[1.1.1])

This limits the amount of spans that are recorded per transaction. This is helpful when 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.

Note
 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 starts.

Environment variable name IConfiguration key

ELASTIC_APM_TRANSACTION_MAX_SPANS

ElasticApm:TransactionMaxSpans
Default Type

500

Integer

CentralConfig (added[1.1])

If set to true, the agent makes periodic requests to the APM Server to fetch the latest {apm-app-ref}/agent-configuration.html[APM Agent configuration].

Environment variable name IConfiguration key

ELASTIC_APM_CENTRAL_CONFIG

ElasticApm:CentralConfig
Default Type

true

Boolean

SanitizeFieldNames (added[1.2])

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 to HTTP headers and application/x-www-form-urlencoded data.

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

Please be sure to 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 {es} index, add an additional entry to this list. Setting a value here will overwrite the defaults, so be sure to include the default entries as well.

Note
 Sensitive information should not be sent in the query string. Data in the query string is considered non-sensitive. 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, auth, set-cookie

Comma separated string

GlobalLabels (added[1.2])

Labels are added to all events with the format key=value[,key=value[,…​]]. 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
Note
 This option requires APM Server 7.2 or later. It will have no effect on older versions.

SpanCompressionEnabled (added[1.14])

Setting this option to true will enable span compression feature. Span compression reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that some information such as DB statements of all the compressed spans will not be collected.

Environment variable name IConfiguration key

ELASTIC_APM_SPAN_COMPRESSION_ENABLED

ElasticApm:SpanCompressionEnabled
Default Type

true

Boolean

SpanCompressionExactMatchMaxDuration (added[1.14])

Consecutive spans that are exact match and that are under this threshold will be compressed into a single composite span. This option does not apply to composite spans. This reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that the DB statements of all the compressed spans will not be collected.

Environment variable name IConfiguration key

ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION

ElasticApm:SpanCompressionExactMatchMaxDuration
Default Type

50ms

TimeDuration

SpanCompressionSameKindMaxDuration (added[1.14])

Consecutive spans to the same destination that are under this threshold will be compressed into a single composite span. This option does not apply to composite spans. This reduces the collection, processing, and storage overhead, and removes clutter from the UI. The tradeoff is that the DB statements of all the compressed spans will not be collected.

Environment variable name IConfiguration key

ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION

ElasticApm:SpanCompressionSameKindMaxDuration
Default Type

5ms

TimeDuration

ExitSpanMinDuration (added[1.14])

Sets the minimum duration of exit spans. Exit spans with a duration lesser than this threshold are attempted to be discarded. If the exit span is equal or greater the threshold, it should be kept. In some cases exit spans cannot be discarded. For example, spans that propagate the trace context to downstream services, such as outgoing HTTP requests, can’t be discarded. However, external calls that don’t propagate context, such as calls to a database, can be discarded using this threshold. Additionally, spans that lead to an error can’t be discarded.

Environment variable name IConfiguration key

ELASTIC_APM_EXIT_SPAN_MIN_DURATION

ElasticApm:ExitSpanMinDuration
Default Type

1ms

TimeDuration

Reporter configuration options

ServerUrl

The URL for your APM Server. The URL must be fully qualified, including protocol (http or https) and port.

Important
 Use of ServerUrls is deprecated. Use ServerUrl.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SERVER_URL

ElasticApm:ServerUrl
Default Type

http://localhost:8200

String

SecretToken

A string used to ensure that only your agents can send data to your APM server.

Both the agents and the APM server have to be configured with the same secret token. Use this setting if the APM Server requires a secret token, for example, when using our hosted {es} Service on Elastic Cloud.

Warning
 The SecretToken is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SECRET_TOKEN

ElasticApm:SecretToken
Default Type

<none>

String

ApiKey (added[1.4])

A base64-encoded string used to ensure that only your agents can send data to your APM server. You must have created the API key using the APM server’s {apm-guide-ref}/api-key.html[command line tool].

Note
 This feature is fully supported in the APM Server versions >= 7.6.
Warning
 The APIKey is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_API_KEY

ElasticApm:ApiKey
Default Type

<none>

A base64-encoded string

VerifyServerCert (added[1.3])

By default, the agent verifies the SSL certificate if you use an HTTPS connection to the APM server.

Verification can be disabled by changing this setting to false.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_VERIFY_SERVER_CERT

ElasticApm:VerifyServerCert
Default Type

true

Boolean

ServerCert (added[1.9])

The path to a PEM-encoded certificate used for SSL/TLS by APM server. Used to perform validation through certificate pinning.

This can be specified when using a certificate signed by a Certificate Authority (CA) that is not in the trust store, such as a self-signed certificate.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SERVER_CERT

ElasticApm:ServerCert
Default Type

<none>

String

FlushInterval (added[1.1])

The maximal amount of time events are held in the queue until there is enough to send a batch. It’s possible for a batch to contain less than MaxBatchEventCount events if there are events that need to be sent out because they were held for too long. A lower value will increase the load on your APM server, while a higher value can increase the memory pressure on your app. A higher value also impacts the time until transactions are indexed and searchable in Elasticsearch.

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

If FlushInterval is set to 0 (or 0s, 0ms, etc.) and there’s no event sending operation still in progress, then the Agent won’t hold events in the queue and will send them immediately.

Setting FlushInterval to a negative value (for example -1, -54s, -89ms, etc.) is invalid and in that case agent uses the default value instead.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_FLUSH_INTERVAL

ElasticApm:FlushInterval
Default Type

10s

TimeDuration

MaxBatchEventCount (added[1.1])

The maximum number of events to send in a batch. It’s possible for a batch to contain less then the maximum events if there are events that need to be sent out because they were held for too long (see FlushInterval).

Setting MaxBatchEventCount to 0 or a negative value is invalid and the Agent will use the default value instead.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_MAX_BATCH_EVENT_COUNT

ElasticApm:MaxBatchEventCount
Default Type

10

Integer

MaxQueueEventCount (added[1.1])

The maximum number of events to hold in the queue as candidates to be sent. If the queue is at its maximum capacity then the agent discards the new events until the queue has free space.

Setting MaxQueueEventCount to 0 or a negative value is invalid and the Agent will use the default value instead.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_MAX_QUEUE_EVENT_COUNT

ElasticApm:MaxQueueEventCount
Default Type

1000

Integer

MetricsInterval (added[1.0.0-beta1])

The interval at which the agent sends metrics to the APM Server. This must be at least 1s. Set this to 0s to deactivate.

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

Default Type

30s

TimeDuration
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_METRICS_INTERVAL

ElasticApm:MetricsInterval

DisableMetrics (added[1.3.0])

This disables the collection of certain metrics. If the name of a metric matches any of the wildcard expressions, it will not be collected. Example: foo.,bar.

You can find the name of the available metrics in [metrics].

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

<none>

Comma separated string
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_DISABLE_METRICS

ElasticApm:DisableMetrics

CloudProvider (added[1.7.0])

Specify which cloud provider should be assumed for metadata collection. By default, the agent attempts to detect the cloud provider and, if that fails, uses trial and error to collect the metadata.

Valid options are "auto", "aws", "gcp", "azure", and "none". If this config value is set to "none", no cloud metadata will be collected. If set to any of "aws", "gcp", or "azure", attempts to collect metadata will only be performed from the chosen provider.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_CLOUD_PROVIDER

ElasticApm:CloudProvider
Default Type

auto

String

HTTP configuration options

CaptureBody (performance) (added[1.0.1])

For transactions that are HTTP requests, the agent can optionally capture the request body, e.g., POST variables. If the request has a body and this setting is disabled, the body will be shown as [REDACTED]. This option is case-insensitive.

Important

To allow capturing request bodies, the agent sets AllowSynchronousIO to true on a per request basis in ASP.NET Core, since capturing can occur in synchronous code paths.

With ASP.NET Core 3.0 onwards, AllowSynchronousIO is false by default because a large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the application unresponsive. If your application becomes unresponsive with this feature enabled, consider disabling capturing.
Warning

Request bodies often contain sensitive values like passwords and credit card numbers. 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 utilization, and Elasticsearch index size.

Possible options are off, errors, transactions and all:

  • off - request bodies will never be reported

  • errors - request bodies will only be reported with errors

  • transactions - request bodies will only be reported with request transactions

  • all - request bodies will be reported with both errors and request transactions

This setting can be changed after the agent starts.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_CAPTURE_BODY

ElasticApm:CaptureBody
Default Type

off

String

CaptureBodyContentTypes (performance) (added[1.0.1])

Configures the content types to be captured.

This option supports the wildcard , which matches zero or more characters. Examples: /foo//bar//baz, foo. Matching is case insensitive.

This setting can be changed after the agent starts.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_CAPTURE_BODY_CONTENT_TYPES

ElasticApm:CaptureBodyContentTypes
Default Type

application/x-www-form-urlencoded*, text/, application/json, application/xml*

Comma separated string

CaptureHeaders (performance)

If set to true, the agent will capture request and response headers, including cookies.

Note
 Setting this to false reduces memory allocations, network bandwidth, and disk space used by {es}.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_CAPTURE_HEADERS

ElasticApm:CaptureHeaders
Default Type

true

Boolean

TraceContinuationStrategy (performance) (added[1.17.0])

Valid options: continue, restart, restart_external.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_TRACE_CONTINUATION_STRATEGY

ElasticApm:TraceContinuationStrategy
Default Type

true

String

The traceparent header of requests that are traced by the Elastic APM .NET Agent might have been added by a 3rd party component.

This situation becomes more and more common as the w3c trace context gets adopted. In such cases you may end up with traces where part of the trace is outside of Elastic APM.

In order to handle this properly, the agent offers trace continuation strategies with the following values and behavior:

  • continue: The agent takes the traceparent header as it is and applies it to the new transaction.

  • restart: The agent always creates a new trace with a new trace id. In this case the agent creates a span link in the new transaction pointing to the original traceparent.

  • restart_external: The agent first checks the tracestate header. If the header contains the es vendor flag (which means the request is coming from a service monitored by an Elastic APM Agent), it’s treated as internal, otherwise (including the case when the tracestate header is not present) it’s treated as external. In case of external calls the agent creates a new trace with a new trace id and creates a link in the new transaction pointing to the original trace.

TransactionIgnoreUrls (performance)

This is used to restrict requests to certain URLs from being instrumented.

This property should be set to a comma separated string containing one or more paths.

For example, in order to ignore the URLs /foo and /bar, set the configuration value to "/foo,/bar".

When an incoming HTTP request is detected, its request path will be tested against each element in this list. For example, adding /home/index to this list would match and remove instrumentation from the following URLs:

https://www.mycoolsite.com/home/index
http://localhost/home/index
http://whatever.com/home/index?value1=123

In other words, the matching always happens based on the request path—hosts and query strings are ignored.

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
 All errors that are captured during a request to an ignored URL are still sent to the APM Server regardless of this setting.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_TRANSACTION_IGNORE_URLS

ElasticApm:TransactionIgnoreUrls
Default Type

/VAADIN/, /heartbeat, /favicon.ico, *.js, *.css, *.jpg, *.jpeg, *.png, *.gif, *.webp, *.svg, *.woff, *.woff2

Comma separated string
Note
 Changing this configuration will overwrite the default value.

UseElasticTraceparentHeader (added[1.3.0])

To enable {apm-guide-ref}/apm-distributed-tracing.html[distributed tracing], the agent adds trace context headers to outgoing HTTP requests made with the HttpClient type. These headers (traceparent and tracestate) are defined in the W3C Trace Context specification.

When this setting is true, the agent also adds the header elasticapm-traceparent for backwards compatibility with older versions of Elastic APM agents. Versions prior to 1.3.0 only read the elasticapm-traceparent header.

Environment variable name IConfiguration or Web.config key

ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER

ElasticApm:UseElasticTraceparentHeader
Default Type

true

Boolean

TraceContextIgnoreSampledFalse

Important
 Use of TraceContextIgnoreSampledFalse is deprecated. Use TraceContinuationStrategy with the restart_external value.

The agent uses the W3C Trace Context specification and standards for distributed tracing. The traceparent header from the W3C Trace Context specification defines a sampled flag which is propagated from a caller service to a callee service, and determines whether a trace is sampled in the callee service. The default behavior of the agent honors the sampled flag value and behaves accordingly.

There may be cases where you wish to change the default behavior of the agent with respect to the sampled flag. By setting the TraceContextIgnoreSampled configuration value to true, the agent ignores the sampled flag of the W3C Trace Context traceparent header when it has a value of false and and there is no agent specific tracestate header value present. In ignoring the sampled flag, the agent makes a sampling decision based on the sample rate. This can be useful when a caller service always sets a sampled flag value of false, that results in the agent never sampling any transactions.

Important

.NET 5 applications set the W3C Trace Context for outgoing HTTP requests by default, but with the traceparent header sampled flag set to false. If a .NET 5 application has an active agent, the agent ensures that the sampled flag is propagated with the agent’s sampling decision. If a .NET 5 application does not have an active agent however, and the application calls another service that does have an active agent, the propagation of a sampled flag value of false results in no sampled transactions in the callee service.

If your application is called by an .NET 5 application that does not have an active agent, setting the TraceContextIgnoreSampledFalse configuration value to true instructs the agent to start a new transaction and make a sampling decision based on the sample rate, when the traceparent header sampled flag has a value of false and there is no agent specific tracestate header value present.
Environment variable name IConfiguration or Web.config key

TRACE_CONTEXT_IGNORE_SAMPLED_FALSE

ElasticApm:TraceContextIgnoreSampledFalse
Default Type

false

Boolean

Messaging configuration options

IgnoreMessageQueues (added[1.10])

Used to filter out specific messaging queues/topics/exchanges from being traced. When set, sends-to and receives-from the specified queues/topics/exchanges will be ignored.

This config accepts a comma separated string of wildcard patterns of queues/topics/exchange names which should be ignored.

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.

Default Type

<empty string>

String
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_IGNORE_MESSAGE_QUEUES

ElasticApm:IgnoreMessageQueues

Stacktrace configuration options

ApplicationNamespaces (added[1.5])

This is used to determine whether a stack trace frame is an in-app frame or a library frame. When defined, all namespaces that do not start with one of the values of this collection are ignored when determining error culprit.

Multiple namespaces can be configured as a comma separated list. For example: "MyAppA, MyAppB".

This suppresses any configuration of ExcludedNamespaces.

Default Type

<empty string>

String
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_APPLICATION_NAMESPACES

ElasticApm:ApplicationNamespaces

ExcludedNamespaces (added[1.5])

A list of namespaces to exclude when reading an exception StackTrace to determine the culprit.

Namespaces are checked with string.StartsWith(), so "System." matches all System namespaces.

Default Type

"System., Microsoft., MS., FSharp., Newtonsoft.Json, Serilog, NLog, Giraffe."

String
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_EXCLUDED_NAMESPACES

ElasticApm:ExcludedNamespaces

StackTraceLimit (performance)

Setting this to 0 disables stack trace collection. Any positive integer value will be used as the maximum number of frames to collect. Setting it to -1 means that all frames will be collected.

Default Type

50

Integer
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_STACK_TRACE_LIMIT

ElasticApm:StackTraceLimit
Note
 If you would like to disable stack trace capturing only for spans, but still capture stack traces for errors, set the SpanFramesMinDuration (performance) config to 0.

SpanFramesMinDuration (performance)

In its default settings, the APM agent collects a stack trace for every recorded span with duration longer than 5ms. While this is very helpful to find the exact place in your code that causes the span, collecting this stack trace does have some overhead. When setting this option to a negative value, like -1ms, stack traces are collected for all spans. Setting it to a positive value, e.g. 5ms, limits stack trace collection to spans with durations equal to or longer than the given value, e.g. 5 milliseconds.

To disable stack trace collection for spans completely, set the value to 0ms.

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

Default Type

5ms

TimeDuration
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_SPAN_FRAMES_MIN_DURATION

ElasticApm:SpanFramesMinDuration

Supportability configuration options

LogLevel

Sets the logging level for the agent.

Valid options: Critical, Error, Warning, Info, Debug, Trace and None (None disables the logging).

Important
 The UseElasticApm() extension offers an overload to pass an IConfiguration instance to the agent. When configuring your agent in this way, as is typical in an ASP.NET Core application, you must instead set the LogLevel for the internal APM logger under the Logging section of appsettings.json. More details, including a sample configuration file are available in Configuration on ASP.NET Core.
Environment variable name IConfiguration or Web.config key

ELASTIC_APM_LOG_LEVEL

ElasticApm:LogLevel
Default Type

Error

String

All options summary

Option name dynamic config Keywords

ApiKey

No

Reporter

ApplicationNamespaces

No

Stacktrace

CaptureBody

Yes

HTTP, Performance

CaptureBodyContentTypes

Yes

HTTP, Performance

CaptureHeaders

No

HTTP, Performance

CentralConfig

No

Core

CloudProvider

No

Reporter

DisableMetrics

No

Reporter

Enabled

No

Core

Environment

No

Core

ExcludedNamespaces

No

Stacktrace

ExitSpanMinDuration

Yes

Core, Performance

FlushInterval

No

Reporter

GlobalLabels

No

Core

IgnoreMessageQueues

Yes

Messaging, Performance

HostName

No

Core

LogLevel

Yes

Supportability

MaxBatchEventCount

No

Reporter

MaxQueueEventCount

No

Reporter

MetricsInterval

No

Reporter

Recording

Yes

Core

SanitizeFieldNames

Yes

Core

SecretToken

No

Reporter

ServerCert

No

Reporter

ServerUrl

No

Reporter

ServiceName

No

Core

ServiceNodeName

No

Core

ServiceVersion

No

Core

SpanCompressionEnabled

Yes

Core, Performance

SpanCompressionExactMatchMaxDuration

Yes

Core, Performance

SpanCompressionSameKindMaxDuration

Yes

Core, Performance

SpanFramesMinDuration

No

Stacktrace, Performance

StackTraceLimit

No

Stacktrace, Performance

TraceContextIgnoreSampledFalse

No

Core

TransactionIgnoreUrls

Yes

HTTP, Performance

TransactionMaxSpans

Yes

Core, Performance

TransactionSampleRate

Yes

Core, Performance

TraceContinuationStrategy

Yes

HTTP, Performance

UseElasticTraceparentHeader

No

HTTP

VerifyServerCert

No

Reporter