feat(otel): add support for otel metrics api via protobuf and json

docs/API.md

@@ -417,6 +417,64 @@ The Datadog SDK supports many of the configurations supported by the OpenTelemet
 
 Logs are exported via OTLP over HTTP. The protocol can be configured using `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` or `OTEL_EXPORTER_OTLP_PROTOCOL` environment variables. Supported protocols are `http/protobuf` (default) and `http/json`. For complete OTLP exporter configuration options, see the [OpenTelemetry OTLP Exporter documentation](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/).
 
+<h3 id="opentelemetry-metrics">OpenTelemetry Metrics</h3>
+
+dd-trace-js includes experimental support for OpenTelemetry metrics, designed as a drop-in replacement for the OpenTelemetry Metrics SDK. This lightweight implementation is fully compliant with the OpenTelemetry Metrics API and integrates with the existing OTLP export infrastructure. Enable it by setting `DD_METRICS_OTEL_ENABLED=true` and use the [OpenTelemetry Metrics API](https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_api.html) to record metric data:
+
+```javascript
+require('dd-trace').init()
+const { metrics } = require('@opentelemetry/api')
+
+const meter = metrics.getMeter('my-service', '1.0.0')
+
+// Counter - monotonically increasing values
+const requestCounter = meter.createCounter('http.requests', {
+  description: 'Total HTTP requests',
+  unit: 'requests'
+})
+requestCounter.add(1, { method: 'GET', status: 200 })
+
+// Histogram - distribution of values
+const durationHistogram = meter.createHistogram('http.duration', {
+  description: 'HTTP request duration',
+  unit: 'ms'
+})
+durationHistogram.record(145, { route: '/api/users' })
+
+// UpDownCounter - can increase and decrease
+const connectionCounter = meter.createUpDownCounter('active.connections', {
+  description: 'Active connections',
+  unit: 'connections'
+})
+connectionCounter.add(1)  // New connection
+connectionCounter.add(-1) // Connection closed
+
+// ObservableGauge - asynchronous observations
+const cpuGauge = meter.createObservableGauge('system.cpu.usage', {
+  description: 'CPU usage percentage',
+  unit: 'percent'
+})
+cpuGauge.addCallback((result) => {
+  const cpuUsage = process.cpuUsage()
+  result.observe(cpuUsage.system / 1000000, { core: '0' })
+})
+```
+
+#### Supported Configuration
+
+The Datadog SDK supports many of the configurations supported by the OpenTelemetry SDK. The following environment variables are supported:
+
+- `DD_METRICS_OTEL_ENABLED` - Enable OpenTelemetry metrics (default: `false`)
+- `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` - OTLP endpoint URL for metrics (default: `http://localhost:4318/v1/metrics`)
+- `OTEL_EXPORTER_OTLP_METRICS_HEADERS` - Optional headers in JSON format for metrics (default: `{}`)
+- `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` - OTLP protocol for metrics (default: `http/protobuf`)
+- `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` - Request timeout in milliseconds for metrics (default: `10000`)
+- `OTEL_METRIC_EXPORT_INTERVAL` - Metric export interval in milliseconds (default: `10000`)
+- `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` - Temporality preference (default: `DELTA`)
+- `OTEL_METRIC_EXPORT_TIMEOUT` - [NOT YET SUPPORTED] Time to export metrics including retries.
+
+Metrics are collected periodically and exported via OTLP over HTTP. The protocol can be configured using `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` or `OTEL_EXPORTER_OTLP_PROTOCOL` environment variables. Supported protocols are `http/protobuf` (default) and `http/json`. All metrics use delta aggregation temporality to match Datadog's data model. For complete OTLP exporter configuration options, see the [OpenTelemetry OTLP Exporter documentation](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/).
+
 <h2 id="advanced-configuration">Advanced Configuration</h2>
 
 <h3 id="tracer-settings">Tracer settings</h3>

packages/dd-trace/src/config.js

