Overview

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

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.

This approach works with the existing OpenTelemetry SDK. When you enable this feature, the Datadog SDK detects the OTel SDK and configures its OTLP exporter to send metrics to the Datadog Agent.

Note: The OpenTelemetry Metrics SDK for Ruby is currently in alpha implementation. Report issues with the SDK at opentelemetry-ruby/issues.

Prerequisites

• Datadog SDK: datadog gem version 2.23.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 Ruby application.

1. Add the Datadog SDK and OTel gems:

   # Add to your Gemfile
   gem 'datadog', '~> 2.23.0'
   gem 'opentelemetry-metrics-sdk', '~> 0.8'
   gem 'opentelemetry-exporter-otlp-metrics', '~> 0.4'
   

2. bundle install
   

3. Enable OTel metrics by setting the following environment variable:

   export DD_METRICS_OTEL_ENABLED=true
   

4. Configure your application:

   require 'opentelemetry/sdk'
   require 'datadog/opentelemetry'
   
   Datadog.configure do |c|
     # Configure Datadog settings here
   end
   
   # Call after Datadog.configure to initialize metrics
   OpenTelemetry::SDK.configure
   

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:

require 'opentelemetry/api'

# dd-trace-rb automatically configures the MeterProvider
meter = OpenTelemetry.meter_provider.meter('my-service', '1.0.0')

# Counter - monotonically increasing values
counter = meter.create_counter('http.requests_total')
counter.add(1, attributes: { 'method' => 'GET', 'status_code' => '200' })

Create a histogram

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

require 'opentelemetry/api'
require 'time'

# dd-trace-rb automatically configures the MeterProvider
meter = OpenTelemetry.meter_provider.meter('my-service', '1.0.0')

# Histogram - distribution of values
histogram = meter.create_histogram('http.request_duration',
  description: 'HTTP request duration',
  unit: 'ms'
)

start_time = Time.now
# ... simulate work ...
sleep(0.05)
end_time = Time.now

duration = (end_time - start_time) * 1000 # convert to milliseconds
histogram.record(duration, attributes: { 'method' => 'POST', 'route' => '/api/users' })

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 using the OTel SDK with your own manual OTLP exporter configuration:

1. Add the Datadog SDK (datadog) to your project and enable its instrumentation.
2. Remove any code that manually configures the OTLPMetricsExporter. The Datadog SDK handles this configuration automatically.
3. Set the DD_METRICS_OTEL_ENABLED=true environment variable.

Important: Runtime and trace metrics continue to be submitted using StatsD. Only custom metrics created through the OpenTelemetry Metrics API are sent using OTLP. The dd-trace-rb implementation supports exporting OTLP metrics exclusively to a Datadog Agent or OpenTelemetry Collector. Multiple exporters are not supported.

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][200] for details.

• Verify required gems are installed. Ensure opentelemetry-metrics-sdk and opentelemetry-exporter-otlp-metrics are installed in your Ruby environment.

• Ensure Datadog.configure is called before OpenTelemetry::SDK.configure. The Datadog SDK must be configured first to properly set up the meter provider.

Further reading

Más enlaces, artículos y documentación útiles:

Correlate OpenTelemetry Traces and MetricsDOCUMENTATION