dd-trace 5.71.0 → 5.72.0

package/packages/dd-trace/src/openfeature/writers/base.js

@@ -0,0 +1,181 @@
+'use strict'
+
+const request = require('../../exporters/common/request')
+const { safeJSONStringify } = require('../../exporters/common/util')
+const { URL, format } = require('node:url')
+
+const log = require('../../log')
+
+/**
+ * @typedef {Object} BaseFFEWriterOptions
+ * @property {number} [interval] - Flush interval in milliseconds
+ * @property {number} [timeout] - Request timeout in milliseconds
+ * @property {Object} config - Tracer configuration object
+ * @property {string} endpoint - API endpoint path
+ * @property {URL} [agentUrl] - Base URL for the agent
+ * @property {number} [payloadSizeLimit] - Maximum payload size in bytes
+ * @property {number} [eventSizeLimit] - Maximum individual event size in bytes
+ * @property {Object} [headers] - Additional HTTP headers
+ */
+
+/**
+ * BaseFFEWriter is the base class for sending Feature Flagging & Exposure Events payloads to the Datadog Agent.
+ * @class BaseFFEWriter
+ */
+class BaseFFEWriter {
+  /**
+   * @param {BaseFFEWriterOptions} options - Writer configuration options
+   */
+  constructor ({ interval, timeout, config, endpoint, agentUrl, payloadSizeLimit, eventSizeLimit, headers }) {
+    this._interval = interval ?? 1000
+    this._timeout = timeout ?? 5000
+
+    this._buffer = []
+    this._bufferLimit = 1000
+    this._bufferSize = 0
+
+    this._config = config
+    this._endpoint = endpoint
+    this._baseUrl = agentUrl ?? this._getAgentUrl()
+    this._payloadSizeLimit = payloadSizeLimit
+    this._eventSizeLimit = eventSizeLimit
+    this._headers = headers || {}
+
+    this._requestOptions = {
+      headers: {
+        ...this._headers,
+        'Content-Type': 'application/json'
+      },
+      method: 'POST',
+      timeout: this._timeout,
+      url: this._baseUrl,
+      path: this._endpoint
+    }
+
+    this._periodic = setInterval(() => {
+      this.flush()
+    }, this._interval).unref()
+
+    this._beforeExitHandler = () => {
+      this.destroy()
+    }
+    process.once('beforeExit', this._beforeExitHandler)
+
+    this._destroyed = false
+    this._droppedEvents = 0
+  }
+
+  /**
+   * Appends an event array to the buffer
+   * @param {Array|Object} events - Event object(s) to append to buffer
+   */
+  append (events) {
+    const eventArray = Array.isArray(events) ? events : [events]
+
+    for (const event of eventArray) {
+      if (this._buffer.length >= this._bufferLimit) {
+        log.warn(`${this.constructor.name} event buffer full (limit is ${this._bufferLimit}), dropping event`)
+        this._droppedEvents++
+        continue
+      }
+
+      const eventSizeBytes = Buffer.byteLength(JSON.stringify(event))
+
+      // Check individual event size limit if configured
+      if (this._eventSizeLimit && eventSizeBytes > this._eventSizeLimit) {
+        log.warn(`${this.constructor.name} event size
+          ${eventSizeBytes} bytes exceeds limit ${this._eventSizeLimit}, dropping event`)
+        this._droppedEvents++
+        continue
+      }
+
+      // Check if adding this event would exceed payload size limit if configured
+      if (this._payloadSizeLimit && this._bufferSize + eventSizeBytes > this._payloadSizeLimit) {
+        log.debug(() => `${this.constructor.name}
+        buffer size would exceed ${this._payloadSizeLimit} bytes, flushing first`)
+        this.flush()
+      }
+
+      this._bufferSize += eventSizeBytes
+      this._buffer.push(event)
+    }
+  }
+
+  /**
+   * Flushes all buffered events to the agent
+   */
+  flush () {
+    if (this._buffer.length === 0) {
+      return
+    }
+    const events = this._buffer
+    this._buffer = []
+    this._bufferSize = 0
+
+    const payload = this._encode(this.makePayload(events))
+
+    log.debug(() => `${this.constructor.name} flushing payload: ${safeJSONStringify(payload)}`)
+
+    request(payload, this._requestOptions, (err, resp, code) => {
+      if (err) {
+        log.error(`Failed to send events to ${this._baseUrl.href}${this._endpoint}: ${err.message}`)
+      } else if (code >= 200 && code < 300) {
+        log.debug(() => `Successfully sent ${events.length} events`)
+      } else {
+        log.warn(`Events request returned status ${code}`)
+      }
+    })
+  }
+
+  /**
+   * Override in subclass to customize payload structure
+   * @param {Array} events - Array of events to be sent
+   * @returns {object} Formatted payload
+   */
+  makePayload (events) {
+    // Override in subclass
+    return events
+  }
+
+  /**
+   * Cleans up resources and flushes remaining events
+   */
+  destroy () {
+    if (!this._destroyed) {
+      log.debug(() => `Stopping ${this.constructor.name}`)
+      clearInterval(this._periodic)
+      process.removeListener('beforeExit', this._beforeExitHandler)
+      this.flush()
+      this._destroyed = true
+
+      if (this._droppedEvents > 0) {
+        log.warn(`${this.constructor.name} dropped ${this._droppedEvents} events due to buffer overflow`)
+      }
+    }
+  }
+
+  /**
+   * @private
+   * @returns {URL} Constructs agent URL from config
+   */
+  _getAgentUrl () {
+    const { hostname, port } = this._config
+
+    return this._config.url ?? new URL(format({
+      protocol: 'http:',
+      hostname: hostname || 'localhost',
+      port: port || 8126
+    }))
+  }
+
+  /**
+   * @private
+   * @param {Array<object>} payload - Payload to encode
+   * @returns {string} JSON-stringified payload
+   */
+  _encode (payload) {
+    return JSON.stringify(payload)
+  }
+}
+
+module.exports = BaseFFEWriter

