dd-trace 5.115.0 → 5.117.0

package/packages/dd-trace/src/llmobs/plugins/openai/index.js

@@ -7,11 +7,13 @@ const {
   INSTRUMENTATION_METHOD_AUTO,
   UNKNOWN_MODEL_PROVIDER,
 } = require('../../constants/tags')
-const { safeJsonParse } = require('../../util')
+const { audioMimeTypeFromFormat, formatAudioPart, safeJsonParse } = require('../../util')
+const { AUDIO_MIME_TYPES } = require('./constants')
 const {
   extractChatTemplateFromInstructions,
   normalizePromptVariables,
   extractTextFromContentItem,
+  extractContentParts,
   hasMultimodalInputs,
 } = require('./utils')
 
@@ -29,6 +31,22 @@ function isIterable (obj) {
   return typeof obj[Symbol.iterator] === 'function'
 }
 
+// Flattens multimodal chat input messages (array `content`) into readable text plus structured
+// `audioParts`, leaving plain-string messages untouched. Model-agnostic: keys off message
+// structure, so it works for any audio-capable chat model (gpt-audio*, gpt-4o-audio-preview, ...).
+function flattenChatInputMessages (messages) {
+  if (!Array.isArray(messages)) return messages
+
+  return messages.map(message => {
+    if (!Array.isArray(message?.content)) return message
+
+    const { content, audioParts } = extractContentParts(message.content)
+    const flattenedMessage = { ...message, content }
+    if (audioParts.length) flattenedMessage.audioParts = audioParts
+    return flattenedMessage
+  })
+}
+
 class OpenAiLLMObsPlugin extends LLMObsPlugin {
   static id = 'openai'
   static integration = 'openai'
@@ -193,47 +211,63 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
 
     this._tagger.tagMetadata(span, metadata)
 
+    const inputMessages = flattenChatInputMessages(messages)
+
     if (error) {
-      this._tagger.tagLLMIO(span, messages, [{ content: '' }])
+      this._tagger.tagLLMIO(span, inputMessages, [{ content: '' }])
       return
     }
 
     const outputMessages = []
     const { choices } = response
     if (!isIterable(choices)) {
-      this._tagger.tagLLMIO(span, messages, [{ content: '' }])
+      this._tagger.tagLLMIO(span, inputMessages, [{ content: '' }])
       return
     }
 
+    // Output audio (non-streamed) is returned in the requested format; chat-completions
+    const outputAudioFormat = inputs.audio?.format
+
     for (const choice of choices) {
       const message = choice.message || choice.delta
-      const content = message.content || ''
+      let content = message.content || ''
       const role = message.role
 
+      const audio = message.audio
+      let audioParts
+      if (audio) {
+        if (audio.data) {
+          audioParts = [formatAudioPart(audio.data, audioMimeTypeFromFormat(outputAudioFormat, AUDIO_MIME_TYPES))]
+        }
+        // gpt-audio* / gpt-4o-audio-preview return null content; surface the transcript as text.
+        if (!content) content = audio.transcript || ''
+      }
+
+      const outputMessage = { content, role }
+      if (audioParts) outputMessage.audioParts = audioParts
+
       if (message.function_call) {
-        const functionCallInfo = {
+        outputMessage.toolCalls = [{
           name: message.function_call.name,
           arguments: safeJsonParse(message.function_call.arguments),
-        }
-        outputMessages.push({ content, role, toolCalls: [functionCallInfo] })
+        }]
       } else if (message.tool_calls) {
         const toolCallsInfo = []
         for (const toolCall of message.tool_calls) {
-          const toolCallInfo = {
+          toolCallsInfo.push({
             arguments: safeJsonParse(toolCall.function.arguments),
             name: toolCall.function.name,
             toolId: toolCall.id,
             type: toolCall.type,
-          }
-          toolCallsInfo.push(toolCallInfo)
+          })
         }
-        outputMessages.push({ content, role, toolCalls: toolCallsInfo })
-      } else {
-        outputMessages.push({ content, role })
+        outputMessage.toolCalls = toolCallsInfo
       }
+
+      outputMessages.push(outputMessage)
     }
 
-    this._tagger.tagLLMIO(span, messages, outputMessages)
+    this._tagger.tagLLMIO(span, inputMessages, outputMessages)
   }
 
   #tagResponse (span, inputs, response, error) {

