--- title: Configuration description: The Elastic APM .NET agent can be configured through environment variables or, for ASP.NET Core applications, through the standard appsettings.json file... url: https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/configuration products: - APM .NET Agent - APM Agent applies_to: - Serverless Observability projects: Generally available - Elastic Stack: Generally available - Application Performance Monitoring Agent for .NET: Generally available --- # Configuration The Elastic APM .NET agent can be configured through environment variables or, for ASP.NET Core applications, through the standard `appsettings.json` file. Both approaches support the same options but use different key names. Environment variable names use the `ELASTIC_APM_` prefix, while `appsettings.json` keys use the `ElasticApm:` prefix. Environment variables work with every installation method. For ASP.NET Core applications registered with `AddElasticApm()` or `AddAllElasticApm()`, the agent also plugs into the [Microsoft.Extensions.Configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) infrastructure, allowing configuration through `appsettings.json` or any other configured source. For these setups, `appsettings.json` (and other `IConfiguration` sources) take precedence over `ELASTIC_APM_*` environment variables, the agent reads `IConfiguration` first and only falls back to environment variables when no `IConfiguration` value is present. For all other installation methods, including auto-instrumentation via the profiler and standalone .NET applications, environment variables are the only configuration source. ## Minimum configuration For non-local deployments, configure at least two settings to connect the agent to your APM Server: | Setting | Environment variable | `appsettings.json` key | Default | |------------|--------------------------|------------------------|-------------------------| | Server URL | `ELASTIC_APM_SERVER_URL` | `ElasticApm:ServerUrl` | `http://localhost:8200` | | API Key | `ELASTIC_APM_API_KEY` | `ElasticApm:ApiKey` | *(none)* | For local development against a default APM Server with no authentication, these defaults are sufficient and no configuration is required. It's also recommended to set the service name explicitly: | Setting | Environment variable | `appsettings.json` key | Default | |--------------|----------------------------|--------------------------|---------------------| | Service name | `ELASTIC_APM_SERVICE_NAME` | `ElasticApm:ServiceName` | Entry assembly name | `ServiceName` defaults to the name of your entry assembly. Set it explicitly if the auto-detected name is not meaningful, or if multiple services share the same binary. **Environment variables** work with every installation method: ```sh ELASTIC_APM_SERVER_URL=https://your-apm-server:8200 ELASTIC_APM_API_KEY=your-api-key ELASTIC_APM_SERVICE_NAME=my-dotnet-service ``` For ASP.NET Core applications registered with `AddElasticApm()` or `AddAllElasticApm()`, you can instead set these in `appsettings.json`. See [Configuration on ASP.NET Core](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/configuration-on-asp-net-core) for details. ```json { "ElasticApm": { "ServerUrl": "https://your-apm-server:8200", "ApiKey": "your-api-key", "ServiceName": "my-dotnet-service" } } ``` ### Authentication Kibana generates an API key by default when configuring the APM integration, making [`ApiKey`](/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-reporter#config-api-key) the recommended authentication method. If your APM Server is configured with a secret token instead, use [`SecretToken`](/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-reporter#config-secret-token). Never commit `ApiKey` or `SecretToken` values to source control. Use your platform's secrets management (for example, Azure Key Vault, AWS Secrets Manager, or Kubernetes Secrets) to inject credentials at runtime. If the agent cannot reach the APM Server — for example, due to a missing or incorrect URL or authentication setting — it continues to run but cannot send data. Check the agent logs if you are not seeing data in APM. See [`LogLevel`](/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-supportability#config-log-level) to increase log verbosity. ## Configuration reference Configuration options are documented by category. Each option lists its environment variable name, `appsettings.json` key, default value, and type. | Category | Description | |-------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | [Core](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-core) | Service identity, sampling, recording, and general behavior | | [Reporter](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-reporter) | APM Server connection, authentication, and reporting intervals | | [HTTP](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-http) | HTTP request capture, headers, body, and trace context propagation | | [Messaging](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-messaging) | Message queue and topic instrumentation | | [Stacktrace](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-stacktrace) | Stack trace collection depth and namespace filtering | | [Supportability](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-supportability) | Agent log level and diagnostic settings | | [All options summary](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-all-options-summary) | Quick-reference table of every option | For platform-specific configuration setup: - [Configuration on ASP.NET Core](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/configuration-on-asp-net-core) - [Configuration on ASP.NET](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/configuration-on-asp-net) - [Configuration for Windows Services](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/configuration-for-windows-services) ## Dynamic configuration Configuration options that are marked with the ![dynamic config](https://www.elastic.co/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/images/dynamic-config.svg) badge can be changed at runtime when set from a supported source. The .NET Agent supports [Central configuration](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3375/solutions/observability/apm/apm-agents/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` ([1.1])](/elastic/docs-builder/docs/3375/reference/apm/agents/dotnet/config-core#config-central-config). The agent polls for configuration changes at the interval specified by the APM Server, defaulting to 5 minutes. Changes take effect after the next poll.