package/packages/dd-trace/src/openfeature/writers/exposures.js

@@ -0,0 +1,173 @@
+'use strict'
+
+const BaseFFEWriter = require('./base')
+const {
+  EXPOSURES_ENDPOINT,
+  EVP_PROXY_AGENT_BASE_PATH,
+  EVP_SUBDOMAIN_HEADER_NAME,
+  EVP_SUBDOMAIN_VALUE,
+  EVP_PAYLOAD_SIZE_LIMIT,
+  EVP_EVENT_SIZE_LIMIT
+} = require('../constants/constants')
+
+/**
+ * @typedef {Object} ExposureEvent
+ * @property {number} timestamp - Unix timestamp in milliseconds
+ * @property {Object} allocation - Allocation information
+ * @property {string} allocation.key - Allocation key
+ * @property {Object} flag - Flag information
+ * @property {string} flag.key - Flag key
+ * @property {Object} variant - Variant information
+ * @property {string} variant.key - Variant key
+ * @property {Object} subject - Subject (user/entity) information
+ * @property {string} subject.id - Subject identifier
+ * @property {string} [subject.type] - Subject type
+ * @property {Object} [subject.attributes] - Additional subject attributes
+ */
+
+/**
+ * @typedef {Object} ExposureContext
+ * @property {string} service_name - Service name
+ * @property {string} [version] - Service version
+ * @property {string} [env] - Service environment
+ */
+
+/**
+ * @typedef {Object} ExposureEventPayload
+ * @property {ExposureContext} context - Service context metadata
+ * @property {ExposureEvent[]} exposures - Formatted exposure events
+ */
+
+/**
+ * ExposuresWriter is responsible for sending exposure events to the Datadog Agent.
+ */
+class ExposuresWriter extends BaseFFEWriter {
+  /**
+   * @param {import('../../config')} config - Tracer configuration object
+   */
+  constructor (config) {
+    // Build full EVP endpoint path
+    const basePath = EVP_PROXY_AGENT_BASE_PATH.replace(/\/+$/, '')
+    const endpoint = EXPOSURES_ENDPOINT.replace(/^\/+/, '')
+    const fullEndpoint = `${basePath}/${endpoint}`
+
+    super({
+      config,
+      endpoint: fullEndpoint,
+      payloadSizeLimit: EVP_PAYLOAD_SIZE_LIMIT,
+      eventSizeLimit: EVP_EVENT_SIZE_LIMIT,
+      headers: {
+        [EVP_SUBDOMAIN_HEADER_NAME]: EVP_SUBDOMAIN_VALUE
+      }
+    })
+    this._enabled = false // Start disabled until agent strategy is set
+    this._pendingEvents = [] // Buffer events until enabled
+    this._context = this._buildContext()
+  }
+
+  /**
+   * @param {boolean} enabled - Whether to enable the writer
+   */
+  setEnabled (enabled) {
+    this._enabled = enabled
+
+    if (enabled && this._pendingEvents.length > 0) {
+      // Flush all pending events as a batch
+      super.append(this._pendingEvents)
+      this._pendingEvents = []
+    }
+  }
+
+  /**
+   * Appends exposure event(s) to the buffer
+   * @param {ExposureEvent|ExposureEvent[]} events - Exposure event(s) to append
+   */
+  append (events) {
+    if (!this._enabled) {
+      // Buffer events until writer is ready
+      if (Array.isArray(events)) {
+        this._pendingEvents.push(...events)
+      } else {
+        this._pendingEvents.push(events)
+      }
+      return
+    }
+    super.append(events)
+  }
+
+  /**
+   * Flushes buffered exposure events to the agent
+   */
+  flush () {
+    if (!this._enabled) {
+      // Don't flush when disabled
+      return
+    }
+    super.flush()
+  }
+
+  /**
+   * Formats exposure events with service context metadata
+   * @param {Array<ExposureEvent>} events - Array of exposure events
+   * @returns {ExposureEventPayload} Formatted payload with service context
+   */
+  makePayload (events) {
+    const formattedEvents = events.map(event => this._formatExposureEvent(event))
+
+    return {
+      context: this._context,
+      exposures: formattedEvents
+    }
+  }
+
+  /**
+   * Builds service context metadata
+   * @private
+   * @returns {ExposureContext} Service context
+   */
+  _buildContext () {
+    const context = {
+      service_name: this._config.service || 'unknown'
+    }
+
+    // Only include version and env if they are defined
+    if (this._config.version !== undefined) {
+      context.version = this._config.version
+    }
+
+    if (this._config.env !== undefined) {
+      context.env = this._config.env
+    }
+
+    return context
+  }
+
+  /**
+   * @private
+   * @param {ExposureEvent} event - Raw exposure event
+   * @returns {ExposureEvent} Formatted exposure event
+   */
+  _formatExposureEvent (event) {
+    // Ensure the event matches the expected schema
+    const formattedEvent = {
+      timestamp: event.timestamp || Date.now(),
+      allocation: {
+        key: event.allocation?.key || event['allocation.key']
+      },
+      flag: {
+        key: event.flag?.key || event['flag.key']
+      },
+      variant: {
+        key: event.variant?.key || event['variant.key']
+      },
+      subject: {
+        id: event.subject?.id || event['subject.id'],
+        type: event.subject?.type,
+        attributes: event.subject?.attributes
+      }
+    }
+    return formattedEvent
+  }
+}
+
+module.exports = ExposuresWriter

