dd-trace 5.79.0 → 5.81.0

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

@@ -0,0 +1,81 @@
+'use strict'
+
+const os = require('os')
+
+/**
+ * @typedef {import('../../config')} Config
+ */
+
+/**
+ * @file 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 { metrics } = require('@opentelemetry/api')
+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) {
+  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,
+    config.otelMaxQueueSize
+  )
+
+  const meterProvider = new MeterProvider({ reader })
+  metrics.setGlobalMeterProvider(meterProvider)
+}
+
+module.exports = {
+  MeterProvider,
+  initializeOpenTelemetryMetrics
+}

package/packages/dd-trace/src/opentelemetry/metrics/instruments.js

@@ -0,0 +1,225 @@
+'use strict'
+
+const { sanitizeAttributes } = require('../../../../../vendor/dist/@opentelemetry/core')
+const { METRIC_TYPES } = require('./constants')
+
+/**
+ * @typedef {import('@opentelemetry/api').Attributes} Attributes
+ * @typedef {import('@opentelemetry/core').InstrumentationScope} InstrumentationScope
+ */
+
+/**
+ * @typedef {Object} Measurement
+ * @property {string} name - Instrument name
+ * @property {string} description - Instrument description
+ * @property {string} unit - Measurement unit
+ * @property {InstrumentationScope} instrumentationScope - Instrumentation scope
+ * @property {string} type - Metric type from METRIC_TYPES
+ * @property {number} value - Measured value
+ * @property {Attributes} attributes - Sanitized metric attributes
+ * @property {number} timestamp - Timestamp in nanoseconds
+ */
+
+/**
+ * Base class for all metric instruments.
+ *
+ *
+ */
+class Instrument {
+  /**
+   * Creates a new instrument instance.
+   *
+   * @param {string} name - Instrument name (e.g., 'http.request.duration')
+   * @param {Object} options - Instrument configuration options
+   * @param {string} [options.description] - Human-readable description of the instrument
+   * @param {string} [options.unit] - Unit of measurement (e.g., 'ms', 'bytes', '1')
+   * @param {InstrumentationScope} instrumentationScope - Instrumentation scope for this instrument
+   * @param {Object} reader - Metric reader for recording measurements
+   */
+  constructor (name, options, instrumentationScope, reader) {
+    this.name = name
+    this.description = options.description ?? ''
+    this.unit = options.unit ?? ''
+    this.valueType = options.valueType // currently ignored, TODO: add support for ValueType
+    this.advice = options.advice // currently ignored, TODO: add support for MetricAdvice
+    this.instrumentationScope = instrumentationScope
+    this.reader = reader
+  }
+
+  /**
+   * Creates a measurement object for recording metric values.
+   * @param {string} type - Metric type from METRIC_TYPES
+   * @param {number} value - Numeric value to record
+   * @param {Attributes} attributes - Key-value pairs for metric dimensions
+   * @returns {Measurement} Measurement object with metadata and timestamp
+   */
+  createMeasurement (type, value, attributes) {
+    return {
+      name: this.name,
+      description: this.description,
+      unit: this.unit,
+      instrumentationScope: this.instrumentationScope,
+      type,
+      value,
+      attributes: sanitizeAttributes(attributes),
+      timestamp: Number(process.hrtime.bigint())
+    }
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry Counter interface:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Counter.html
+ * @class Counter
+ */
+class Counter extends Instrument {
+  add (value, attributes = {}) {
+    if (value < 0) return
+    this.reader?.record(this.createMeasurement(METRIC_TYPES.COUNTER, value, attributes))
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry UpDownCounter interface:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.UpDownCounter.html
+ * @class UpDownCounter
+ */
+class UpDownCounter extends Instrument {
+  add (value, attributes = {}) {
+    this.reader?.record(this.createMeasurement(METRIC_TYPES.UPDOWNCOUNTER, value, attributes))
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry Histogram interface:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Histogram.html
+ * @class Histogram
+ */
+class Histogram extends Instrument {
+  record (value, attributes = {}) {
+    if (value < 0) return
+    this.reader?.record(this.createMeasurement(METRIC_TYPES.HISTOGRAM, value, attributes))
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry Gauge interface:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Gauge.html
+ * @class Gauge
+ */
+class Gauge extends Instrument {
+  record (value, attributes = {}) {
+    this.reader?.record(this.createMeasurement(METRIC_TYPES.GAUGE, value, attributes))
+  }
+}
+
+/**
+ * Base class for observable (asynchronous) instruments.
+ * Implementation of the OpenTelemetry Observable interface:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Observable.html
+ *
+ */
+class ObservableInstrument extends Instrument {
+  #callbacks = []
+  #type
+
+  constructor (name, options, instrumentationScope, reader, type) {
+    super(name, options, instrumentationScope, reader)
+    this.#type = type
+  }
+
+  /**
+   * Adds a callback to invoke during metric collection.
+   *
+   * @param {Function} callback - Receives an ObservableResult to record observations
+   */
+  addCallback (callback) {
+    if (typeof callback !== 'function') return
+    this.#callbacks.push(callback)
+    this.reader?.observableInstruments.add(this)
+  }
+
+  /**
+   * Removes a callback.
+   *
+   * @param {Function} callback - The callback to remove
+   */
+  removeCallback (callback) {
+    const index = this.#callbacks.indexOf(callback)
+    if (index !== -1) {
+      this.#callbacks.splice(index, 1)
+      if (this.#callbacks.length === 0) {
+        // Remove instrument from collection when no callbacks remain
+        this.reader?.observableInstruments.delete(this)
+      }
+    }
+  }
+
+  /**
+   * Collects observations from all callbacks. Errors are silently ignored.
+   *
+   * @returns {Array<Measurement>} Array of measurements
+   */
+  collect () {
+    const observations = []
+    const observableResult = {
+      observe: (value, attributes = {}) => {
+        observations.push(this.createMeasurement(this.#type, value, attributes))
+      }
+    }
+
+    for (const callback of this.#callbacks) {
+      try {
+        callback(observableResult)
+      } catch {
+        // Ignore callback errors per OpenTelemetry spec to prevent disruption
+        // Errors are swallowed as callbacks should not break metric collection
+      }
+    }
+
+    return observations
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry ObservableGauge interface:
+ * https://open-telemetry.github.io/opentelemetry-js/types/_opentelemetry_api._opentelemetry_api.ObservableGauge.html
+ * @class ObservableGauge
+ */
+class ObservableGauge extends ObservableInstrument {
+  constructor (name, options, instrumentationScope, reader) {
+    super(name, options, instrumentationScope, reader, METRIC_TYPES.GAUGE)
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry ObservableCounter interface:
+ * https://open-telemetry.github.io/opentelemetry-js/types/_opentelemetry_api._opentelemetry_api.ObservableCounter.html
+ * @class ObservableCounter
+ */
+class ObservableCounter extends ObservableInstrument {
+  constructor (name, options, instrumentationScope, reader) {
+    super(name, options, instrumentationScope, reader, METRIC_TYPES.OBSERVABLECOUNTER)
+  }
+}
+
+/**
+ * Implementation of the OpenTelemetry ObservableUpDownCounter interface:
+ * https://open-telemetry.github.io/opentelemetry-js/types/_opentelemetry_api._opentelemetry_api.ObservableUpDownCounter.html
+ * @class ObservableUpDownCounter
+ */
+class ObservableUpDownCounter extends ObservableInstrument {
+  constructor (name, options, instrumentationScope, reader) {
+    super(name, options, instrumentationScope, reader, METRIC_TYPES.OBSERVABLEUPDOWNCOUNTER)
+  }
+}
+
+module.exports = {
+  Counter,
+  UpDownCounter,
+  Histogram,
+  Gauge,
+  ObservableGauge,
+  ObservableCounter,
+  ObservableUpDownCounter
+}

package/packages/dd-trace/src/opentelemetry/metrics/meter.js

@@ -0,0 +1,171 @@
+'use strict'
+
+const { VERSION: packageVersion } = require('../../../../../version')
+const {
+  Counter, UpDownCounter, Histogram, Gauge, ObservableGauge, ObservableCounter, ObservableUpDownCounter
+} = require('./instruments')
+const log = require('../../log')
+const { METRIC_TYPES } = require('./constants')
+
+/**
+ * @typedef {import('@opentelemetry/api').MetricOptions} MetricOptions
+ * @typedef {import('@opentelemetry/core').InstrumentationScope} InstrumentationScope
+ */
+
+/**
+ * Meter provides methods to create metric instruments.
+ *
+ * This implementation follows the OpenTelemetry JavaScript API Meter:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Meter.html
+ *
+ * @class Meter
+ */
+class Meter {
+  #instrumentationScope
+  #instruments = new Map()
+  /**
+   * Creates a new Meter instance.
+   *
+   * @param {MeterProvider} meterProvider - Parent meter provider
+   * @param {InstrumentationScope} instrumentationScope - Instrumentation scope information
+   * @param {string} [instrumentationScope.name] - Meter name (defaults to 'dd-trace-js')
+   * @param {string} [instrumentationScope.version] - Meter version (defaults to tracer version)
+   * @param {string} [instrumentationScope.schemaUrl] - Schema URL
+   * @param {Object} [instrumentationScope.attributes] - Attributes for the instrumentation scope
+   */
+  constructor (
+    meterProvider,
+    { name = 'dd-trace-js', version = packageVersion, schemaUrl = '', attributes = {} } = {}
+  ) {
+    this.meterProvider = meterProvider
+    this.#instrumentationScope = {
+      name,
+      version,
+      schemaUrl,
+      attributes,
+    }
+  }
+
+  /**
+   * Gets an existing instrument or creates a new one if it doesn't exist.
+   * Instruments are cached by type and normalized (lowercase) name.
+   *
+   *
+   * @param {string} name - Instrument name (will be normalized to lowercase)
+   * @param {string} type - Instrument type (e.g., 'counter', 'histogram', 'gauge')
+   * @param {Function} InstrumentClass - Constructor for the instrument type
+   * @param {MetricOptions} [options] - Instrument options (description, unit, etc.)
+   * @returns {Instrument} The instrument instance (new or cached)
+   */
+  #getOrCreateInstrument (name, type, InstrumentClass, options) {
+    const normalizedName = name.toLowerCase()
+    const key = `${type}:${normalizedName}`
+    let instrument = this.#instruments.get(key)
+    if (!instrument) {
+      instrument = new InstrumentClass(
+        normalizedName, options, this.#instrumentationScope, this.meterProvider.reader
+      )
+      this.#instruments.set(key, instrument)
+    }
+    return instrument
+  }
+
+  /**
+   * Creates a Counter instrument.
+   *
+   * @param {string} name - Instrument name (case-insensitive)
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {Counter} Counter instrument
+   */
+  createCounter (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.COUNTER, Counter, options)
+  }
+
+  /**
+   * Creates an UpDownCounter instrument.
+   *
+   * @param {string} name - Instrument name
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {UpDownCounter} UpDownCounter instrument
+   */
+  createUpDownCounter (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.UPDOWNCOUNTER, UpDownCounter, options)
+  }
+
+  /**
+   * Creates a Histogram instrument.
+   *
+   * @param {string} name - Instrument name (case-insensitive)
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {Histogram} Histogram instrument
+   */
+  createHistogram (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.HISTOGRAM, Histogram, options)
+  }
+
+  /**
+   * Creates a Gauge instrument.
+   *
+   * @param {string} name - Instrument name (case-insensitive)
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {Gauge} Gauge instrument
+   */
+  createGauge (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.GAUGE, Gauge, options)
+  }
+
+  /**
+   * Creates an ObservableGauge instrument.
+   *
+   * @param {string} name - Instrument name (case-insensitive)
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {ObservableGauge} ObservableGauge instrument
+   */
+  createObservableGauge (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.OBSERVABLEGAUGE, ObservableGauge, options)
+  }
+
+  /**
+   * Creates an ObservableCounter instrument.
+   *
+   * @param {string} name - Instrument name (case-insensitive)
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {ObservableCounter} ObservableCounter instrument
+   */
+  createObservableCounter (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.OBSERVABLECOUNTER, ObservableCounter, options)
+  }
+
+  /**
+   * Creates an ObservableUpDownCounter instrument.
+   *
+   * @param {string} name - Instrument name (case-insensitive)
+   * @param {MetricOptions} [options] - Instrument options
+   * @returns {ObservableUpDownCounter} ObservableUpDownCounter instrument
+   */
+  createObservableUpDownCounter (name, options = {}) {
+    return this.#getOrCreateInstrument(name, METRIC_TYPES.OBSERVABLEUPDOWNCOUNTER, ObservableUpDownCounter, options)
+  }
+
+  /**
+   * Adds a batch observable callback (not implemented).
+   *
+   * @param {Function} callback - Batch observable callback
+   * @param {Array} observables - Array of observable instruments
+   */
+  addBatchObservableCallback (callback, observables) {
+    log.warn('addBatchObservableCallback is not implemented')
+  }
+
+  /**
+   * Removes a batch observable callback (not implemented).
+   *
+   * @param {Function} callback - Batch observable callback
+   * @param {Array} observables - Array of observable instruments
+   */
+  removeBatchObservableCallback (callback, observables) {
+    log.warn('removeBatchObservableCallback is not implemented')
+  }
+}
+
+module.exports = Meter

package/packages/dd-trace/src/opentelemetry/metrics/meter_provider.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const Meter = require('./meter')
+
+/**
+ * @typedef {import('@opentelemetry/api').Meter} Meter
+ * @typedef {import('@opentelemetry/api').MeterOptions} MeterOptions
+ * @typedef {import('./periodic_metric_reader')} PeriodicMetricReader
+ */
+
+/**
+ * MeterProvider is the main entry point for creating meters with a single reader for Datadog Agent export.
+ *
+ * This implementation follows the OpenTelemetry JavaScript API MeterProvider interface:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.MeterProvider.html
+ *
+ * @class MeterProvider
+ * @implements {import('@opentelemetry/api').MeterProvider}
+ */
+class MeterProvider {
+  #meters = new Map()
+
+  /**
+   * Creates a new MeterProvider instance with a single reader for Datadog Agent export.
+   *
+   * @param {MeterOptions} [options] - MeterProvider options
+   * @param {PeriodicMetricReader} [options.reader] - Single MetricReader instance for
+   *   exporting metrics to Datadog Agent
+   */
+  constructor (options = {}) {
+    this.reader = options.reader
+  }
+
+  /**
+   * Gets or creates a meter instance.
+   *
+   * @param {string} name - Meter name (case-insensitive)
+   * @param {string} [version] - Meter version
+   * @param {MeterOptions} [options] - Additional options
+   * @returns {Meter} Meter instance
+   */
+  getMeter (name, version = '', { schemaUrl = '', attributes = {} } = {}) {
+    const normalizedName = name.toLowerCase()
+    const key = `${normalizedName}@${version}@${schemaUrl}`
+    let meter = this.#meters.get(key)
+    if (!meter) {
+      meter = new Meter(this, { name: normalizedName, version, schemaUrl, attributes })
+      this.#meters.set(key, meter)
+    }
+    return meter
+  }
+}
+
+module.exports = MeterProvider

package/packages/dd-trace/src/opentelemetry/metrics/otlp_http_metric_exporter.js

@@ -0,0 +1,62 @@
+'use strict'
+
+const OtlpHttpExporterBase = require('../otlp/otlp_http_exporter_base')
+const OtlpTransformer = require('./otlp_transformer')
+
+/**
+ * @typedef {import('@opentelemetry/resources').Resource} Resource
+ * @typedef {import('./periodic_metric_reader').AggregatedMetric} AggregatedMetric
+ */
+
+/**
+ * OtlpHttpMetricExporter exports metrics via OTLP over HTTP.
+ *
+ * @class OtlpHttpMetricExporter
+ */
+class OtlpHttpMetricExporter extends OtlpHttpExporterBase {
+  /**
+   * Creates a new OtlpHttpMetricExporter instance.
+   *
+   * @param {string} url - OTLP endpoint URL
+   * @param {string} headers - Additional HTTP headers as comma-separated key=value string
+   * @param {number} timeout - Request timeout in milliseconds
+   * @param {string} protocol - OTLP protocol (http/protobuf or http/json)
+   * @param {Resource} resource - Resource attributes
+   */
+  constructor (url, headers, timeout, protocol, resource) {
+    super(url, headers, timeout, protocol, '/v1/metrics', 'metrics')
+    this.transformer = new OtlpTransformer(resource, protocol)
+  }
+
+  /**
+   * Exports metrics via OTLP over HTTP.
+   *
+   * @param {Map<string, AggregatedMetric>} metrics - Map of metric data to export
+   *
+   * @returns {void}
+   */
+  export (metrics) {
+    if (metrics.size === 0) {
+      return
+    }
+
+    let dataPointCount = 0
+    for (const metric of metrics.values()) {
+      if (metric.dataPointMap) {
+        dataPointCount += metric.dataPointMap.size
+      }
+    }
+
+    const additionalTags = [`points:${dataPointCount}`]
+    this.recordTelemetry('otel.metrics_export_attempts', 1, additionalTags)
+
+    const payload = this.transformer.transformMetrics(metrics.values())
+    this.sendPayload(payload, (result) => {
+      if (result.code === 0) {
+        this.recordTelemetry('otel.metrics_export_successes', 1, additionalTags)
+      }
+    })
+  }
+}
+
+module.exports = OtlpHttpMetricExporter