configuration.asciidoc

Note	For the best reading experience, please view this documentation at elastic.co

Configuration

You can 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.

Configuration on ASP.NET Core

The UseElasticApm() extension method offers an overload to pass an IConfiguration instance to the APM Agent. By using this overload in a typical ASP.NET Core application, the Startup.cs file would contain code similar to the following:

public class Startup
{
    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 you can use any configuration source that you configured on the IConfiguration instance that you passed to the APM Agent. You can find the key of each configuration below in the IConfiguration key column.

Note	By simply calling app.UseElasticApm() without the overload, the agent will read configurations only from environment variables.

Sample configuration file

Below is a sample appsettings.json configuration file for a typical ASP.NET Core application. There are two important takeaways:

1. The part below ElasticApm is fetched by the agent if the corresponding IConfiguration is passed to the agent.

2. With ASP.NET Core, you must set LogLevel for the internal APM logger in the standard `Logging section with the ElasticApm category name.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Elastic.Apm": "Debug"
    }
  },
  "AllowedHosts": "*",
  "ElasticApm":
    {
      "ServerUrls":  "http://myapmserver:8200",
      "TransactionSampleRate": 1.0
    }
}

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

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ElasticApm":
    {
      "LogLevel":  "Debug",
      "ServerUrls":  "http://myapmserver:8200",
      "TransactionSampleRate": 1.0
    }
}

Core configuration options

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 less regexy terms: Your service name must only contain characters from the ASCII alphabet, numbers, dashes, underscores and spaces.

Environment variable name	IConfiguration key
ELASTIC_APM_SERVICE_NAME	ElasticApm:ServiceName

Default	Type
Name of the entry assembly	String

TransactionSampleRate

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.

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.

Environment variable name	IConfiguration key
ELASTIC_APM_TRANSACTION_SAMPLE_RATE	ElasticApm:TransactionSampleRate

Default	Type
1.0	Double

Reporter configuration options

SecretToken

Environment variable name	IConfiguration key
ELASTIC_APM_SECRET_TOKEN	ElasticApm:SecretToken

Default	Type
<none>	String

This string is 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 in case the APM Server requires a token (e.g. APM Server in Elastic Cloud).

ServerUrls

Environment variable name	IConfiguration key
ELASTIC_APM_SERVER_URLS	ElasticApm:ServerUrls

Default	Type
http://localhost:8200	List

The URLs for your APM Servers. The URLs must be fully qualified, including protocol (http or https) and port. To add multiple servers, separate them with a comma (,).

Note	Providing multiple URLs only works with APM Server v6.5+.

LogLevel

Environment variable name	IConfiguration key
ELASTIC_APM_LOG_LEVEL	ElasticApm:LogLevel

Default	Type
Error	String

Sets the logging level for the agent.

Valid options: Error, Warning, Info, Debug.

MetricsInterval (added[1.0.0-beta1])

The interval at which the agent sends metrics to the APM Server. Must be at least 1s. Set 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 key
ELASTIC_APM_METRICS_INTERVAL	ElasticApm:MetricsInterval

HTTP configuration options

CaptureHeaders (performance)

Environment variable name	IConfiguration key
ELASTIC_APM_CAPTURE_HEADERS	ElasticApm:CaptureHeaders

Default	Type
true	Boolean

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

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