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. If the Agent configuration 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.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. If the Agent configuration 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.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_RULESnullsample_rate value must be between 0.0 and 1.0 (inclusive). For more information, see Ingestion Mechanisms.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_TRACE_CLIENT_IP_HEADERx-forwarded-for.2.19.0."x-forwarded-for", "x-real-ip", "client-ip", "x-forwarded", "x-cluster-client-ip", "forwarded-for", "forwarded", "via", "true-client-ip". If several are present, none will be reported.DD_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_DBM_PROPAGATION_MODE'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.'disabled'DD_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. 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 for more details.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:
tracecontext (W3C is deprecated)Datadogb3multi (B3 is deprecated)B3 single header (B3SingleHeader is deprecated)You can use the following environment variables to configure injection and extraction styles:
DD_TRACE_PROPAGATION_STYLE_INJECT=tracecontext, Datadog, b3multiDD_TRACE_PROPAGATION_STYLE_EXTRACT=tracecontext, Datadog, b3multiThe environment variable values are comma-separated lists of header styles enabled for injection or extraction. If multiple extraction styles are enabled, the extraction attempt is completed in the order of configured styles, and uses the first successful extracted value.
Starting from version 2.22.0, the default injection style is tracecontext, Datadog, so the W3C context is used, followed by the Datadog headers. Prior to version 2.22.0, only the Datadog injection style is enabled.
Additional helpful documentation, links, and articles:
