dd-trace 5.70.0 → 5.72.0

package/packages/dd-trace/src/llmobs/tagger.js

@@ -268,6 +268,32 @@ class LLMObsTagger {
     return filteredToolCalls
   }
 
+  #filterToolResults (toolResults) {
+    if (!Array.isArray(toolResults)) {
+      toolResults = [toolResults]
+    }
+
+    const filteredToolResults = []
+    for (const toolResult of toolResults) {
+      if (typeof toolResult !== 'object') {
+        this.#handleFailure('Tool result must be an object.', 'invalid_io_messages')
+        continue
+      }
+
+      const { result, toolId, type } = toolResult
+      const toolResultObj = {}
+
+      const condition1 = this.#tagConditionalString(result, 'Tool result', toolResultObj, 'result')
+      const condition2 = this.#tagConditionalString(toolId, 'Tool ID', toolResultObj, 'tool_id')
+      const condition3 = this.#tagConditionalString(type, 'Tool type', toolResultObj, 'type')
+
+      if (condition1 && condition2 && condition3) {
+        filteredToolResults.push(toolResultObj)
+      }
+    }
+    return filteredToolResults
+  }
+
   #tagMessages (span, data, key) {
     if (!data) {
       return
@@ -290,6 +316,7 @@ class LLMObsTagger {
 
       const { content = '', role } = message
       const toolCalls = message.toolCalls
+      const toolResults = message.toolResults
       const toolId = message.toolId
       const messageObj = { content }
 
@@ -308,6 +335,14 @@ class LLMObsTagger {
         }
       }
 
+      if (toolResults) {
+        const filteredToolResults = this.#filterToolResults(toolResults)
+
+        if (filteredToolResults.length) {
+          messageObj.tool_results = filteredToolResults
+        }
+      }
+
       if (toolId) {
         if (role === 'tool') {
           condition = this.#tagConditionalString(toolId, 'Tool ID', messageObj, 'tool_id')

package/packages/dd-trace/src/noop/proxy.js

@@ -4,12 +4,14 @@ const NoopTracer = require('./tracer')
 const NoopAppsecSdk = require('../appsec/sdk/noop')
 const NoopDogStatsDClient = require('./dogstatsd')
 const NoopLLMObsSDK = require('../llmobs/noop')
+const NoopFlaggingProvider = require('../openfeature/noop')
 const NoopAIGuardSDK = require('../aiguard/noop')
 
 const noop = new NoopTracer()
 const noopAppsec = new NoopAppsecSdk()
 const noopDogStatsDClient = new NoopDogStatsDClient()
 const noopLLMObs = new NoopLLMObsSDK(noop)
+const noopOpenFeatureProvider = new NoopFlaggingProvider()
 const noopAIGuard = new NoopAIGuardSDK()
 
 /** @type {import('../../src/index')} Proxy */
@@ -19,6 +21,7 @@ class NoopProxy {
     this.appsec = noopAppsec
     this.dogstatsd = noopDogStatsDClient
     this.llmobs = noopLLMObs
+    this.openfeature = noopOpenFeatureProvider
     this.aiguard = noopAIGuard
     this.setBaggageItem = () => {}
     this.getBaggageItem = () => {}

package/packages/dd-trace/src/openfeature/constants/constants.js

@@ -0,0 +1,51 @@
+'use strict'
+
+module.exports = {
+  /**
+   * @constant
+   * @type {string} Base path for EVP proxy agent endpoint
+   */
+  EVP_PROXY_AGENT_BASE_PATH: '/evp_proxy/v2/',
+
+  /**
+   * @constant
+   * @type {string} HTTP header name for EVP subdomain routing
+   */
+  EVP_SUBDOMAIN_HEADER_NAME: 'X-Datadog-EVP-Subdomain',
+
+  /**
+   * @constant
+   * @type {string} EVP subdomain value for event platform intake
+   */
+  EVP_SUBDOMAIN_VALUE: 'event-platform-intake',
+
+  /**
+   * @constant
+   * @type {string} API endpoint for exposure events EVP track
+   */
+  EXPOSURES_ENDPOINT: '/api/v2/exposures',
+
+  /**
+   * @constant
+   * @type {number} Maximum payload size for EVP intake (5MB, actual limit is 5.1MB)
+   */
+  EVP_PAYLOAD_SIZE_LIMIT: 5 << 20,
+
+  /**
+   * @constant
+   * @type {number} Maximum individual event size (999KB, actual limit is 1MB)
+   */
+  EVP_EVENT_SIZE_LIMIT: (1 << 20) - 1024,
+
+  /**
+   * @constant
+   * @type {string} Channel name for exposure event submission
+   */
+  EXPOSURE_CHANNEL: 'ffe:exposure:submit',
+
+  /**
+   * @constant
+   * @type {string} Reason code for noop provider evaluations
+   */
+  NOOP_REASON: 'STATIC'
+}

package/packages/dd-trace/src/openfeature/flagging_provider.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const { DatadogNodeServerProvider } = require('@datadog/openfeature-node-server')
+const { channel } = require('dc-polyfill')
+const log = require('../log')
+const { EXPOSURE_CHANNEL } = require('./constants/constants')
+
+/**
+ * OpenFeature provider that integrates with Datadog's feature flagging system.
+ * Extends DatadogNodeServerProvider to add tracer integration and configuration management.
+ */
+class FlaggingProvider extends DatadogNodeServerProvider {
+  /**
+   * @param {import('../tracer')} tracer - Datadog tracer instance
+   * @param {import('../config')} config - Tracer configuration object
+   */
+  constructor (tracer, config) {
+    // Call parent constructor with required options
+    super({
+      exposureChannel: channel(EXPOSURE_CHANNEL)
+    })
+
+    this._tracer = tracer
+    this._config = config
+
+    log.debug(this.constructor.name + ' created')
+  }
+
+  /**
+   * Internal method to update flag configuration from Remote Config.
+   * This method is called automatically when Remote Config delivers UFC updates.
+   *
+   * @internal
+   * @param {import('@datadog/openfeature-node-server').UniversalFlagConfigurationV1} ufc
+   * - Universal Flag Configuration object
+   */
+  _setConfiguration (ufc) {
+    if (typeof this.setConfiguration === 'function') {
+      this.setConfiguration(ufc)
+    }
+    log.debug(this.constructor.name + ' provider configuration updated')
+  }
+}
+
+module.exports = FlaggingProvider

package/packages/dd-trace/src/openfeature/index.js

@@ -0,0 +1,77 @@
+'use strict'
+
+const log = require('../log')
+const ExposuresWriter = require('./writers/exposures')
+const { setAgentStrategy } = require('./writers/util')
+const { channel } = require('dc-polyfill')
+
+const exposureSubmitCh = channel('ffe:exposure:submit')
+const flushCh = channel('ffe:writers:flush')
+
+let exposuresWriter = null
+
+/**
+ * @private
+ * @param {Object|Array<Object>} exposureEvents - Exposure events channel subscriber
+ * @returns {void}
+ */
+function _handleExposureSubmit (exposureEvents) {
+  if (!exposuresWriter) return
+  exposuresWriter.append(exposureEvents)
+}
+
+/**
+ * Channel subscriber for manually flushing the exposures writer
+ * @private
+ * @returns {void}
+ */
+function _handleFlush () {
+  exposuresWriter?.flush()
+}
+
+/**
+ * Enables the OpenFeature module and sets up FF&E writer and channel subscribers
+ * @param {import('../config')} config - Tracer configuration object
+ * @returns {void}
+ */
+function enable (config) {
+  if (exposuresWriter) {
+    log.warn(exposuresWriter.constructor.name + ' already enabled')
+    return
+  }
+
+  exposuresWriter = new ExposuresWriter(config)
+  exposureSubmitCh.subscribe(_handleExposureSubmit)
+  flushCh.subscribe(_handleFlush)
+
+  setAgentStrategy(config, hasAgent => {
+    exposuresWriter?.setEnabled(hasAgent)
+  })
+
+  log.debug('OpenFeature module enabled')
+}
+
+/**
+ * Disables the OpenFeature module and cleans up resources
+ * @returns {void}
+ */
+function disable () {
+  if (!exposuresWriter) return
+
+  if (exposureSubmitCh.hasSubscribers) {
+    exposureSubmitCh.unsubscribe(_handleExposureSubmit)
+  }
+  if (flushCh.hasSubscribers) {
+    flushCh.unsubscribe(_handleFlush)
+  }
+
+  exposuresWriter.destroy?.()
+  exposuresWriter = null
+
+  log.debug('OpenFeature module disabled')
+}
+
+module.exports = {
+  enable,
+  disable
+}

package/packages/dd-trace/src/openfeature/noop.js

@@ -0,0 +1,101 @@
+'use strict'
+
+const { NOOP_REASON } = require('./constants/constants')
+
+/**
+ * No-op implementation of OpenFeature provider that always returns default values.
+ * Used when the OpenFeature provider is not initialized or disabled.
+ * https://openfeature.dev/docs/reference/concepts/provider/
+ */
+class NoopFlaggingProvider {
+  /**
+   * @param {Object} [noopTracer] - Optional noop tracer instance
+   */
+  constructor (noopTracer) {
+    this._tracer = noopTracer
+    this._config = {}
+    this.metadata = { name: 'NoopFlaggingProvider' }
+    this.status = 'NOT_READY'
+    this.runsOn = 'server'
+  }
+
+  /**
+   * @param {string} flagKey - Flag key
+   * @param {boolean} defaultValue - Default value to return
+   * @param {Object} context - Evaluation context
+   * @param {Object} logger - Logger instance
+   * @returns {Promise<{value: boolean, reason: string}>} Resolution details
+   */
+  resolveBooleanEvaluation (flagKey, defaultValue, context, logger) {
+    return Promise.resolve({
+      value: defaultValue,
+      reason: NOOP_REASON
+    })
+  }
+
+  /**
+   * @param {string} flagKey - Flag key
+   * @param {string} defaultValue - Default value to return
+   * @param {Object} context - Evaluation context
+   * @param {Object} logger - Logger instance
+   * @returns {Promise<{value: string, reason: string}>} Resolution details
+   */
+  resolveStringEvaluation (flagKey, defaultValue, context, logger) {
+    return Promise.resolve({
+      value: defaultValue,
+      reason: NOOP_REASON
+    })
+  }
+
+  /**
+   * @param {string} flagKey - Flag key
+   * @param {number} defaultValue - Default value to return
+   * @param {Object} context - Evaluation context
+   * @param {Object} logger - Logger instance
+   * @returns {Promise<{value: number, reason: string}>} Resolution details
+   */
+  resolveNumberEvaluation (flagKey, defaultValue, context, logger) {
+    return Promise.resolve({
+      value: defaultValue,
+      reason: NOOP_REASON,
+    })
+  }
+
+  /**
+   * @param {string} flagKey - Flag key
+   * @param {Object} defaultValue - Default value to return
+   * @param {Object} context - Evaluation context
+   * @param {Object} logger - Logger instance
+   * @returns {Promise<{value: Object, reason: string}>} Resolution details
+   */
+  resolveObjectEvaluation (flagKey, defaultValue, context, logger) {
+    return Promise.resolve({
+      value: defaultValue,
+      reason: NOOP_REASON
+    })
+  }
+
+  /**
+   * @returns {Object} Current configuration
+   */
+  getConfiguration () {
+    return this._config
+  }
+
+  /**
+   * @param {Object} config - Configuration to set
+   */
+  setConfiguration (config) {
+    this._config = config
+  }
+
+  /**
+   * @internal
+   * @param {Object} ufc - Universal Flag Configuration object
+   */
+  _setConfiguration (ufc) {
+    this.setConfiguration(ufc)
+  }
+}
+
+module.exports = NoopFlaggingProvider

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