.NET Custom Instrumentation

.NET Custom Instrumentation

For instructions on how to setup the .NET Tracer and enable automatic instrumentation, see the .NET setup instructions.

Note: When using both custom and automatic instrumentation, it is important to keep the MSI installer and NuGet package versions in sync.

This page details common use cases for adding and customizing observability with Datadog APM.

Add the Datadog.Trace NuGet package to your application. To create new spans, access the global tracer through the Datadog.Trace.Tracer.Instance property.

Custom instrumentation is supported on .NET Framework 4.6.1+ for Windows, on .NET Core 2.0+ for Windows and Linux, and on .NET 5 and .NET 6 for Windows and Linux.

Add tags and spans

To customize your observability within Datadog, add custom span tags to your spans. Span tags are applied to your incoming traces, allowing you to correlate observed behavior with code-level information such as merchant tier, checkout amount, user ID, etc.

Add custom span tags

Add custom tags to your spans corresponding to any dynamic value within your application code such as customer.id.

Add tags directly to a Datadog.Trace.Span object by calling Span.SetTag(). For example:

public class ShoppingCartController : Controller
    private IShoppingCartRepository _shoppingCartRepository;

    public IActionResult Index(int customerId)
        // Access the active scope through
        // the global tracer (can return null)
        var scope = Tracer.Instance.ActiveScope;

        if (scope != null)
            // Add a tag to the span for use in the Datadog web UI
            scope.Span.SetTag("customer.id", customerId.ToString());

        var cart = _shoppingCartRepository.Get(customerId);

        return View(cart);

Note: Datadog.Trace.Tracer.Instance.ActiveScope returns null if there is no active span.

Adding tags globally to all spans

Use the DD_TAGS environment variable (at the Agent level) to set tags across all generated spans for an application. This can be useful for grouping stats for your applications, data centers, regions, etc. within the Datadog UI. For example:


Set errors on a span

To recognize and mark errors that occur in your code, utilize the Span.SetException(Exception) method available to spans. The method marks the span as an error and adds related span metadata to provide insight into the exception.

    // do work that can throw an exception
catch(Exception e)

This sets three tags on the span: "error.msg":exception.Message, "error.stack":exception.ToString(), and "error.type":exception.GetType().ToString().

Manually creating a new span

Customize your observability by programmatically creating spans around any block of code. Spans created in this manner integrate with other tracing mechanisms automatically. In other words, if a trace has already started, the manual span has its caller as its parent span. Similarly, any traced methods called from the wrapped block of code have the manual span as its parent.

using (var parentScope =
    parentScope.Span.ResourceName = "<RESOURCE NAME>";
    using (var childScope =
        // Nest using statements around the code to trace
        childScope.Span.ResourceName = "<RESOURCE NAME>";

Resource filtering

Traces can be excluded based on their resource name, to remove synthetic traffic such as health checks from reporting traces to Datadog. This and other security and fine-tuning configurations can be found on the Security page.

Further Reading