package/packages/dd-trace/src/llmobs/plugins/openai/utils.js

@@ -1,10 +1,13 @@
 'use strict'
 
+const { audioMimeTypeFromFormat, formatAudioPart } = require('../../util')
 const {
   INPUT_TYPE_IMAGE,
   INPUT_TYPE_FILE,
   IMAGE_FALLBACK,
   FILE_FALLBACK,
+  AUDIO_FALLBACK,
+  AUDIO_MIME_TYPES,
 } = require('./constants')
 
 const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g
@@ -118,9 +121,49 @@ function hasMultimodalInputs (variables) {
   )
 }
 
+/**
+ * Flattens an array of OpenAI chat message content parts into readable text plus structured audio.
+ *
+ * Text parts are concatenated (newline-joined),
+ * images collapse to an `[image]` marker, and `input_audio` parts with data are captured as audio
+ * parts (rendered as a player). The `[audio]` marker is only emitted as a fallback when an audio
+ * part carries no data.
+ *
+ * @param {Array<object>} parts - Array of content parts from a chat message `content`
+ * @returns {{ content: string, audioParts: Array<{ mimeType: string, content: string }> }}
+ */
+function extractContentParts (parts) {
+  const extracted = []
+  const audioParts = []
+
+  for (const part of parts) {
+    const partType = part?.type ?? ''
+    if (partType === 'text') {
+      extracted.push(part.text ?? '')
+    } else if (partType === 'image_url') {
+      extracted.push(IMAGE_FALLBACK)
+    } else if (partType === 'input_audio') {
+      const inputAudio = part.input_audio ?? {}
+      const data = inputAudio.data
+      if (data) {
+        // Audio is captured as a structured audio part (rendered as a player), so no text marker
+        // is needed. Only fall back to "[audio]" when there's no audio to capture.
+        audioParts.push(formatAudioPart(data, audioMimeTypeFromFormat(inputAudio.format, AUDIO_MIME_TYPES)))
+      } else {
+        extracted.push(AUDIO_FALLBACK)
+      }
+    } else {
+      extracted.push(`[${partType}]`)
+    }
+  }
+
+  return { content: extracted.join('\n'), audioParts }
+}
+
 module.exports = {
   extractChatTemplateFromInstructions,
   normalizePromptVariables,
   extractTextFromContentItem,
+  extractContentParts,
   hasMultimodalInputs,
 }

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