@@ -476,6 +476,7 @@ class Config {
       DD_INSTRUMENTATION_CONFIG_ID,
       DD_LOGS_INJECTION,
       DD_LOGS_OTEL_ENABLED,
+      DD_METRICS_OTEL_ENABLED,
       DD_LANGCHAIN_SPAN_CHAR_LIMIT,
       DD_LANGCHAIN_SPAN_PROMPT_COMPLETION_SAMPLE_RATE,
       DD_LLMOBS_AGENTLESS_ENABLED,
@@ -570,12 +571,19 @@ class Config {
       OTEL_EXPORTER_OTLP_LOGS_HEADERS,
       OTEL_EXPORTER_OTLP_LOGS_PROTOCOL,
       OTEL_EXPORTER_OTLP_LOGS_TIMEOUT,
+      OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
+      OTEL_EXPORTER_OTLP_METRICS_HEADERS,
+      OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
+      OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
+      OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE,
+      OTEL_METRIC_EXPORT_TIMEOUT,
       OTEL_EXPORTER_OTLP_PROTOCOL,
       OTEL_EXPORTER_OTLP_ENDPOINT,
       OTEL_EXPORTER_OTLP_HEADERS,
       OTEL_EXPORTER_OTLP_TIMEOUT,
       OTEL_BSP_SCHEDULE_DELAY,
-      OTEL_BSP_MAX_EXPORT_BATCH_SIZE
+      OTEL_BSP_MAX_EXPORT_BATCH_SIZE,
+      OTEL_METRIC_EXPORT_INTERVAL
     } = source
 
     const tags = {}
@@ -606,6 +614,26 @@ class Config {
     target.otelLogsTimeout = maybeInt(OTEL_EXPORTER_OTLP_LOGS_TIMEOUT) || target.otelTimeout
     target.otelLogsBatchTimeout = maybeInt(OTEL_BSP_SCHEDULE_DELAY)
     target.otelLogsMaxExportBatchSize = maybeInt(OTEL_BSP_MAX_EXPORT_BATCH_SIZE)
+
+    const otelMetricsExporter = String(OTEL_METRICS_EXPORTER).toLowerCase() !== 'none'
+    this.#setBoolean(target, 'otelMetricsEnabled', DD_METRICS_OTEL_ENABLED && otelMetricsExporter)
+    // Set OpenTelemetry metrics configuration with specific _METRICS_ vars
+    // taking precedence over generic _EXPORTERS_ vars
+    if (OTEL_EXPORTER_OTLP_ENDPOINT || OTEL_EXPORTER_OTLP_METRICS_ENDPOINT) {
+      this.#setString(target, 'otelMetricsUrl', OTEL_EXPORTER_OTLP_METRICS_ENDPOINT || target.otelUrl)
+    }
+    this.#setString(target, 'otelMetricsHeaders', OTEL_EXPORTER_OTLP_METRICS_HEADERS || target.otelHeaders)
+    this.#setString(target, 'otelMetricsProtocol', OTEL_EXPORTER_OTLP_METRICS_PROTOCOL || target.otelProtocol)
+    target.otelMetricsTimeout = maybeInt(OTEL_EXPORTER_OTLP_METRICS_TIMEOUT) || target.otelTimeout
+    target.otelMetricsExportTimeout = maybeInt(OTEL_METRIC_EXPORT_TIMEOUT)
+    target.otelMetricsExportInterval = maybeInt(OTEL_METRIC_EXPORT_INTERVAL)
+    // Parse temporality preference (default to DELTA for Datadog)
+    if (OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE) {
+      const temporalityPref = OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE.toUpperCase()
+      if (['DELTA', 'CUMULATIVE', 'LOWMEMORY'].includes(temporalityPref)) {
+        this.#setString(target, 'otelMetricsTemporalityPreference', temporalityPref)
+      }
+    }
     this.#setBoolean(
       target,
       'apmTracingEnabled',
@@ -1200,9 +1228,10 @@ class Config {
 
     calc['dogstatsd.hostname'] = this.#getHostname()
 
-    // Compute OTLP logs URL to send payloads to the active Datadog Agent
+    // Compute OTLP logs and metrics URLs to send payloads to the active Datadog Agent
     const agentHostname = this.#getHostname()
     calc.otelLogsUrl = `http://${agentHostname}:${DEFAULT_OTLP_PORT}`
+    calc.otelMetricsUrl = `http://${agentHostname}:${DEFAULT_OTLP_PORT}/v1/metrics`
     calc.otelUrl = `http://${agentHostname}:${DEFAULT_OTLP_PORT}`
 
     this.#setBoolean(calc, 'isGitUploadEnabled',

packages/dd-trace/src/config_defaults.js

@@ -140,6 +140,14 @@ module.exports = {
   otelTimeout: 10_000,
   otelLogsBatchTimeout: 5000,
   otelLogsMaxExportBatchSize: 512,
+  otelMetricsEnabled: false,
+  otelMetricsUrl: undefined, // Will be computed using agent host
+  otelMetricsHeaders: '',
+  otelMetricsProtocol: 'http/protobuf',
+  otelMetricsTimeout: 10_000,
+  otelMetricsExportTimeout: 7500,
+  otelMetricsExportInterval: 10_000,
+  otelMetricsTemporalityPreference: 'DELTA', // DELTA, CUMULATIVE, or LOWMEMORY
   lookup: undefined,
   inferredProxyServicesEnabled: false,
   memcachedCommandEnabled: false,

packages/dd-trace/src/opentelemetry/logs/otlp_http_log_exporter.js

@@ -11,7 +11,7 @@ const OtlpTransformer = require('./otlp_transformer')
 /**
  * OtlpHttpLogExporter exports log records via OTLP over HTTP.
  *
- * This implementation follows the OTLP HTTP specification:
+ * This implementation follows the OTLP HTTP v1.7.0 specification:
  * https://opentelemetry.io/docs/specs/otlp/#otlphttp
  *
  * @class OtlpHttpLogExporter
@@ -37,6 +37,8 @@ class OtlpHttpLogExporter extends OtlpHttpExporterBase {
    *
    * @param {LogRecord[]} logRecords - Array of enriched log records to export
    * @param {Function} resultCallback - Callback function for export result
+   *
+   * @returns {void}
    */
   export (logRecords, resultCallback) {
     if (logRecords.length === 0) {
@@ -45,8 +47,8 @@ class OtlpHttpLogExporter extends OtlpHttpExporterBase {
     }
 
     const payload = this.transformer.transformLogRecords(logRecords)
-    this._sendPayload(payload, resultCallback)
-    this._recordTelemetry('otel.log_records', logRecords.length)
+    this.sendPayload(payload, resultCallback)
+    this.recordTelemetry('otel.log_records', logRecords.length)
   }
 }
 

packages/dd-trace/src/opentelemetry/logs/otlp_transformer.js

@@ -40,7 +40,7 @@ const SEVERITY_MAP = {
 /**
  * OtlpTransformer transforms log records to OTLP format.
  *
- * This implementation follows the OTLP Logs Data Model specification:
+ * This implementation follows the OTLP Logs v1.7.0 Data Model specification:
  * https://opentelemetry.io/docs/specs/otlp/#log-data-model
  *
  * @class OtlpTransformer
@@ -80,12 +80,12 @@ class OtlpTransformer extends OtlpTransformerBase {
 
     const logsData = {
       resourceLogs: [{
-        resource: this._transformResource(),
+        resource: this.transformResource(),
         scopeLogs: this.#transformScope(logRecords),
       }]
     }
 
-    return this._serializeToProtobuf(protoLogsService, logsData)
+    return this.serializeToProtobuf(protoLogsService, logsData)
   }
 
   /**
@@ -97,11 +97,11 @@ class OtlpTransformer extends OtlpTransformerBase {
   #transformToJson (logRecords) {
     const logsData = {
       resourceLogs: [{
-        resource: this._transformResource(),
+        resource: this.transformResource(),
         scopeLogs: this.#transformScope(logRecords)
       }]
     }
-    return this._serializeToJson(logsData)
+    return this.serializeToJson(logsData)
   }
 
   /**
@@ -111,7 +111,7 @@ class OtlpTransformer extends OtlpTransformerBase {
    * @private
    */
   #transformScope (logRecords) {
-    const groupedRecords = this._groupByInstrumentationScope(logRecords)
+    const groupedRecords = this.groupByInstrumentationScope(logRecords)
     const scopeLogs = []
 
     for (const records of groupedRecords.values()) {
@@ -159,7 +159,7 @@ class OtlpTransformer extends OtlpTransformerBase {
     }
 
     if (logRecord.attributes) {
-      result.attributes = this._transformAttributes(logRecord.attributes)
+      result.attributes = this.transformAttributes(logRecord.attributes)
     }
 
     if (spanContext?.traceFlags !== undefined) {
@@ -240,7 +240,7 @@ class OtlpTransformer extends OtlpTransformerBase {
         kvlistValue: {
           values: Object.entries(body).map(([key, value]) => ({
             key,
-            value: this._transformAnyValue(value)
+            value: this.transformAnyValue(value)
           }))
         }
       }

packages/dd-trace/src/opentelemetry/metrics/constants.js

@@ -0,0 +1,28 @@
+'use strict'
+
+// Metric type constants
+const METRIC_TYPES = {
+  HISTOGRAM: 'histogram',
+  COUNTER: 'counter',
+  UPDOWNCOUNTER: 'updowncounter',
+  OBSERVABLECOUNTER: 'observable-counter',
+  OBSERVABLEUPDOWNCOUNTER: 'observable-updowncounter',
+  GAUGE: 'gauge'
+}
+
+// Temporality constants
+const TEMPORALITY = {
+  DELTA: 'DELTA',
+  CUMULATIVE: 'CUMULATIVE',
+  GAUGE: 'GAUGE',
+  LOWMEMORY: 'LOWMEMORY'
+}
+
+// Default histogram bucket boundaries (in milliseconds for latency metrics)
+const DEFAULT_HISTOGRAM_BUCKETS = [0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10_000]
+
+module.exports = {
+  METRIC_TYPES,
+  TEMPORALITY,
+  DEFAULT_HISTOGRAM_BUCKETS
+}

packages/dd-trace/src/opentelemetry/metrics/index.js

@@ -0,0 +1,81 @@
+'use strict'
+
+const os = require('os')
+
+/**
+ * @typedef {import('../../config')} Config
+ */
+
+/**
+ * @fileoverview OpenTelemetry Metrics Implementation for dd-trace-js
+ *
+ * This package provides a custom OpenTelemetry Metrics implementation that integrates
+ * with the Datadog tracing library. It includes all necessary components for
+ * creating instruments, recording measurements, and exporting metrics via OTLP.
+ *
+ * Key Components:
+ * - MeterProvider: Main entry point for creating meters
+ * - Meter: Provides methods to create metric instruments
+ * - Instruments: Gauge, Counter, UpDownCounter, ObservableGauge, ObservableCounter, ObservableUpDownCounter, Histogram
+ * - PeriodicMetricReader: Collects and exports instruments (metrics) at regular intervals
+ * - OtlpHttpMetricExporter: Exports instruments (metrics) via OTLP over HTTP
+ * - OtlpTransformer: Transforms instruments (metrics) to OTLP format
+ *
+ * This is a custom implementation to avoid pulling in the full OpenTelemetry SDK,
+ * based on OTLP Protocol v1.7.0. It supports both protobuf and JSON serialization
+ * formats and integrates with Datadog's configuration system.
+ *
+ * @package
+ */
+
+const MeterProvider = require('./meter_provider')
+const PeriodicMetricReader = require('./periodic_metric_reader')
+const OtlpHttpMetricExporter = require('./otlp_http_metric_exporter')
+
+/**
+ * Initializes OpenTelemetry Metrics support
+ * @param {Config} config - Tracer configuration instance
+ */
+function initializeOpenTelemetryMetrics (config) {
+  // Build resource attributes
+  const resourceAttributes = {
+    'service.name': config.service,
+    'service.version': config.version,
+    'deployment.environment': config.env
+  }
+
+  if (config.tags) {
+    const filteredTags = { ...config.tags }
+    delete filteredTags.service
+    delete filteredTags.version
+    delete filteredTags.env
+    Object.assign(resourceAttributes, filteredTags)
+  }
+
+  if (config.reportHostname) {
+    resourceAttributes['host.name'] = os.hostname()
+  }
+
+  const exporter = new OtlpHttpMetricExporter(
+    config.otelMetricsUrl,
+    config.otelMetricsHeaders,
+    config.otelMetricsTimeout,
+    config.otelMetricsProtocol,
+    resourceAttributes
+  )
+
+  const reader = new PeriodicMetricReader(
+    exporter,
+    config.otelMetricsExportInterval,
+    config.otelMetricsTemporalityPreference
+  )
+
+  const meterProvider = new MeterProvider({ reader })
+
+  meterProvider.register()
+}
+
+module.exports = {
+  MeterProvider,
+  initializeOpenTelemetryMetrics
+}