dd-trace 5.80.0 → 5.81.0

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

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

@@ -0,0 +1,251 @@
+'use strict'
+
+const OtlpTransformerBase = require('../otlp/otlp_transformer_base')
+const { getProtobufTypes } = require('../otlp/protobuf_loader')
+const { METRIC_TYPES, TEMPORALITY } = require('./constants')
+
+const { protoAggregationTemporality } = getProtobufTypes()
+const AGGREGATION_TEMPORALITY_DELTA = protoAggregationTemporality.values.AGGREGATION_TEMPORALITY_DELTA
+const AGGREGATION_TEMPORALITY_CUMULATIVE = protoAggregationTemporality.values.AGGREGATION_TEMPORALITY_CUMULATIVE
+
+/**
+ * @typedef {import('./periodic_metric_reader').AggregatedMetric} AggregatedMetric
+ * @typedef {import('./periodic_metric_reader').NumberDataPoint} NumberDataPoint
+ * @typedef {import('./periodic_metric_reader').HistogramDataPoint} HistogramDataPoint
+ */
+
+/**
+ * OtlpTransformer transforms metrics to OTLP format.
+ *
+ * This implementation follows the OTLP Metrics v1.7.0 Data Model specification:
+ * https://opentelemetry.io/docs/specs/otlp/#metrics-data-model
+ *
+ * @class OtlpTransformer
+ * @augments OtlpTransformerBase
+ */
+class OtlpTransformer extends OtlpTransformerBase {
+  /**
+   * Creates a new OtlpTransformer instance.
+   *
+   * @param {import('@opentelemetry/api').Attributes} resourceAttributes - Resource attributes
+   * @param {string} protocol - OTLP protocol (http/protobuf or http/json)
+   */
+  constructor (resourceAttributes, protocol) {
+    super(resourceAttributes, protocol, 'metrics')
+  }
+
+  /**
+   * Transforms metrics to OTLP format based on the configured protocol.
+   * @param {Iterable<AggregatedMetric>} metrics - Iterable of metric data to transform
+   * @returns {Buffer} Transformed metrics in the appropriate format
+   */
+  transformMetrics (metrics) {
+    if (this.protocol === 'http/json') {
+      return this.#transformToJson(metrics)
+    }
+    return this.#transformToProtobuf(metrics)
+  }
+
+  /**
+   * Transforms metrics to protobuf format.
+   * @param {Iterable<AggregatedMetric>} metrics - Iterable of metrics to transform
+   * @returns {Buffer} Protobuf-encoded metrics
+   *
+   */
+  #transformToProtobuf (metrics) {
+    const { protoMetricsService } = getProtobufTypes()
+
+    const metricsData = {
+      resourceMetrics: [{
+        resource: this.transformResource(),
+        scopeMetrics: this.#transformScope(metrics),
+      }]
+    }
+
+    return this.serializeToProtobuf(protoMetricsService, metricsData)
+  }
+
+  /**
+   * Transforms metrics to JSON format.
+   * @param {Array} metrics - Array of metrics to transform
+   * @returns {Buffer} JSON-encoded metrics
+   *
+   */
+  #transformToJson (metrics) {
+    const metricsData = {
+      resourceMetrics: [{
+        resource: this.transformResource(),
+        scopeMetrics: this.#transformScope(metrics, true)
+      }]
+    }
+    return this.serializeToJson(metricsData)
+  }
+
+  /**
+   * Creates scope metrics grouped by instrumentation scope.
+   * @param {Iterable<AggregatedMetric>} metrics - Iterable of metrics to transform
+   * @param {boolean} isJson - Whether to format for JSON output
+   * @returns {Array<Object>} Array of scope metric objects
+   *
+   */
+  #transformScope (metrics, isJson = false) {
+    const groupedMetrics = this.groupByInstrumentationScope(metrics)
+    const scopeMetrics = []
+
+    for (const metricsInScope of groupedMetrics.values()) {
+      const firstMetric = metricsInScope[0]
+      const instrumentationScope = firstMetric.instrumentationScope || {}
+      const { name = '', version = '', schemaUrl = '', attributes = {} } = instrumentationScope
+
+      const scope = {
+        name,
+        version,
+        droppedAttributesCount: 0
+      }
+
+      if (attributes) {
+        const transformed = isJson ? this.attributesToJson(attributes) : this.transformAttributes(attributes)
+        if (transformed.length) {
+          scope.attributes = transformed
+        }
+      }
+
+      scopeMetrics.push({
+        scope,
+        schemaUrl,
+        metrics: metricsInScope.map(metric => this.#transformMetric(metric, isJson))
+      })
+    }
+
+    return scopeMetrics
+  }
+
+  /**
+   * Transforms a single metric to protobuf or JSON format.
+   *
+   * @param {AggregatedMetric} metric - The metric to transform
+   * @param {boolean} isJson - Whether to output JSON format (vs protobuf)
+   * @returns {Object} - The metric transformed to OTLP protobuf or JSON format
+   */
+  #transformMetric (metric, isJson = false) {
+    const result = {
+      name: metric.name,
+      description: metric.description || '',
+      unit: metric.unit || ''
+    }
+
+    const isCumulative = metric.temporality === TEMPORALITY.CUMULATIVE
+    let temporality
+    if (isJson) {
+      temporality = isCumulative ? 'AGGREGATION_TEMPORALITY_CUMULATIVE' : 'AGGREGATION_TEMPORALITY_DELTA'
+    } else {
+      temporality = isCumulative ? AGGREGATION_TEMPORALITY_CUMULATIVE : AGGREGATION_TEMPORALITY_DELTA
+    }
+
+    switch (metric.type) {
+      case METRIC_TYPES.HISTOGRAM:
+        result.histogram = {
+          dataPoints: Array.from(metric.dataPointMap.values(), dp => this.#transformHistogramDataPoint(dp, isJson)),
+          aggregationTemporality: temporality
+        }
+        break
+
+      case METRIC_TYPES.COUNTER:
+      case METRIC_TYPES.OBSERVABLECOUNTER:
+      case METRIC_TYPES.UPDOWNCOUNTER:
+      case METRIC_TYPES.OBSERVABLEUPDOWNCOUNTER:
+        result.sum = {
+          dataPoints: Array.from(metric.dataPointMap.values(), dp => this.#transformNumberDataPoint(dp, isJson)),
+          aggregationTemporality: temporality,
+          isMonotonic: metric.type === METRIC_TYPES.COUNTER || metric.type === METRIC_TYPES.OBSERVABLECOUNTER
+        }
+        break
+
+      case METRIC_TYPES.GAUGE:
+        result.gauge = {
+          dataPoints: Array.from(metric.dataPointMap.values(), dp => this.#transformNumberDataPoint(dp, isJson))
+        }
+        break
+    }
+
+    return result
+  }
+
+  /**
+   * Transforms a histogram data point.
+   *
+   * @param {HistogramDataPoint} dp - The histogram data point to transform
+   * @param {boolean} isJson - Whether to output JSON format (vs protobuf)
+   * @returns {Object} The histogram data point transformed to OTLP protobuf format
+   */
+  #transformHistogramDataPoint (dp, isJson) {
+    const attributes = isJson
+      ? this.attributesToJson(dp.attributes)
+      : this.transformAttributes(dp.attributes)
+
+    const dataPoint = {
+      attributes,
+      startTimeUnixNano: dp.startTimeUnixNano,
+      timeUnixNano: dp.timeUnixNano,
+      count: dp.count,
+      sum: dp.sum,
+      bucketCounts: dp.bucketCounts || [],
+      explicitBounds: dp.explicitBounds || [],
+      min: dp.min,
+      max: dp.max
+    }
+
+    if (isJson) {
+      dataPoint.startTimeUnixNano = String(dataPoint.startTimeUnixNano)
+      dataPoint.timeUnixNano = String(dataPoint.timeUnixNano)
+      dataPoint.count = dataPoint.count || 0
+    }
+
+    return dataPoint
+  }
+
+  /**
+   * Transforms a number data point to protobuf or JSON format.
+   *
+   * @param {NumberDataPoint} dataPoint - The number data point to transform
+   * @param {boolean} isJson - Whether to output JSON format (vs protobuf)
+   * @returns {Object} The number data point transformed to OTLP protobuf format
+   */
+  #transformNumberDataPoint (dataPoint, isJson) {
+    const attributes = isJson
+      ? this.attributesToJson(dataPoint.attributes)
+      : this.transformAttributes(dataPoint.attributes)
+    const timeUnixNano = isJson
+      ? String(dataPoint.timeUnixNano)
+      : dataPoint.timeUnixNano
+
+    const result = {
+      attributes,
+      timeUnixNano
+    }
+
+    if (dataPoint.startTimeUnixNano) {
+      result.startTimeUnixNano = isJson ? String(dataPoint.startTimeUnixNano) : dataPoint.startTimeUnixNano
+    }
+
+    this.#assignNumberValue(result, dataPoint.value)
+    return result
+  }
+
+  /**
+   * Assigns the appropriate value field (asInt or asDouble) based on the value type.
+   *
+   * @param {NumberDataPoint} dataPoint - The number data point to assign a value to
+   * @param {number} value - The value to assign
+   * @returns {void}
+   */
+  #assignNumberValue (dataPoint, value) {
+    if (Number.isInteger(value)) {
+      dataPoint.asInt = value
+    } else {
+      dataPoint.asDouble = value
+    }
+  }
+}
+
+module.exports = OtlpTransformer