@@ -19,6 +19,7 @@ const {
 const { storage } = require('./storage')
 const telemetry = require('./telemetry')
 const LLMObsTagger = require('./tagger')
+const { createExperiments } = require('./experiments')
 
 // communicating with writer
 const evalMetricAppendCh = channel('llmobs:eval-metric:append')
@@ -33,6 +34,12 @@ class LLMObs extends NoopLLMObs {
    */
   #hasUserSpanProcessor = false
 
+  /**
+   * Lazily-created experiments facade (see ./experiments).
+   * @type {import('./experiments').Experiments | undefined}
+   */
+  #experiments
+
   /**
    * @param {import('../tracer')} tracer - Tracer instance
    * @param {import('./index')} llmobsModule - LLMObs module instance
@@ -52,6 +59,16 @@ class LLMObs extends NoopLLMObs {
     return this._config.llmobs.DD_LLMOBS_ENABLED ?? false
   }
 
+  /**
+   * Datasets & Experiments API. Requires LLM Observability to be enabled and
+   * DD_API_KEY / DD_APP_KEY to be set; otherwise the returned facade throws with
+   * a clear message on use.
+   */
+  get experiments () {
+    this.#experiments ??= createExperiments(this._config)
+    return this.#experiments
+  }
+
   enable (options = {}) {
     logger.warn(
       'Enabling LLM Observability via `llmobs.enable()` is deprecated and will be removed in dd-trace@7.0.0. ' +

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

@@ -618,6 +618,65 @@ class LLMObsTagger {
     return filteredToolResults
   }
 
+  // Validates audio segments on a message and emits the snake_case wire shape
+  // `{ mime_type, content | attachment_key }`. Mirrors dd-trace-py's
+  // `_extract_audio_part`: a part requires `mimeType` and exactly one of
+  // `content` (inline base64) or `attachmentKey` (backend-offloaded).
+  #filterAudioParts (audioParts) {
+    if (!Array.isArray(audioParts)) {
+      audioParts = [audioParts]
+    }
+
+    const filteredAudioParts = []
+    for (const audioPart of audioParts) {
+      if (audioPart == null || typeof audioPart !== 'object') {
+        this.#handleFailure('Audio part must be an object.', 'invalid_io_messages')
+        continue
+      }
+
+      const { mimeType, content, attachmentKey } = audioPart
+
+      if (typeof mimeType !== 'string' || !mimeType) {
+        this.#handleFailure('Audio part mimeType must be a non-empty string.', 'invalid_io_messages')
+        continue
+      }
+
+      if (content == null && attachmentKey == null) {
+        this.#handleFailure("Audio part must have either 'content' or 'attachmentKey'.", 'invalid_io_messages')
+        continue
+      }
+
+      if (content != null && attachmentKey != null) {
+        this.#handleFailure(
+          "Audio part must have only one of 'content' or 'attachmentKey', not both.", 'invalid_io_messages'
+        )
+        continue
+      }
+
+      const audioPartObj = { mime_type: mimeType }
+
+      // Exactly one of content / attachmentKey is set here (guarded above). Validate its type
+      // explicitly so the failure carries the `invalid_io_messages` tag for telemetry, instead
+      // of routing through `#tagConditionalString` which omits it.
+      if (content == null) {
+        if (typeof attachmentKey !== 'string') {
+          this.#handleFailure('Audio part attachmentKey must be a string.', 'invalid_io_messages')
+          continue
+        }
+        audioPartObj.attachment_key = attachmentKey
+      } else {
+        if (typeof content !== 'string') {
+          this.#handleFailure('Audio part content must be a base64-encoded string.', 'invalid_io_messages')
+          continue
+        }
+        audioPartObj.content = content
+      }
+
+      filteredAudioParts.push(audioPartObj)
+    }
+    return filteredAudioParts
+  }
+
   #tagMessages (span, data, key) {
     if (!data) {
       return
@@ -644,6 +703,7 @@ class LLMObsTagger {
         toolCalls,
         toolResults,
         toolId,
+        audioParts,
       } = message
       const messageObj = {}
 
@@ -677,6 +737,14 @@ class LLMObsTagger {
         }
       }
 
+      if (audioParts != null) {
+        const filteredAudioParts = this.#filterAudioParts(audioParts)
+
+        if (filteredAudioParts.length) {
+          messageObj.audio_parts = filteredAudioParts
+        }
+      }
+
       if (toolId) {
         if (role === 'tool') {
           condition = this.#tagConditionalString(toolId, 'Tool ID', messageObj, 'tool_id') && condition

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

@@ -3,6 +3,7 @@
 const ERROR_TYPE = require('../constants')
 
 const telemetryMetrics = require('../telemetry/metrics')
+const { getSegment } = require('../util')
 const {
   SPAN_KIND,
   MODEL_PROVIDER,
@@ -22,7 +23,7 @@ function extractIntegrationFromTags (tags) {
   if (!Array.isArray(tags)) return null
   const integrationTag = tags.find(tag => tag.startsWith('integration:'))
   if (!integrationTag) return null
-  return integrationTag.split(':')[1] || null
+  return getSegment(integrationTag, ':', 1) || null
 }
 
 function extractTagsFromSpanEvent (event) {

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

@@ -362,9 +362,41 @@ function findGenAIAncestorSpanId (span) {
   return null
 }
 
+// Maps an audio `format` (e.g. "wav", "mp3") to a MIME type. Defaults to `audio/wav` when the
+// format is missing. Provider-specific overrides (e.g. OpenAI's mp3 -> audio/mpeg) are passed in
+// via `mimeTypeLookup` so this stays provider-agnostic. A non-string `format` is treated as missing
+// so a malformed auto-instrumented payload can't throw and disable the plugin.
+/**
+ * @param {string} fmt
+ * @param {Record<string, string>} [mimeTypeLookup]
+ * @returns {string}
+ */
+function audioMimeTypeFromFormat (fmt, mimeTypeLookup = {}) {
+  fmt = typeof fmt === 'string' ? fmt.trim().toLowerCase() : ''
+  if (!fmt) return 'audio/wav'
+  return mimeTypeLookup[fmt] ?? `audio/${fmt}`
+}
+
+// Builds an audio part from raw audio bytes (base64-encoded) or an existing base64 string. Only
+// Buffer/Uint8Array inputs are base64-encoded; any other shape is passed through so a malformed
+// auto-instrumented payload can't throw (the tagger soft-skips a non-string `content`).
+/**
+ * @param {Buffer | Uint8Array | string} data
+ * @param {string} mimeType
+ * @returns {{ mimeType: string, content: string }}
+ */
+function formatAudioPart (data, mimeType) {
+  const content = Buffer.isBuffer(data) || ArrayBuffer.isView(data)
+    ? Buffer.from(data).toString('base64')
+    : data
+  return { mimeType, content }
+}
+
 module.exports = {
+  audioMimeTypeFromFormat,
   encodeUnicode,
   findGenAIAncestorSpanId,
+  formatAudioPart,
   validateCostTags,
   validateKind,
   getFunctionArguments,

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

@@ -0,0 +1,322 @@
+'use strict'
+
+/* eslint-disable no-await-in-loop -- Polls and retries must remain sequential. */
+
+const { setTimeout: sleep } = require('node:timers/promises')
+
+const request = require('../exporters/common/request')
+const { getClientLibraryHeaders } = require('../exporters/common/client-library-headers')
+const log = require('../log')
+
+const MAX_ATTEMPTS = 3
+const FIRST_RETRY_MIN_MS = 2000
+const FIRST_RETRY_MAX_MS = 10_000
+const SECOND_RETRY_MIN_MS = 5000
+const SECOND_RETRY_MAX_MS = 30_000
+const RETRY_JITTER = 0.2
+
+/**
+ * @typedef {object} AgentlessSourceConfig
+ * @property {URL} endpoint
+ * @property {number} pollIntervalMs
+ * @property {number} requestTimeoutMs
+ * @property {string} apiKey
+ */
+
+/**
+ * @typedef {import('@datadog/openfeature-node-server').UniversalFlagConfigurationV1} UniversalFlagConfiguration
+ */
+
+/**
+ * @typedef {object} PollResponse
+ * @property {Error | null | undefined} error
+ * @property {string | undefined} body
+ * @property {number | undefined} statusCode
+ * @property {import('node:http').IncomingHttpHeaders | undefined} headers
+ */
+
+class AgentlessConfigurationSource {
+  /** @type {AbortController | undefined} */
+  #abortController
+
+  /** @type {(configuration: UniversalFlagConfiguration) => void} */
+  #applyConfiguration
+
+  #applicationFailureLogged = false
+
+  /** @type {AgentlessSourceConfig} */
+  #config
+
+  /** @type {string | undefined} */
+  #etag
+
+  /** @type {Set<string>} */
+  #failureWarnings = new Set()
+
+  #malformedPayloadLogged = false
+
+  /**
+   * @param {AgentlessSourceConfig} config
+   * @param {(configuration: UniversalFlagConfiguration) => void} applyConfiguration
+   */
+  constructor (config, applyConfiguration) {
+    this.#config = config
+    this.#applyConfiguration = applyConfiguration
+  }
+
+  /**
+   * @returns {void}
+   */
+  start () {
+    if (this.#abortController) return
+
+    const abortController = new AbortController()
+    this.#abortController = abortController
+    this.#poll(abortController)
+  }
+
+  /**
+   * @returns {void}
+   */
+  stop () {
+    this.#abortController?.abort()
+    this.#abortController = undefined
+  }
+
+  /**
+   * @param {AbortController} abortController
+   * @returns {Promise<void>}
+   */
+  async #poll (abortController) {
+    try {
+      do {
+        await this.#pollOnce(abortController)
+      } while (
+        this.#abortController === abortController &&
+        await wait(this.#config.pollIntervalMs, abortController.signal)
+      )
+    } catch (error) {
+      if (this.#abortController === abortController) {
+        this.#warnFailure(undefined, error, 1)
+      }
+    } finally {
+      if (this.#abortController === abortController) {
+        this.#abortController = undefined
+      }
+    }
+  }
+
+  /**
+   * @param {AbortController} abortController
+   * @returns {Promise<void>}
+   */
+  async #pollOnce (abortController) {
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      const response = await this.#request(abortController.signal)
+      if (this.#abortController !== abortController) return
+
+      const retryable = response.statusCode === undefined || isRetryableStatus(response.statusCode)
+      if (!retryable) {
+        this.#apply(response)
+        return
+      }
+
+      if (attempt === MAX_ATTEMPTS) {
+        this.#warnFailure(response.statusCode, response.error, attempt)
+        return
+      }
+
+      const delay = retryDelay(this.#config.pollIntervalMs, attempt, Math.random())
+      if (!await wait(delay, abortController.signal)) return
+    }
+  }
+
+  /**
+   * @param {AbortSignal} signal
+   * @returns {Promise<PollResponse>}
+   */
+  #request (signal) {
+    const headers = getClientLibraryHeaders()
+    headers['Accept-Encoding'] = 'gzip'
+    headers['DD-API-KEY'] = this.#config.apiKey
+    if (this.#etag) headers['If-None-Match'] = this.#etag
+
+    /**
+     * @param {(response: PollResponse) => void} resolve
+     */
+    const execute = (resolve) => {
+      /**
+       * @param {Error | null} error
+       * @param {string | import('node:http').IncomingMessage | null | undefined} body
+       * @param {number | undefined} statusCode
+       * @param {import('node:http').IncomingHttpHeaders | undefined} responseHeaders
+       */
+      const onResponse = (error, body, statusCode, responseHeaders) => {
+        resolve({
+          error,
+          body: typeof body === 'string' ? body : undefined,
+          statusCode,
+          headers: responseHeaders,
+        })
+      }
+
+      request('', {
+        url: this.#config.endpoint,
+        method: 'GET',
+        headers,
+        retry: false,
+        signal,
+        timeout: this.#config.requestTimeoutMs,
+      }, onResponse)
+    }
+
+    return new Promise(execute)
+  }
+
+  /**
+   * @param {PollResponse} response
+   * @returns {void}
+   */
+  #apply (response) {
+    const statusCode = response.statusCode
+    if (statusCode === 304) return
+
+    if (statusCode === 401 || statusCode === 403) {
+      this.#warnFailure(statusCode, undefined, 1)
+      return
+    }
+
+    if (statusCode !== 200) return
+
+    let configuration
+    try {
+      configuration = parseConfiguration(response.body)
+    } catch {
+      if (!this.#malformedPayloadLogged) {
+        this.#malformedPayloadLogged = true
+        log.error('Feature Flagging agentless endpoint returned malformed UFC payload')
+      }
+      return
+    }
+
+    try {
+      this.#applyConfiguration(configuration)
+    } catch (error) {
+      if (!this.#applicationFailureLogged) {
+        this.#applicationFailureLogged = true
+        log.warn('Feature Flagging agentless UFC payload could not be applied: %s', errorMessage(error))
+      }
+      return
+    }
+
+    const etag = response.headers?.etag
+    const value = Array.isArray(etag) ? etag[0] : etag
+    this.#etag = value?.trim() || undefined
+  }
+
+  /**
+   * @param {number | undefined} statusCode
+   * @param {unknown} error
+   * @param {number} attempts
+   * @returns {void}
+   */
+  #warnFailure (statusCode, error, attempts) {
+    const category = statusCode === 401 || statusCode === 403
+      ? 'authentication'
+      : statusCode ? 'http' : 'request'
+    if (this.#failureWarnings.has(category)) return
+    this.#failureWarnings.add(category)
+
+    if (statusCode === 401 || statusCode === 403) {
+      log.warn(
+        'Feature Flagging agentless endpoint returned HTTP %d; verify DD_API_KEY is configured and valid',
+        statusCode
+      )
+    } else if (statusCode) {
+      log.warn('Feature Flagging agentless endpoint returned HTTP %d after %d attempts', statusCode, attempts)
+    } else if (attempts > 1) {
+      log.warn('Feature Flagging agentless request failed after %d attempts: %s', attempts, errorMessage(error))
+    } else {
+      log.warn('Feature Flagging agentless request failed: %s', errorMessage(error))
+    }
+  }
+}
+
+/**
+ * @param {number} delay
+ * @param {AbortSignal} signal
+ * @returns {Promise<boolean>}
+ */
+async function wait (delay, signal) {
+  try {
+    await sleep(delay, undefined, { ref: false, signal })
+    return true
+  } catch (error) {
+    if (error?.name === 'AbortError') return false
+    throw error
+  }
+}
+
+/**
+ * @param {string | undefined} body
+ * @returns {UniversalFlagConfiguration}
+ */
+function parseConfiguration (body) {
+  const { data } = JSON.parse(body)
+  if (data?.type !== 'universal-flag-configuration') {
+    throw new Error('Expected a JSON:API Universal Flag Configuration resource')
+  }
+
+  const { attributes } = data
+  if (typeof attributes?.format !== 'string' ||
+      typeof attributes.createdAt !== 'string' ||
+      typeof attributes.environment?.name !== 'string' ||
+      !attributes.flags ||
+      typeof attributes.flags !== 'object' ||
+      Array.isArray(attributes.flags)) {
+    throw new Error('Expected a Universal Flag Configuration v1 object')
+  }
+
+  return attributes
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorMessage (error) {
+  return error instanceof Error ? error.message : String(error ?? 'request was not sent')
+}
+
+/**
+ * @param {number | undefined} status
+ * @returns {boolean}
+ */
+function isRetryableStatus (status) {
+  return status === 408 || status === 429 || (status >= 500 && status <= 599)
+}
+
+/**
+ * @param {number} pollIntervalMs
+ * @param {number} attempt
+ * @param {number} random
+ * @returns {number}
+ */
+function retryDelay (pollIntervalMs, attempt, random) {
+  const base = attempt === 1
+    ? clamp(pollIntervalMs / 6, FIRST_RETRY_MIN_MS, FIRST_RETRY_MAX_MS)
+    : clamp(pollIntervalMs / 3, SECOND_RETRY_MIN_MS, SECOND_RETRY_MAX_MS)
+  return Math.max(1, Math.round(base * (1 - RETRY_JITTER + random * RETRY_JITTER * 2)))
+}
+
+/**
+ * @param {number} value
+ * @param {number} minimum
+ * @param {number} maximum
+ * @returns {number}
+ */
+function clamp (value, minimum, maximum) {
+  return Math.max(minimum, Math.min(maximum, value))
+}
+
+module.exports = AgentlessConfigurationSource