---
title: Configuring the .NET Core Tracing Library
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Configure the Datadog Tracing
  Library > Configuring the .NET Core Tracing Library
---

# Configuring the .NET Core Tracing Library

After you set up the tracing library with your code and configure the Agent to collect APM data, optionally configure the tracing library as desired, including setting up [Unified Service Tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/).
To verify your runtime configuration and confirm settings, view the current configuration of your service in Datadog. Navigate to the **APM Service Page**, click **Service Config**, and select the **SDK Configuration** tab.
{% image
   source="https://docs.dd-static.net/images/tracing/dotnet/dotnet_core_configuration.8303ff3d0a963a71a20ff2b8dbd1c05e.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/dotnet/dotnet_core_configuration.8303ff3d0a963a71a20ff2b8dbd1c05e.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt=".NET Core Tracer configuration setting precedence" /%}

You can set configuration settings in the .NET Tracer with any of the following methods:

{% tab title="Environment variables" %}
To configure the tracer using environment variables, set the variables before launching the instrumented application. To learn how to set environment variables in different environments, see [Configuring process environment variables](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/dotnet-core/#configuring-process-environment-variables).
{% /tab %}

{% tab title="Code" %}
To configure the tracer in application code, create a `TracerSettings` instance from the default configuration sources. Set properties on this `TracerSettings` instance before calling `Tracer.Configure()`. For example:

{% alert level="danger" %}
Settings must be set on `TracerSettings` *before* creating the `Tracer`. Changes made to `TracerSettings` properties after the `Tracer` is created are ignored.
{% /alert %}

```csharp
using Datadog.Trace;
using Datadog.Trace.Configuration;

// read default configuration sources (env vars or datadog.json)
var settings = TracerSettings.FromDefaultSources();

// change some settings
settings.Environment = "prod";
settings.ServiceName = "MyService";
settings.ServiceVersion = "abc123";
// In v2 of Datadog.Trace, use settings.Exporter.AgentUri
settings.AgentUri = new Uri("http://localhost:8126/");

// configure the global Tracer settings
Tracer.Configure(settings);
```

{% /tab %}

{% tab title="JSON file" %}
To configure the tracer using a JSON file, create `datadog.json` in the instrumented application's directory. The root JSON object must be an object with a key-value pair for each setting. For example:

```json
{
  "DD_TRACE_AGENT_URL": "http://localhost:8126",
  "DD_ENV": "prod",
  "DD_SERVICE": "MyService",
  "DD_VERSION": "abc123",
}
```

{% /tab %}

## Configuration settings{% #configuration-settings %}

{% alert level="danger" %}
On Linux, the names of environment variables are case-sensitive.
{% /alert %}

Using the methods described above, customize your tracing configuration with the following variables. Use the environment variable name (for example, `DD_TRACE_AGENT_URL`) when setting environment variables or configuration files. Use the TracerSettings property (for example, `Exporter.AgentUri`) when changing settings in code.

### Unified Service Tagging{% #unified-service-tagging %}

To use [Unified Service Tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/), configure the following settings for your services:

{% dl %}

{% dt %}
`DD_ENV`
{% /dt %}

{% dd %}
**TracerSettings property**: `Environment`If specified, adds the `env` tag with the specified value to all generated spans. Added in version 1.17.0.
{% /dd %}

{% dt %}
`DD_SERVICE`
{% /dt %}

{% dd %}
**TracerSettings property**: `ServiceName`If specified, sets the service name. Otherwise, the .NET Tracer tries to determine service name automatically from the application name (IIS application name, process entry assembly, or process name). Added in version 1.17.0.
{% /dd %}

{% dt %}
`DD_VERSION`
{% /dt %}

{% dd %}
**TracerSettings property**: `ServiceVersion`If specified, sets the version of the service. Added in version 1.17.0.
{% /dd %}

{% /dl %}

### Optional configuration{% #optional-configuration %}

The following configuration variables are available for both automatic and custom instrumentation:

#### Traces{% #traces %}

{% dl %}

{% dt %}
`DD_TRACE_RATE_LIMIT`
{% /dt %}

{% dd %}
**TracerSettings property**: `MaxTracesSubmittedPerSecond`The number of traces allowed to be submitted per second (deprecates `DD_MAX_TRACES_PER_SECOND`).**Default**: `100` when `DD_TRACE_SAMPLE_RATE` is set. Otherwise, delegates rate limiting to the Datadog Agent.
{% /dd %}

{% dt %}
`DD_TAGS`
{% /dt %}

{% dd %}
**TracerSettings property**: `GlobalTags`If specified, adds all of the specified tags to all generated spans.**Example**: `layer:api, team:intake, key:value`**Note**: The delimiter is a comma and a space: `,`.Added in version 1.17.0.
{% /dd %}

{% dt %}
`DD_TRACE_HEADER_TAGS`
{% /dt %}

{% dd %}
**TracerSettings property**:`HeaderTags`Accepts a map of case-insensitive header keys to tag names and automatically applies matching header values as tags on traces. Also accepts entries without a specified tag name that are automatically mapped to tags of the form `http.request.headers.<header-name>` and `http.response.headers.<header-name>` respectively. Applies to web server integrations (ASP.NET, ASP.NET Core, ASP.NET WebAPI, etc…). For incoming requests and outgoing responses handled by these frameworks. This feature does not apply to outbound HTTP client calls.**Example** (with specified tag names): `User-ID:userId`If the **Request** has a header `User-ID`, its value is applied as tag `userId` to the spans produced by the service.**Example** (without specified tag names): `User-ID`If the **Request** has a header `User-ID`, its value is applied as tag `http.request.headers.User-ID`.If the **Response** has a header `User-ID`, its value is applied as tag `http.response.headers.User-ID`.Added in version 1.18.3.Response header support and entries without tag names added in version 1.26.0.Starting in version 2.35.0, if [Agent Remote Configuration](https://docs.datadoghq.com/tracing/guide/remote_config) is enabled where this service runs, you can set `DD_TRACE_HEADER_TAGS` in the [Software Catalog](https://app.datadoghq.com/services) UI.
{% /dd %}

{% dt %}
`DD_TRACE_CLIENT_IP_ENABLED`
{% /dt %}

{% dd %}
Enables client IP collection from relevant IP headers.Added in version `2.19.0`.**Default**: `false`
{% /dd %}

{% dt %}
`DD_TRACE_CLIENT_IP_HEADER`
{% /dt %}

{% dd %}
The IP header to be used for client IP collection, for example: `x-forwarded-for`.Added in version `2.19.0`.**Default**: Datadog parses the following: `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip`, `x-forwarded`, `forwarded-for`, `x-cluster-client-ip`, `fastly-client-ip`, `cf-connecting-ip`, `cf-connecting-ipv6`. If several are present, the first from the list to parse correctly will be used.
{% /dd %}

{% dt %}
`DD_TRACE_SERVICE_MAPPING`
{% /dt %}

{% dd %}
Rename services using configuration. Accepts a comma-separated list of key-value pairs of service name keys to rename, and the name to use instead, in the format `[from-key]:[to-name]`.**Example**: `mysql:main-mysql-db, mongodb:offsite-mongodb-service`The `from-key` value is specific to the integration type, and should exclude the application name prefix. For example, to rename `my-application-sql-server` to `main-db`, use `sql-server:main-db`. Added in version 1.23.0
{% /dd %}

{% dt %}
`DD_HTTP_SERVER_TAG_QUERY_STRING`
{% /dt %}

{% dd %}
When set to `true`, the `http.url` includes query string parameters. You can find more details in [Redacting the query in the url](https://docs.datadoghq.com/tracing/configure_data_security/#redacting-the-query-in-the-url). **Default**: `true`
{% /dd %}

{% dt %}
`DD_HTTP_SERVER_TAG_QUERY_STRING_SIZE`
{% /dt %}

{% dd %}
When `DD_HTTP_SERVER_TAG_QUERY_STRING` is true, sets the max size of the querystring to report, before obfuscation. Set 0 for no limit in size**Default**: `5000`
{% /dd %}

{% dt %}
`DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP`
{% /dt %}

{% dd %}
When `DD_HTTP_SERVER_TAG_QUERY_STRING` is true, this regex redacts sensitive data from incoming requests' query string reported in the `http.url` tag (matches are replaced with `<redacted>`). This regex executes for every incoming request.
{% /dd %}

{% /dl %}

#### Agent{% #agent %}

{% dl %}

{% dt %}
`DD_TRACE_AGENT_URL`
{% /dt %}

{% dd %}
**TracerSettings property**: `Exporter.AgentUri`Sets the URL endpoint where traces are sent. Overrides `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network/#configure-ports) sets `receiver_port` or `DD_APM_RECEIVER_PORT` to something other than the default `8126`, then `DD_TRACE_AGENT_PORT` or `DD_TRACE_AGENT_URL` must match it.It can contain a Unix Domain Socket (UDS) path by prefixing the path with `unix://`.Note that UDS is only supported on .NET Core 3.1 and above.**Default**: `http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>` if they are set, `unix:///var/run/datadog/apm.socket` if the file exists, or `http://localhost:8126`.
{% /dd %}

{% dt %}
`DD_AGENT_HOST`
{% /dt %}

{% dd %}
Sets the host where the Agent is listening for connections. Can be a hostname or an IP address. Use `DD_TRACE_AGENT_URL`, which has precedence over this parameter.**Default**: `localhost`
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_PORT`
{% /dt %}

{% dd %}
Sets the TCP port where the Agent is listening for connections. Use `DD_TRACE_AGENT_URL`, which has precedence over this parameter. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network/#configure-ports) sets `receiver_port` or `DD_APM_RECEIVER_PORT` to something other than the default `8126`, then `DD_TRACE_AGENT_PORT` or `DD_TRACE_AGENT_URL` must match it.**Default**: `8126`
{% /dd %}

{% dt %}
`DD_INSTRUMENTATION_TELEMETRY_ENABLED`
{% /dt %}

{% dd %}
Datadog may collect [environmental and diagnostic information about your system](https://docs.datadoghq.com/tracing/configure_data_security#telemetry-collection) to improve the product. When false, this telemetry data will not be collected.**Default**: `true`
{% /dd %}

{% /dl %}

#### Trace context propagation{% #trace-context-propagation %}

For information about valid values and using the following configuration options, see [Trace Context Propagation](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/).

{% dl %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE_INJECT`
{% /dt %}

{% dd %}
**Default**: `datadog,tracecontext,baggage`A comma-separated list of header formats to include to propagate distributed traces between services.Available since version `2.20.0`
{% /dd %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE_EXTRACT`
{% /dt %}

{% dd %}
**Default**: `datadog,tracecontext,baggage`A comma-separated list of header formats from which to attempt to extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue.Available since version `2.20.0`
{% /dd %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE`
{% /dt %}

{% dd %}
**Default**: `datadog,tracecontext,baggage`A comma-separated list of header formats from which to attempt to inject and extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue. The more specific `DD_TRACE_PROPAGATION_STYLE_INJECT` and `DD_TRACE_PROPAGATION_STYLE_EXTRACT` configuration settings take priority when present.Available since version `2.20.0`
{% /dd %}

{% dt %}
`DD_TRACE_PROPAGATION_EXTRACT_FIRST`
{% /dt %}

{% dd %}
**Default**: `false`When set to `true`, stop extracting trace context when a valid one is found.Available since version `2.42.0`
{% /dd %}

{% /dl %}

#### Diagnostic logs{% #diagnostic-logs %}

{% dl %}

{% dt %}
`DD_TRACE_DEBUG`
{% /dt %}

{% dd %}
Enables or disables debug logging. Valid values are `true` or `false`.**Default**: `false`
{% /dd %}

{% dt %}
`DD_TRACE_LOG_DIRECTORY`
{% /dt %}

{% dd %}
Sets the directory for .NET Tracer logs.**Default**: `%ProgramData%\Datadog .NET Tracer\logs\` on Windows, `/var/log/datadog/dotnet` on Linux
{% /dd %}

{% dt %}
`DD_TRACE_LOGFILE_RETENTION_DAYS`
{% /dt %}

{% dd %}
During the tracer's startup, this configuration uses the tracer's current log directory to delete log files the same age and older than the given number of days. Added in version 2.19.0.**Default**: `32`
{% /dd %}

{% dt %}
`DD_TRACE_LOGGING_RATE`
{% /dt %}

{% dd %}
Sets rate limiting for log messages. If set, unique log lines are written once per `x` seconds. For example, to log a given message once per 60 seconds, set to `60`. Setting to `0` disables log rate limiting. Added in version 1.24.0. Disabled by default.
{% /dd %}

{% /dl %}

#### OpenTelemetry{% #opentelemetry %}

{% dl %}

{% dt %}
`DD_TRACE_OTEL_ENABLED`
{% /dt %}

{% dd %}
Enables or disables OpenTelemetry based tracing, both for [custom](https://docs.datadoghq.com/tracing/trace_collection/otel_instrumentation/dotnet/) or [automatic](https://docs.datadoghq.com/tracing/trace_collection/compatibility/dotnet-core/#opentelemetry-based-integrations) instrumentation. Valid values are: `true` or `false`.**Default**: `false`
{% /dd %}

{% /dl %}

### Automatic instrumentation optional configuration{% #automatic-instrumentation-optional-configuration %}

The following configuration variables are available **only** when using automatic instrumentation:

#### Traces{% #traces-1 %}

{% dl %}

{% dt %}
`DD_TRACE_ENABLED`
{% /dt %}

{% dd %}
**TracerSettings property**: `TraceEnabled`Enables or disables all instrumentation. Valid values are: `true` or `false`.**Default**: `true`See also [DD_APM_TRACING_ENABLED](https://docs.datadoghq.com/tracing/trace_collection/library_config/#traces).
{% /dd %}

{% dt %}
`DD_TRACE_EXPAND_ROUTE_TEMPLATES_ENABLED`
{% /dt %}

{% dd %}
Expands all route parameters in the application for ASP.NET/ASP.NET Core (except ID parameters)This can be useful if you are using parameter names to differentiate between form values, or a slug, such as in GraphQL. **Default**: `false` Added in version 2.5.1.
{% /dd %}

{% dt %}
`DD_TRACE_METHODS`
{% /dt %}

{% dd %}
List of methods to trace. Accepts a semicolon (`;`) separated list where each entry has the format `Namespace.TypeName[MethodNames]`, where `MethodNames` is either a comma (`,`) separated list of method names or the `*` wildcard. For generic types, replace the angled brackets and the type parameters' names with a backtick (```) followed by the number of generic type parameters. For example, `Dictionary<TKey, TValue>` must be written as `Dictionary`2`. For generic methods, you only need to specify the method name.**Example**: `Namespace1.Class1[Method1,GenericMethod];Namespace1.GenericTypeWithOneTypeVariable`1[ExecuteAsync];Namespace2.Class2[*]`**Note:** The wildcard method support (`[*]`) selects all methods in a type except constructors, property getters and setters, `Equals`, `Finalize`, `GetHashCode`, and `ToString`.`DD_TRACE_METHODS` is not intended for tracing large numbers of methods and classes. To find CPU, memory, and IO bottlenecks, broken down by method name, class name, and line number, consider the [Continuous Profiler](https://docs.datadoghq.com/profiler/) product instead.Added in version 2.6.0. Wildcard support `[*]` added in version 2.7.0.
{% /dd %}

{% dt %}
`DD_TRACE_KAFKA_CREATE_CONSUMER_SCOPE_ENABLED`
{% /dt %}

{% dd %}
Alters the behavior of the Kafka consumer span**Default**: `true`When set to `true`, the consumer span is created when a message is consumed and closed before consuming the next message. The span duration is representative of the computation between one message consumption and the next. Use this setting when message consumption is performed in a loop.When set to `false`, the consumer span is created when a message is consumed and immediately closed. Use this setting when a message is not processed completely before consuming the next one, or when multiple messages are consumed at once. When you set this parameter to `false`, consumer spans are closed right away. If you have child spans to trace, you must extract the context manually. Read [Headers extraction and injection](https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/dotnet/#headers-extraction-and-injection) for more details.
{% /dd %}

{% /dl %}

#### Database monitoring{% #database-monitoring %}

{% dl %}

{% dt %}
`DD_DBM_PROPAGATION_MODE`
{% /dt %}

{% dd %}
Enables linking between data sent from APM and the Database Monitoring product when set to `service` or `full`. The `service` option enables the connection between DBM and APM services. The `full` option enables connection between database spans with database query events. Available for Postgres and MySQL.**Default**: `disabled`
{% /dd %}

{% /dl %}

#### Runtime metrics{% #runtime-metrics %}

{% dl %}

{% dt %}
`DD_RUNTIME_METRICS_ENABLED`
{% /dt %}

{% dd %}
Enables .NET runtime metrics. Valid values are `true` or `false`.**Default**: `true` for .NET 6+ starting v3.40.0+, otherwise `false`.Added in version 1.23.0.
{% /dd %}

{% dt %}
`DD_RUNTIME_METRICS_DIAGNOSTICS_METRICS_API_ENABLED`
{% /dt %}

{% dd %}
Available starting with .NET 6. It controls whether the .NET tracer uses the new [`System.Diagnostics.Metrics`](https://learn.microsoft.com/dotnet/api/system.diagnostics.metrics) API to collect the metrics instead of the `EventListener`-based collector.**Default**: `true` on .NET 8+ and on .NET 6/7 when `DD_RUNTIME_METRICS_ENABLED` is not explicitly set, otherwise `false`.Added in version 3.40.0.
{% /dd %}

{% /dl %}

#### Errors{% #errors %}

{% dl %}

{% dt %}
`DD_HTTP_CLIENT_ERROR_STATUSES`
{% /dt %}

{% dd %}
Sets status code ranges that will cause HTTP client spans to be marked as errors.**Default**: `400-499`
{% /dd %}

{% dt %}
`DD_HTTP_SERVER_ERROR_STATUSES`
{% /dt %}

{% dd %}
Sets status code ranges that will cause HTTP server spans to be marked as errors.**Default**: `500-599`
{% /dd %}

{% /dl %}

#### Logs{% #logs %}

{% dl %}

{% dt %}
`DD_LOGS_INJECTION`
{% /dt %}

{% dd %}
**TracerSettings property**: `LogsInjectionEnabled`Enables or disables automatic injection of correlation identifiers into application logs.Your logger needs to have a `source` that sets the `trace_id` mapping correctly. The default source for .NET Applications, `csharp`, does this automatically. For more information, see [correlated logs in the Trace ID panel](https://docs.datadoghq.com/tracing/faq/why-cant-i-see-my-correlated-logs-in-the-trace-id-panel#trace_id-option).Starting in version 2.35.0, if [Agent Remote Configuration](https://docs.datadoghq.com/tracing/guide/remote_config) is enabled where this service runs, you can set `DD_LOGS_INJECTION` in the [Software Catalog](https://app.datadoghq.com/services) UI.
{% /dd %}

{% /dl %}

### Automatic instrumentation integration configuration{% #automatic-instrumentation-integration-configuration %}

The following table lists configuration variables that are available **only** when using automatic instrumentation and can be set for each integration.

{% dl %}

{% dt %}
`DD_DISABLED_INTEGRATIONS`
{% /dt %}

{% dd %}
**TracerSettings property**: `DisabledIntegrationNames`Sets a list of integrations to disable. All other integrations remain enabled. If not set, all integrations are enabled. Supports multiple values separated with semicolons. Valid values are the integration names listed in the [Integrations](https://docs.datadoghq.com/tracing/trace_collection/compatibility/dotnet-core#integrations) section.
{% /dd %}

{% dt %}
`DD_TRACE_<INTEGRATION_NAME>_ENABLED`
{% /dt %}

{% dd %}
**TracerSettings property**: `Integrations[<INTEGRATION_NAME>].Enabled`Enables or disables a specific integration. Valid values are: `true` or `false`. Integration names are listed in the [Integrations](https://docs.datadoghq.com/tracing/trace_collection/compatibility/dotnet-core#integrations) section.**Default**: `true`
{% /dd %}

{% /dl %}

### Experimental features{% #experimental-features %}

The following configuration variables are for features that are available for use but may change in future releases.

{% dl %}

{% dt %}
`DD_TRACE_PARTIAL_FLUSH_ENABLED`
{% /dt %}

{% dd %}
Enables incrementally flushing large traces to the Datadog Agent, reducing the chance of rejection by the Agent. Use only when you have long-lived traces or traces with many spans. Valid values are `true` or `false`. Added in version 1.26.0, only compatible with the Datadog Agent 7.26.0+.**Default**: `false`
{% /dd %}

{% /dl %}

### Deprecated settings{% #deprecated-settings %}

{% dl %}

{% dt %}
`DD_TRACE_LOG_PATH`
{% /dt %}

{% dd %}
Sets the path for the automatic instrumentation log file and determines the directory of all other .NET Tracer log files. Ignored if `DD_TRACE_LOG_DIRECTORY` is set.
{% /dd %}

{% dt %}
`DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED`
{% /dt %}

{% dd %}
Enables improved resource names for web spans when set to `true`. Uses route template information where available, adds an additional span for ASP.NET Core integrations, and enables additional tags. Added in version 1.26.0. Enabled by default in 2.0.0**Default**: `true`
{% /dd %}

{% /dl %}

## Further reading{% #further-reading %}

- [Connect .NET application logs to traces](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces/dotnet/)
- [Runtime metrics](https://docs.datadoghq.com/tracing/metrics/runtime_metrics/dotnet/)
- [Propagating trace context](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/)
- [Microsoft Azure App Service extension](https://docs.datadoghq.com/serverless/azure_app_services/)
- [Explore your services, resources, and traces](https://docs.datadoghq.com/tracing/glossary/)
- [.NET monitoring with Datadog APM and distributed tracing](https://www.datadoghq.com/blog/net-monitoring-apm/)
- [Examples of custom instrumentation](https://github.com/DataDog/dd-trace-dotnet/tree/master/tracer/samples)
- [Source code](https://github.com/DataDog/dd-trace-dotnet)
- [Deploy ASP.NET Core applications to Azure App Service](https://www.datadoghq.com/blog/deploy-dotnet-core-azure-app-service/)
- [OpenTelemetry Environment Variable Configurations](https://docs.datadoghq.com/opentelemetry/interoperability/environment_variable_support)