package/packages/dd-trace/src/openfeature/writers/util.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const logger = require('../../log')
+const { EVP_PROXY_AGENT_BASE_PATH } = require('../constants/constants')
+
+const AgentInfoExporter = require('../../exporters/common/agent-info-exporter')
+let agentInfoExporter
+
+/**
+ * Determines if the agent supports EVP proxy and sets the writer enabled state accordingly
+ * @param {import('../../config')} config - Tracer configuration object
+ * @param {Function} setWriterEnabledValue - Callback to set the writer enabled state
+ */
+function setAgentStrategy (config, setWriterEnabledValue) {
+  if (!agentInfoExporter) {
+    agentInfoExporter = new AgentInfoExporter(config)
+  }
+
+  agentInfoExporter.getAgentInfo((err, agentInfo) => {
+    if (err) {
+      logger.debug('FFE Writer disabled - error getting agent info:', err.message)
+      setWriterEnabledValue(false)
+      return
+    }
+
+    const endpoints = agentInfo.endpoints
+    const normalizedPath = EVP_PROXY_AGENT_BASE_PATH.replace(/\/+$/, '')
+    const hasEndpoint = Array.isArray(endpoints) &&
+      endpoints.includes(normalizedPath) || endpoints.includes(normalizedPath + '/')
+
+    if (hasEndpoint) {
+      logger.debug('FFE Writer enabled - agent has EVP proxy support')
+      setWriterEnabledValue(true)
+    } else {
+      logger.debug('FFE Writer disabled - agent does not have EVP proxy support')
+      setWriterEnabledValue(false)
+    }
+  })
+}
+
+module.exports = {
+  setAgentStrategy
+}

package/packages/dd-trace/src/opentelemetry/logs/batch_log_processor.js

