Configuration on ASP.NET Core

The AddElasticApm() extension method on the IServiceCollection automatically accesses configuration bound via the Microsoft.Extensions.Configuration sources. To use this type of setup, which is typical in an ASP.NET Core application, your application’s Program.cs file should contain code similar to the following:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAllElasticApm();

var app = builder.Build();

// Configure the HTTP request pipeline.

app.Run();
		

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 in use in the application 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.

Here is a sample appsettings.json configuration file for a typical ASP.NET Core application that has been activated with AddElasticApm(). There is one important takeaway, listed as a callout below the example:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Elastic.Apm": "Debug"
    }
  },
  "AllowedHosts": "*",
  "ElasticApm":
    {
      "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.

In certain scenarios, like when you’re not using ASP.NET Core, you won’t activate the agent with the AddElasticApm() 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
    }
}
		

Because the agent reads all configuration from IConfiguration, you can inject computed or derived values at startup using the in-memory configuration provider. Call AddInMemoryCollection on builder.Configuration before AddElasticApm or AddAllElasticApm:

var builder = WebApplication.CreateBuilder(args);

// Derive the APM environment from application-specific configuration
var apmEnvironment = $"{builder.Configuration["App:Region"]}-{builder.Environment.EnvironmentName}";

builder.Configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
    ["ElasticApm:ServiceName"] = "My Service",
    ["ElasticApm:Environment"] = apmEnvironment
});

builder.Services.AddAllElasticApm();
		

This pattern is useful when you need to set agent values that are derived from other configuration, fetched from a secrets manager, or otherwise not expressible as static file entries.

For example, to supply an API key retrieved from a secrets manager such as Azure Key Vault or AWS Secrets Manager:

var builder = WebApplication.CreateBuilder(args);

// Fetch the API key from your secrets manager at startup
var apiKey = GetApiKeyFromVault("elastic-apm-api-key");

builder.Configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
    ["ElasticApm:ApiKey"] = apiKey
});

builder.Services.AddAllElasticApm();
		

1. pseudo-code: replace with your secrets manager client call

Source ordering and environment variable precedence

The agent resolves each configuration option through two layers in order:

1. IConfiguration — checked first. This includes all registered sources: appsettings.json, ElasticApm__* environment variables (double underscore is the .NET section separator), command-line arguments, and any in-memory values.
2. ELASTIC_APM_* environment variables — the agent's own env var form, checked only when layer 1 returns no value.

Because AddInMemoryCollection is appended to the end of the IConfiguration source list, it wins over all other layer 1 sources. It also implicitly overrides ELASTIC_APM_* variables, because a hit in layer 1 means the agent never falls through to layer 2.

If you want either form of environment variable to remain able to override a value at deployment time, check for both before injecting:

var overrides = new Dictionary<string, string?>();

if (builder.Configuration["ElasticApm:Environment"] is null
    && Environment.GetEnvironmentVariable("ELASTIC_APM_ENVIRONMENT") is null)
    overrides["ElasticApm:Environment"] = DeriveEnvironment(builder.Configuration);

if (overrides.Count > 0)
    builder.Configuration.AddInMemoryCollection(overrides);

builder.Services.AddAllElasticApm();
		

1. replace with your own logic

Most agent configuration options are read once when the agent initializes at startup. In-memory values must be in place before builder.Build() is called; changes made after that point will not be picked up.

The IConfiguration key for each agent option is listed under the IConfiguration or Web.config key column in the configuration reference.