Overview

Send custom application metrics into Datadog using the OpenTelemetry (OTel) Metrics API with the Datadog SDK (dd-trace-dotnet).

This is an alternative to using DogStatsD and means you can write code against the standard OTel interfaces while benefiting from all the features of the Datadog SDK.

The Datadog SDK provides a native implementation of the OpenTelemetry API. This means you can write code against the standard OTel interfaces without needing the official OpenTelemetry SDK.

Prerequisites

• .NET Runtime: Requires .NET 6+ (or System.Diagnostics.DiagnosticSource v6.0.0+). See Version and instrument support for a list of supported instruments by version.
• Datadog SDK: dd-trace-dotnet version 3.30.0 or later.
• An OTLP-compatible destination: You must have a destination ready to receive OTLP data, such as the Datadog Agent or OpenTelemetry Collector.

Setup

Follow these steps to enable OTel Metrics API support in your .NET application.

1. Install the Datadog SDK. Follow the installation steps for your runtime:
   • .NET Framework
   • .NET Core
2. Enable OTel metrics by setting the following environment variable:

   export DD_METRICS_OTEL_ENABLED=true
   

Examples

You can use the standard OpenTelemetry API packages to create custom metrics.

Create a counter

This example uses the OTel Metrics API to create a counter that increments every time an item is processed:

using System.Diagnostics.Metrics;

// Define a meter
Meter meter = new("MyService", "1.0.0");

// Create a counter instrument, which will be used to record measurements in your code
Counter<long> requestsCounter = meter.CreateCounter<long>("http.requests_total");

// Perform work
// ...

// Record measurements
requestsCounter.Add(1, new("method", "GET"), new("status_code", "200"));

Create a histogram

This example uses the OTel Metrics API to create a histogram to track request durations:

using System.Diagnostics.Metrics;

// Define a meter
Meter meter = new("MyService", "1.0.0");

// Create a histogram instrument, which will be used to record measurements in your code
Histogram<double> responseTimeHistogram = meter.CreateHistogram<double>("http.response.time");

// Perform work
var watch = System.Diagnostics.Stopwatch.StartNew();
await Task.Delay(1_000);
watch.Stop();

// Record measurements
responseTimeHistogram.Record(watch.ElapsedMilliseconds, new("method", "GET"), new("status_code", "200"));

Supported configuration

To enable this feature, you must set DD_METRICS_OTEL_ENABLED=true.

All OTLP exporter settings (such as endpoints, protocols, and timeouts), resource attributes, and temporality preferences are configured using a shared set of OpenTelemetry environment variables.

For a complete list of all shared OTLP environment variables, see OpenTelemetry Environment Variables Interoperability.

Migrate from other setups

Existing OTel setup

If you are already using the OpenTelemetry SDK with a manual OTLP exporter configuration, follow these steps to migrate:

1. Add the Datadog SDK (dd-trace-dotnet) to your project and enable its instrumentation.
2. Remove any code that manually configures the OtlpExporter for metrics. The Datadog SDK handles this configuration automatically.
3. Remove the OpenTelemetry and OpenTelemetry.Exporter.OpenTelemetryProtocol packages from your project’s dependencies.
4. Set the DD_METRICS_OTEL_ENABLED=true environment variable.

Existing DogStatsD setup

If you are currently using the Datadog DogStatsD client and want to migrate to the OpenTelemetry Metrics API, you need to update your instrumentation code. The main difference is that OTel metrics are configured using environment variables rather than code, and you create Instrument objects first.

Troubleshooting

• Ensure DD_METRICS_OTEL_ENABLED is set to true.

• Verify that your OTLP destination is configured correctly to receive metrics.

• If you are sending data to the Datadog Agent, ensure OTLP ingestion is enabled. See Enabling OTLP Ingestion on the Datadog Agent for details.

• Verify Datadog automatic instrumentation is active. This feature relies on Datadog’s automatic instrumentation to function. Ensure you have completed all setup steps to enable the .NET instrumentation hooks, as these are required to intercept the metric data.

• If, after removing the OpenTelemetry SDK packages, your application fails to compile due to missing APIs in the System.Diagnostics.Metrics namespace, you must update your application by either adding a direct NuGet package reference to System.Diagnostics.DiagnosticSource or upgrading the version of .NET. See .NET version and instrument support for more information.

Further reading

Additional helpful documentation, links, and articles:

Correlate OpenTelemetry Traces and MetricsDOCUMENTATION