@@ -0,0 +1,100 @@
+'use strict'
+
+/**
+ * @typedef {import('@opentelemetry/api-logs').LogRecord} LogRecord
+ * @typedef {import('@opentelemetry/core').InstrumentationScope} InstrumentationScope
+ */
+
+/**
+ * BatchLogRecordProcessor processes log records in batches for efficient export to Datadog Agent.
+ *
+ * This implementation follows the OpenTelemetry JavaScript SDK BatchLogRecordProcessor:
+ * https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_sdk-logs.BatchLogRecordProcessor.html
+ *
+ * @class BatchLogRecordProcessor
+ */
+class BatchLogRecordProcessor {
+  #logRecords
+  #timer
+  #batchTimeout
+  #maxExportBatchSize
+
+  /**
+   * Creates a new BatchLogRecordProcessor instance.
+   *
+   * @param {OtlpHttpLogExporter} exporter - Log processor for exporting batches to Datadog Agent
+   * @param {number} batchTimeout - Timeout in milliseconds for batch processing
+   * @param {number} maxExportBatchSize - Maximum number of log records per batch
+   */
+  constructor (exporter, batchTimeout, maxExportBatchSize) {
+    this.exporter = exporter
+    this.#batchTimeout = batchTimeout
+    this.#maxExportBatchSize = maxExportBatchSize
+    this.#logRecords = []
+    this.#timer = null
+  }
+
+  /**
+   * Processes a single log record.
+   *
+   * @param {LogRecord} logRecord - The enriched log record with trace correlation and metadata
+   * @param {InstrumentationScope} instrumentationScope - The instrumentation library
+   */
+  onEmit (logRecord, instrumentationScope) {
+    // Store the log record (already enriched by Logger.emit)
+    this.#logRecords.push({ ...logRecord, instrumentationScope })
+
+    if (this.#logRecords.length >= this.#maxExportBatchSize) {
+      this.#export()
+    } else if (this.#logRecords.length === 1) {
+      this.#startTimer()
+    }
+  }
+
+  /**
+   * Forces an immediate flush of all pending log records.
+   * @returns {undefined} Promise that resolves when flush is complete
+   */
+  forceFlush () {
+    this.#export()
+  }
+
+  /**
+   * Starts the batch timeout timer.
+   * @private
+   */
+  #startTimer () {
+    if (this.#timer) {
+      return
+    }
+
+    this.#timer = setTimeout(() => {
+      this.#export()
+    }, this.#batchTimeout)
+  }
+
+  /**
+   * Exports the current batch of log records.
+   * @private
+   */
+  #export () {
+    const logRecords = this.#logRecords.slice(0, this.#maxExportBatchSize)
+    this.#logRecords = this.#logRecords.slice(this.#maxExportBatchSize)
+
+    this.#clearTimer()
+    this.exporter.export(logRecords, () => {})
+  }
+
+  /**
+   * Clears the batch timeout timer.
+   * @private
+   */
+  #clearTimer () {
+    if (this.#timer) {
+      clearTimeout(this.#timer)
+      this.#timer = null
+    }
+  }
+}
+
+module.exports = BatchLogRecordProcessor

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

@@ -0,0 +1,87 @@
+'use strict'
+
+const os = require('os')
+
+/**
+ * @typedef {import('../../config')} Config
+ */
+
+/**
+ * @fileoverview OpenTelemetry Logs Implementation for dd-trace-js
+ *
+ * This package provides a custom OpenTelemetry Logs implementation that integrates
+ * with the Datadog tracing library. It includes all necessary components for
+ * emitting, processing, and exporting log records via OTLP (OpenTelemetry Protocol).
+ *
+ * Key Components:
+ * - LoggerProvider: Main entry point for creating loggers
+ * - Logger: Provides methods to emit log records
+ * - BatchLogRecordProcessor: Processes log records in batches for efficient export
+ * - OtlpHttpLogExporter: Exports log records via OTLP over HTTP
+ * - OtlpTransformer: Transforms log records 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 LoggerProvider = require('./logger_provider')
+const BatchLogRecordProcessor = require('./batch_log_processor')
+const OtlpHttpLogExporter = require('./otlp_http_log_exporter')
+
+/**
+ * Initializes OpenTelemetry Logs support
+ * @param {Config} config - Tracer configuration instance
+ */
+function initializeOpenTelemetryLogs (config) {
+  // Build resource attributes
+  const resourceAttributes = {
+    'service.name': config.service,
+    'service.version': config.version,
+    'deployment.environment': config.env
+  }
+
+  // Add all tracer tags (includes DD_TAGS, OTEL_RESOURCE_ATTRIBUTES, DD_TRACE_TAGS, etc.)
+  // Exclude Datadog-style keys that duplicate OpenTelemetry standard keys
+  if (config.tags) {
+    const filteredTags = { ...config.tags }
+    delete filteredTags.service
+    delete filteredTags.version
+    delete filteredTags.env
+    Object.assign(resourceAttributes, filteredTags)
+  }
+
+  // Add host.name if reportHostname is enabled
+  if (config.reportHostname) {
+    resourceAttributes['host.name'] = os.hostname()
+  }
+
+  // Create OTLP exporter using resolved config values
+  const exporter = new OtlpHttpLogExporter(
+    config.otelLogsUrl,
+    config.otelLogsHeaders,
+    config.otelLogsTimeout,
+    config.otelLogsProtocol,
+    resourceAttributes
+  )
+
+  // Create batch processor for exporting logs to Datadog Agent
+  const processor = new BatchLogRecordProcessor(
+    exporter,
+    config.otelLogsBatchTimeout,
+    config.otelLogsMaxExportBatchSize
+  )
+
+  // Create logger provider with processor for Datadog Agent export
+  const loggerProvider = new LoggerProvider({ processor })
+
+  // Register the logger provider globally with OpenTelemetry API
+  loggerProvider.register()
+}
+
+module.exports = {
+  LoggerProvider,
+  initializeOpenTelemetryLogs
+}

package/packages/dd-trace/src/opentelemetry/logs/logger.js

@@ -0,0 +1,77 @@
+'use strict'
+
+const { sanitizeAttributes } = require('@opentelemetry/core')
+const { context } = require('@opentelemetry/api')
+const packageVersion = require('../../../../../package.json').version
+/**
+ * @typedef {import('@opentelemetry/api-logs').LogRecord} LogRecord
+ * @typedef {import('@opentelemetry/api').SpanContext} SpanContext
+ * @typedef {import('@opentelemetry/api').Attributes} Attributes
+ * @typedef {import('@opentelemetry/resources').Resource} Resource
+ * @typedef {import('@opentelemetry/core').InstrumentationScope} InstrumentationScope
+ */
+
+/**
+ * Logger provides methods to emit log records.
+ *
+ * This implementation follows the OpenTelemetry JavaScript API Logger:
+ * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api-logs.Logger.html
+ *
+ * @class Logger
+ */
+class Logger {
+  #instrumentationScope
+
+  /**
+   * Creates a new Logger instance.
+   *
+   * @param {LoggerProvider} loggerProvider - Parent logger provider
+   * @param {InstrumentationScope} [instrumentationScope] - Instrumentation scope information (newer API)
+   * @param {Object} [instrumentationLibrary] - Instrumentation library information (legacy API) [DEPRECATED in v1.3.0]
+   * @param {InstrumentationScope} [instrumentationScope.name] - Library name (defaults to 'dd-trace-js')
+   * @param {InstrumentationScope} [instrumentationScope.version] - Library version (defaults to tracer version)
+   * @param {string} [instrumentationLibrary.name] - Library name (legacy, defaults to 'dd-trace-js')
+   * @param {string} [instrumentationLibrary.version] - Library version (legacy, defaults to tracer version)
+   */
+  constructor (loggerProvider, instrumentationScope, instrumentationLibrary) {
+    this.loggerProvider = loggerProvider
+
+    // Support both newer instrumentationScope and legacy instrumentationLibrary
+    const scope = instrumentationScope || instrumentationLibrary
+    this.#instrumentationScope = {
+      name: scope?.name || 'dd-trace-js',
+      version: scope?.version || packageVersion,
+      schemaUrl: scope?.schemaUrl || '',
+    }
+  }
+
+  /**
+   * Emits a log record.
+   *
+   * @param {LogRecord} logRecord - The log record to emit
+   * @returns {void}
+   */
+  emit (logRecord) {
+    if (this.loggerProvider.isShutdown || !this.loggerProvider.processor) {
+      return
+    }
+
+    if (logRecord.attributes) {
+      logRecord.attributes = sanitizeAttributes(logRecord.attributes)
+    }
+
+    // Note: timestamp is in nanoseconds (as defined by OpenTelemetry LogRecord API)
+    if (!logRecord.timestamp) {
+      logRecord.timestamp = Number(process.hrtime.bigint())
+    }
+
+    if (!logRecord.context) {
+      // Store span context in the log record context for trace correlation
+      logRecord.context = context.active()
+    }
+
+    this.loggerProvider.processor.onEmit(logRecord, this.#instrumentationScope)
+  }
+}
+
+module.exports = Logger