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.
You can set configuration settings in the .NET Tracer with any of the following methods:
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.
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:
TracerSettings before creating the Tracer. Changes made to TracerSettings properties after the Tracer is created are ignored.using Datadog.Trace;
using Datadog.Trace.Configuration;
// read default configuration sources (env vars, web.config, datadog.json)
var settings = TracerSettings.FromDefaultSources();
// change some settings
settings.Environment = "prod";
settings.ServiceName = "MyService";
settings.ServiceVersion = "abc123";
settings.Exporter.AgentUri = new Uri("http://localhost:8126/");
// configure the global Tracer settings
Tracer.Configure(settings);
To configure the Tracer using an app.config or web.config file, use the <appSettings> section. For example:
<configuration>
<appSettings>
<add key="DD_TRACE_AGENT_URL" value="http://localhost:8126"/>
<add key="DD_ENV" value="prod"/>
<add key="DD_SERVICE" value="MyService"/>
<add key="DD_VERSION" value="abc123"/>
</appSettings>
</configuration>
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:
{
"DD_TRACE_AGENT_URL": "http://localhost:8126",
"DD_ENV": "prod",
"DD_SERVICE": "MyService",
"DD_VERSION": "abc123",
}
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.
To use Unified Service Tagging, configure the following settings for your services:
DD_ENVEnvironmentenv tag with the specified value to all generated spans. Added in version 1.17.0.DD_SERVICEServiceNameDD_VERSIONServiceVersionThe following configuration variables are available for both automatic and custom instrumentation:
DD_TRACE_AGENT_URLExporter.AgentUriDD_AGENT_HOST and DD_TRACE_AGENT_PORT if set.http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT> if they are set or http://localhost:8126.DD_AGENT_HOSTDD_TRACE_AGENT_URL, which has precedence over this parameter.localhostDD_TRACE_AGENT_PORTDD_TRACE_AGENT_URL, which has precedence over this parameter.8126DD_TRACE_SAMPLE_RATEGlobalSamplingRate0.0 to 1.0.
For more information, see Ingestion Mechanisms.DD_TRACE_SAMPLING_RULESCustomSamplingRulesnull"sample_rate". The "name" and "service" fields are optional. The "sample_rate" value must be between 0.0 and 1.0 (inclusive). Rules are applied in configured order to determine the trace’s sample rate.
For more information, see Ingestion Mechanisms.'[{"sample_rate": 0.2}]''[{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]'DD_TRACE_RATE_LIMITMaxTracesSubmittedPerSecondDD_MAX_TRACES_PER_SECOND).100 when DD_TRACE_SAMPLE_RATE is set. Otherwise, delegates rate limiting to the Datadog Agent.DD_SPAN_SAMPLING_RULES
Default: null
A JSON array of objects. Rules are applied in configured order to determine the span’s sample rate. The sample_rate value must be between 0.0 and 1.0 (inclusive).
For more information, see Ingestion Mechanisms.
Example:
my-service and operation name http.request, up to 50 traces per second: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'DD_TRACE_GLOBAL_TAGSGlobalTagslayer:api, team:intake, .DD_TRACE_DEBUGtrue or false.falseDD_TRACE_HEADER_TAGSHeaderTagsCASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-NameDD_TRACE_CLIENT_IP_ENABLED2.19.0.falseDD_TAGSGlobalTagslayer:api,team:intakeDD_TRACE_LOG_DIRECTORY%ProgramData%\Datadog .NET Tracer\logs\DD_TRACE_LOGGING_RATEx 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_TRACE_SERVICE_MAPPING[from-key]:[to-name].mysql:main-mysql-db, mongodb:offsite-mongodb-servicefrom-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.0The following configuration variables are available only when using automatic instrumentation:
DD_TRACE_ENABLEDTraceEnabledfalse completely disables the CLR profiler. For other configuration methods, the CLR profiler is still loaded, but traces will not be generated. Valid values are: true or false.trueDD_HTTP_CLIENT_ERROR_STATUSES400-499DD_HTTP_SERVER_ERROR_STATUSES500-599DD_LOGS_INJECTIONLogsInjectionEnabledsource 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.DD_RUNTIME_METRICS_ENABLEDtrue or false.falseDD_TRACE_EXPAND_ROUTE_TEMPLATES_ENABLEDfalse
Added in version 2.5.2DD_TRACE_METHODS;) separated list where each entry has the format 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.Namespace1.Class1[Method1,GenericMethod];Namespace1.GenericTypeWithOneTypeVariable`1[ExecuteAsync];Namespace2.Class2[*][*]) selects all methods in a type except constructors, property getters and setters, Equals, Finalize, GetHashCode, and ToString.[*] added in version 2.7.0.DD_TRACE_KAFKA_CREATE_CONSUMER_SCOPE_ENABLEDtruetrue, 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.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.The following table lists configuration variables that are available only when using automatic instrumentation and can be set for each integration.
DD_DISABLED_INTEGRATIONSDisabledIntegrationNamesDD_TRACE_<INTEGRATION_NAME>_ENABLEDIntegrations[<INTEGRATION_NAME>].Enabledtrue or false. Integration names are listed in the Integrations section.trueThe following configuration variables are for features that are available for use but may change in future releases.
DD_TRACE_PARTIAL_FLUSH_ENABLEDtrue or false. Added in version 1.26.0, only compatible with the Datadog Agent 7.26.0+.falseDD_TRACE_LOG_PATHDD_TRACE_LOG_DIRECTORY is set.DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLEDtrue. 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.0trueThe Datadog APM Tracer supports B3 and W3C (TraceParent) headers extraction and injection for distributed tracing.
You can configure injection and extraction styles for distributed headers.
The .NET Tracer supports the following styles:
DatadogB3W3CB3SingleHeader or B3 single headerYou can use the following environment variables to configure injection and extraction styles:
DD_PROPAGATION_STYLE_INJECT=Datadog, B3, W3CDD_PROPAGATION_STYLE_EXTRACT=Datadog, B3, W3CThe environment variable values are comma-separated lists of header styles enabled for injection or extraction. By default, only the Datadog injection style is enabled.
If multiple extraction styles are enabled, the extraction attempt is completed in order of configured styles, and uses the first successful extracted value.
Additional helpful documentation, links, and articles:
