dd-trace 6.15.0 → 6.17.0

package/packages/datadog-instrumentations/src/openai-realtime/turns.js

@@ -0,0 +1,211 @@
+'use strict'
+
+const AudioAccumulator = require('./audio-accumulator')
+
+/**
+ * @typedef {{ name?: string, arguments?: unknown, toolId?: string, type?: string }} ToolCall
+ * @typedef {{ name?: string, result?: string, toolId?: string, type?: string }} ToolResult
+ */
+
+/**
+ * One response's text or transcript, accumulated across the output items it arrives in.
+ *
+ * Deltas stream per output item, and each item ends with a `.done` carrying that item's
+ * authoritative final value. A single response can hold several output items — a server-side MCP
+ * call sits between a preamble message and the answer — so a `.done` replaces only the span its own
+ * item contributed rather than the whole response, which would drop every item before it.
+ *
+ * Events that carry no item id are treated as one continuous item, which is how a response with a
+ * single output item behaves anyway.
+ */
+class ItemText {
+  /** @type {string} */
+  value = ''
+
+  /** @type {string | undefined} */
+  #itemId = undefined
+
+  /** Offset into `value` at which the current item's span begins. */
+  #itemStart = 0
+
+  /**
+   * @param {unknown} itemId
+   * @param {string} delta
+   */
+  appendDelta (itemId, delta) {
+    this.#openItem(itemId)
+    this.value += delta
+  }
+
+  /**
+   * Replace the current item's span with the final value the server reported for it.
+   *
+   * @param {unknown} itemId
+   * @param {string} final
+   */
+  complete (itemId, final) {
+    this.#openItem(itemId)
+    this.value = this.value.slice(0, this.#itemStart) + final
+  }
+
+  /**
+   * Begin a new item's span, leaving everything earlier items contributed in place.
+   *
+   * @param {unknown} itemId
+   */
+  #openItem (itemId) {
+    const item = itemId == null ? undefined : String(itemId)
+    if (item === this.#itemId) return
+
+    this.#itemId = item
+    this.#itemStart = this.value.length
+  }
+}
+
+/** Accumulated user input — audio plus transcript or text — for a single turn. */
+class InputTurn {
+  /**
+   * @param {(() => boolean) | boolean} [retainAudio] - Whether anything consumes the bytes, so only
+   *   their count is kept when not. Resolved when the segment opens. See `AudioAccumulator`.
+   */
+  constructor (retainAudio = true) {
+    this.audio = new AudioAccumulator(retainAudio)
+  }
+
+  text = ''
+
+  transcript = ''
+
+  /** @type {string | undefined} */
+  itemId = undefined
+
+  /**
+   * Wall clock (epoch ms) when the user actually started speaking, from the VAD speech-onset event.
+   * This is the start of the user-speech window; the first buffered frame is not, because a
+   * server-VAD client streams the microphone continuously.
+   *
+   * @type {number | undefined}
+   */
+  speechStartTime = undefined
+
+  /**
+   * Wall clock (epoch ms) when the input audio was committed (roughly the end of user speech). Lets
+   * response latency be measured from real speech-end rather than the padded buffer end.
+   *
+   * @type {number | undefined}
+   */
+  speechEndTime = undefined
+
+  /**
+   * Offset (ms) on the session's input-audio-buffer timeline of the first frame buffered for this
+   * turn, so a VAD offset can be converted into a byte offset into `audio`.
+   *
+   * @type {number | undefined}
+   */
+  audioBaseMs = undefined
+
+  /**
+   * Tool results the app fed back (`function_call_output`) before the next response.
+   *
+   * @type {ToolResult[]}
+   */
+  toolResults = []
+
+  /**
+   * The input audio buffer was cleared: drop the buffered audio and the speech onset derived from
+   * it, so neither can be attributed to the next response. A commit that already happened is left
+   * alone — a client that clears the buffer after committing has still ended that speech.
+   */
+  discardAudio () {
+    this.audio.clear()
+    this.speechStartTime = undefined
+    this.audioBaseMs = undefined
+  }
+}
+
+/** Accumulated assistant output for a single `response.*` lifecycle. */
+class ResponseTurn {
+  /**
+   * @param {InputTurn} input
+   * @param {number} createdTime - Epoch ms at which `response.created` arrived. The fallback start
+   *   for the turn root and llm spans when the turn produced no user speech to back-date to.
+   * @param {(() => boolean) | boolean} [retainAudio] - Whether anything consumes the bytes, so only
+   *   their count is kept when not. Resolved when the segment opens. See `AudioAccumulator`.
+   */
+  constructor (input, createdTime, retainAudio = true) {
+    this.input = input
+    this.createdTime = createdTime
+    this.audio = new AudioAccumulator(retainAudio)
+  }
+
+  transcript = new ItemText()
+
+  text = new ItemText()
+
+  /** @type {{ input_tokens?: number, output_tokens?: number, total_tokens?: number } | undefined} */
+  usage = undefined
+
+  /** @type {string | undefined} */
+  model = undefined
+
+  /** @type {string | undefined} */
+  status = undefined
+
+  /**
+   * The provider's own account of a failure, from `response.done`'s `status_details.error`. Carried
+   * separately from `status` because `failed` alone leaves a span with no way to say what went wrong.
+   *
+   * @type {{ type?: string, code?: string, message?: string } | undefined}
+   */
+  error = undefined
+
+  /**
+   * Wall clock (epoch ms) when `response.done` arrived. The llm span ends here — generation
+   * complete — not when the agent finishes speaking.
+   *
+   * @type {number | undefined}
+   */
+  responseDoneTime = undefined
+
+  /**
+   * Byte offset into `audio` at which each output item's audio begins, so a truncation — which is
+   * reported per item — maps onto this turn's segment.
+   *
+   * @type {Map<string, number>}
+   */
+  audioItemStarts = new Map()
+
+  /**
+   * Wall clock (epoch ms) at which the agent's audio would finish playing. Set while the turn is
+   * held open waiting for playback to end.
+   *
+   * @type {number | undefined}
+   */
+  playbackEndTime = undefined
+
+  /**
+   * Runs a callback inside the async context that was active when this turn started, so the span
+   * tree replayed at finalize nests under the caller's own APM and LLM Observability context.
+   * Composed by the tracing and LLM Observability plugins off the capture-context channel; absent
+   * when neither is subscribed.
+   *
+   * @type {((fn: () => void) => void) | undefined}
+   */
+  runInContext = undefined
+
+  /**
+   * Function and MCP calls the model made this turn.
+   *
+   * @type {ToolCall[]}
+   */
+  toolCalls = []
+
+  /**
+   * Inline MCP results for the calls above.
+   *
+   * @type {ToolResult[]}
+   */
+  toolResults = []
+}
+
+module.exports = { InputTurn, ItemText, ResponseTurn }

package/packages/datadog-instrumentations/src/openai.js

@@ -3,51 +3,34 @@
 const dc = require('dc-polyfill')
 const shimmer = require('../../datadog-shimmer')
 const { addHook } = require('./helpers/instrument')
+const { patchRealtimeEmitter, patchRealtimeTransport, realtimeEnabled } = require('./openai-realtime')
 
 const ch = dc.tracingChannel('apm:openai:request')
 const onStreamedChunkCh = dc.channel('apm:openai:request:chunk')
 const responsePromiseContexts = new WeakMap()
 
-// Provider lifecycle channels. Payloads stay OpenAI-native:
-// before { args, parentSpan, abortController, pending }
-// after  { args, body, parentSpan, abortController, pending }
-const chatCompletionsBeforeChannel = dc.channel('dd-trace:openai:chat.completions:before')
-const chatCompletionsAfterChannel = dc.channel('dd-trace:openai:chat.completions:after')
-const responsesBeforeChannel = dc.channel('dd-trace:openai:responses:before')
-const responsesAfterChannel = dc.channel('dd-trace:openai:responses:after')
-
-const LIFECYCLE_CHANNELS = {
-  'chat.completions': {
-    before: chatCompletionsBeforeChannel,
-    after: chatCompletionsAfterChannel,
-  },
-  responses: {
-    before: responsesBeforeChannel,
-    after: responsesAfterChannel,
-  },
-}
+// Published synchronously with the native call data. A subscriber may set either callback and
+// this instrumentation applies it, so the wrapping stays here and only the policy lives outside:
+//   beforeResult () => Promise<void>|undefined   holds the result back until it settles
+//   onResult (body) => unknown|Promise<unknown>  inspects or replaces the delivered body
+const chatCompletionsInterceptChannel = dc.channel('dd-trace:openai:chat.completions:intercept')
+const responsesInterceptChannel = dc.channel('dd-trace:openai:responses:intercept')
 
 /**
- * Publishes a provider-native lifecycle payload to a cancelable lifecycle channel.
- *
- * Subscribers push async work into `pending` synchronously during publication and
- * abort `abortController` with an error before the pushed promise resolves to block.
+ * Returns `promise`, but not before `settled` settles, so a rejection from an interceptor
+ * reaches the caller instead of the SDK's value.
  *
- * @param {object} channel
- * @param {object} payload
- * @returns {Promise<void>}
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {Promise<void>|undefined} settled
+ * @returns {Promise<T>}
  */
-function publishLifecycle (channel, payload) {
-  const abortController = new AbortController()
-  const ctx = { ...payload, abortController, pending: [] }
+function heldUntil (promise, settled) {
+  if (!settled) return promise
 
-  channel.publish(ctx)
-
-  return Promise.all(ctx.pending).then(() => {
-    if (abortController.signal.aborted) {
-      throw abortController.signal.reason
-    }
-  })
+  // The interceptor's rejection wins over an earlier SDK rejection, so keep that one handled.
+  promise.catch(() => {})
+  return settled.then(() => promise)
 }
 
 const V4_PACKAGE_SHIMS = [
@@ -57,6 +40,7 @@ const V4_PACKAGE_SHIMS = [
     baseResource: 'chat.completions',
     methods: ['create'],
     streamedResponse: true,
+    interceptChannel: chatCompletionsInterceptChannel,
   },
   {
     file: 'resources/completions',
@@ -72,6 +56,7 @@ const V4_PACKAGE_SHIMS = [
     methods: ['create'], // implicitly covers `parse` as well which calls `create` under the hood
     streamedResponse: true,
     versions: ['>=4.87.0'],
+    interceptChannel: responsesInterceptChannel,
   },
   {
     file: 'resources/embeddings',
@@ -185,6 +170,7 @@ const V4_PACKAGE_SHIMS = [
     methods: ['create'],
     streamedResponse: true,
     versions: ['>=4.85.0'],
+    interceptChannel: chatCompletionsInterceptChannel,
   },
 ]
 
@@ -287,13 +273,11 @@ for (const extension of extensions) {
         return handleUnwrappedAPIPromise(parsedPromise, state)
       })
 
+      // Raw-response callers bypass `parse`, so run the interceptor here too.
       shimmer.wrap(prototype, 'asResponse', asResponse => function (...args) {
         const state = responsePromiseContexts.get(this.responsePromise)
-        const responsePromise = asResponse.apply(this, args)
-
-        if (!state?.getBeforeVerdict) return responsePromise
 
-        return Promise.all([state.getBeforeVerdict(), responsePromise]).then(([, response]) => response)
+        return heldUntil(asResponse.apply(this, args), state?.interceptCtx?.beforeResult?.())
       })
 
       return exports
@@ -303,7 +287,7 @@ for (const extension of extensions) {
 
 for (const extension of extensions) {
   for (const shim of V4_PACKAGE_SHIMS) {
-    const { file, targetClass, baseResource, methods, versions, streamedResponse } = shim
+    const { file, targetClass, baseResource, methods, versions, streamedResponse, interceptChannel } = shim
     addHook({ name: 'openai', file: file + extension, versions: versions || ['>=4'] }, exports => {
       const targetPrototype = exports[targetClass].prototype
 
@@ -314,10 +298,10 @@ for (const extension of extensions) {
           // chat.completions and completions
           const stream = streamedResponse && getOption(args, 'stream', false)
 
-          const channels = stream ? null : LIFECYCLE_CHANNELS[baseResource]
-          const hasLifecycle = !!channels && (channels.before.hasSubscribers || channels.after.hasSubscribers)
+          const tracing = ch.start.hasSubscribers
+          const intercepted = interceptChannel?.hasSubscribers
 
-          if (!ch.start.hasSubscribers && !hasLifecycle) {
+          if (!tracing && !intercepted) {
             return methodFn.apply(this, args)
           }
 
@@ -330,24 +314,21 @@ for (const extension of extensions) {
           }
 
           return ch.start.runStores(ctx, () => {
-            // Capture the parent span explicitly: the _thenUnwrap/parse path decouples
-            // the lazy evaluation from the active scope at call time.
-            const parentSpan = hasLifecycle ? ctx.currentStore?.span : undefined
-
             const apiProm = methodFn.apply(this, args)
 
-            const beforeChannel = hasLifecycle && channels.before.hasSubscribers ? channels.before : null
-            const afterChannel = hasLifecycle && channels.after.hasSubscribers ? channels.after : null
-            let beforeVerdict
-            const getBeforeVerdict = beforeChannel
-              ? function getBeforeVerdict () {
-                beforeVerdict ??= publishLifecycle(beforeChannel, { args, parentSpan })
-                return beforeVerdict
-              }
-              : null
+            let interceptCtx
+            if (intercepted) {
+              interceptCtx = { arguments: args, tracingContext: ctx }
+              interceptChannel.publish(interceptCtx)
+            }
 
-            const state = { ctx, stream, getBeforeVerdict, afterChannel, parentSpan }
-            responsePromiseContexts.set(apiProm.responsePromise, state)
+            // Keyed by the response promise rather than the APIPromise: `_thenUnwrap` builds a new
+            // APIPromise around the same response, which is how `responses.parse` and the
+            // pagination page types reach the prototype wrappers above. A method that resolves to
+            // a plain value has none, and a WeakMap rejects a non-object key.
+            if (apiProm?.responsePromise) {
+              responsePromiseContexts.set(apiProm.responsePromise, { ctx, stream, interceptCtx, tracing })
+            }
 
             ch.end.publish(ctx)
 
@@ -360,23 +341,57 @@ for (const extension of extensions) {
   }
 }
 
+// The Realtime API is a bidirectional WebSocket event stream, not request/response, so it can't
+// reuse the resource shims above. Every server event funnels through the emitter's `_emit`, and
+// every client event through the transport's `send`.
+//
+// Realtime ships at two paths: the current `realtime/*` (openai >=5.17.0) and the older
+// `beta/realtime/*`, which is a fully duplicated implementation with its own emitter and transport
+// classes — not a re-export — and still ships alongside it. Both are hooked, so an app that has not
+// moved off the beta import path is still instrumented. `addHook` on a file a given version doesn't
+// have is a no-op, so the ranges only need to be loose enough.
+const REALTIME_SHIMS = [
+  { file: 'realtime/internal-base', targetClass: 'OpenAIRealtimeEmitter', versions: ['>=5.17.0'] },
+  { file: 'realtime/ws', targetClass: 'OpenAIRealtimeWS', versions: ['>=5.17.0'] },
+  { file: 'realtime/websocket', targetClass: 'OpenAIRealtimeWebSocket', versions: ['>=5.17.0'] },
+  { file: 'beta/realtime/internal-base', targetClass: 'OpenAIRealtimeEmitter', versions: ['>=4'] },
+  { file: 'beta/realtime/ws', targetClass: 'OpenAIRealtimeWS', versions: ['>=4'] },
+  { file: 'beta/realtime/websocket', targetClass: 'OpenAIRealtimeWebSocket', versions: ['>=4'] },
+]
+
+if (realtimeEnabled()) {
+  for (const extension of extensions) {
+    for (const { file, targetClass, versions } of REALTIME_SHIMS) {
+      addHook({ name: 'openai', file: file + extension, versions }, exports => {
+        const prototype = exports[targetClass]?.prototype
+        if (targetClass === 'OpenAIRealtimeEmitter') {
+          patchRealtimeEmitter(prototype)
+        } else {
+          patchRealtimeTransport(prototype)
+        }
+        return exports
+      })
+    }
+  }
+}
+
 function handleUnwrappedAPIPromise (apiProm, state) {
-  const { ctx, stream, getBeforeVerdict, afterChannel, parentSpan } = state
-  const gatedApiProm = getBeforeVerdict
-    ? Promise.all([getBeforeVerdict(), apiProm]).then(([, result]) => result)
-    : apiProm
+  const { ctx, stream, interceptCtx, tracing } = state
 
-  return gatedApiProm
+  return heldUntil(apiProm, interceptCtx?.beforeResult?.())
     .then(([{ response, options }, body]) => {
       if (stream) {
-        if (body.iterator) {
-          shimmer.wrap(body, 'iterator', wrapStreamIterator(response, options, ctx))
-        } else {
-          shimmer.wrap(
-            body.response.body, Symbol.asyncIterator, wrapStreamIterator(response, options, ctx)
-          )
-        }
-        return body
+        return Promise.resolve(interceptCtx?.onResult ? interceptCtx.onResult(body) : body).then(streamBody => {
+          if (!tracing) return streamBody
+
+          const wrapIterator = wrapStreamIterator(response, options, ctx)
+          if (streamBody.iterator) {
+            shimmer.wrap(streamBody, 'iterator', wrapIterator)
+          } else {
+            shimmer.wrap(streamBody.response.body, Symbol.asyncIterator, wrapIterator)
+          }
+          return streamBody
+        })
       }
 
       const responseData = {
@@ -388,28 +403,29 @@ function handleUnwrappedAPIPromise (apiProm, state) {
         },
       }
 
-      if (!afterChannel) {
+      if (!interceptCtx?.onResult) {
         finish(ctx, responseData)
         return body
       }
 
-      // Finish after evaluation so a block propagates the error to openai.request
-      // and the span wraps its child instead of closing before it.
-      return publishLifecycle(afterChannel, { args: ctx.args, body, parentSpan }).then(() => {
+      // Finish after the callback settles so a rejection propagates to openai.request and the
+      // span wraps its child instead of closing before it.
+      return Promise.resolve(interceptCtx.onResult(body)).then(deliveredBody => {
         finish(ctx, responseData)
-        return body
+        return deliveredBody
       })
     })
     .catch(error => {
-      // ctx.result is set inside finish(); if absent, finish never ran (sync throw in the success
-      // branch, Before Model block, After Model block, or openai error) — record the error now so
-      // the openai.request span is marked errored. If finish already ran, don't double-publish.
-      if (!ctx.result) finish(ctx, undefined, error)
+      finish(ctx, undefined, error)
       throw error
     })
 }
 
 function finish (ctx, response, error) {
+  // `parse` is re-entered on every await of the same APIPromise, and a stream may be iterated
+  // more than once, so the span must only close once.
+  if (ctx.finished) return
+
   if (error) {
     ctx.error = error
     ch.error.publish(ctx)
@@ -419,6 +435,7 @@ function finish (ctx, response, error) {
   // so we don't want to override it here
   ctx.result ??= {}
   Object.assign(ctx.result, response)
+  ctx.finished = true
 
   ch.asyncEnd.publish(ctx)
 }

package/packages/datadog-instrumentations/src/oracledb.js

@@ -105,9 +105,13 @@ addHook({ name: 'oracledb', versions: ['>=5'], file: 'lib/oracledb.js' }, oracle
   })
   shimmer.wrap(oracledb, 'getConnection', getConnection => {
     return function wrappedGetConnection (connAttrs, callback) {
+      if (typeof connAttrs === 'function') {
+        callback = connAttrs
+        connAttrs = undefined
+      }
       if (callback) {
-        arguments[1] = shimmer.wrapFunction(callback, callback => (err, connection) => {
-          if (connection) {
+        arguments[arguments.length - 1] = shimmer.wrapFunction(callback, callback => (err, connection) => {
+          if (connection && !connectionAttributes.has(connection)) {
             connectionAttributes.set(connection, connAttrs)
           }
           callback(err, connection)
@@ -116,7 +120,9 @@ addHook({ name: 'oracledb', versions: ['>=5'], file: 'lib/oracledb.js' }, oracle
         getConnection.apply(this, arguments)
       } else {
         return getConnection.apply(this, arguments).then((connection) => {
-          connectionAttributes.set(connection, connAttrs)
+          if (!connectionAttributes.has(connection)) {
+            connectionAttributes.set(connection, connAttrs)
+          }
           return connection
         })
       }

package/packages/datadog-instrumentations/src/playwright-reporter.js

@@ -2,6 +2,7 @@
 
 const { channel } = require('dc-polyfill')
 
+const libraryConfigurationCh = channel('ci:playwright:library-configuration')
 const reporterErrorCh = channel('ci:playwright:reporter:error')
 const reporterRunSummaryCh = channel('ci:playwright:reporter:run-summary')
 const reporterSuiteHookErrorCh = channel('ci:playwright:reporter:suite-hook-error')
@@ -15,7 +16,6 @@ const PLAYWRIGHT_REPORTER_ERROR_CALLER_RE =
  * interpreting identical user console output as a framework error.
  *
  * @param {unknown} message - First console.error argument
- * @returns {boolean}
  */
 function isPlaywrightReporterError (message) {
   if (message !== PLAYWRIGHT_REPORTER_ERROR_MESSAGE) return false
@@ -34,7 +34,6 @@ function isPlaywrightReporterError (message) {
  * Returns whether a finalized Playwright result contains a failed suite hook.
  *
  * @param {Array<object>} steps
- * @returns {boolean}
  */
 function hasFailedSuiteHook (steps) {
   if (!steps) return false
@@ -71,7 +70,6 @@ class DatadogPlaywrightReporter {
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
    * @param {object} config
-   * @returns {void}
    */
   onConfigure (config) {
     this.failOnFlakyTests = config.failOnFlakyTests
@@ -80,7 +78,6 @@ class DatadogPlaywrightReporter {
   /**
    * Restores console error after Playwright completes the reporter lifecycle.
    *
-   * @returns {void}
    */
   static restoreConsoleError () {
     // eslint-disable-next-line no-console
@@ -99,7 +96,6 @@ class DatadogPlaywrightReporter {
    *
    * @param {object} configOrSuite
    * @param {object} [suite]
-   * @returns {void}
    */
   onBegin (configOrSuite, suite) {
     this.suite = suite || configOrSuite
@@ -110,49 +106,42 @@ class DatadogPlaywrightReporter {
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onTestBegin () {}
 
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onStdOut () {}
 
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onStdErr () {}
 
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onTestEnd () {}
 
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onStepBegin () {}
 
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onStepEnd () {}
 
   /**
    * Marks the beginning of reporter finalization so later reporter errors can be identified.
    *
-   * @returns {void}
    */
   onEnd () {
     let failureCount = this.fatalErrorCount
@@ -182,7 +171,8 @@ class DatadogPlaywrightReporter {
     reporterRunSummaryCh.publish({ failureCount, quarantinedFailureCount, hasIncompleteTests })
     suitesWithHookErrors.clear()
 
-    if (!this.captureReporterErrors) return
+    // A reused config can retain this reporter after the plugin is disabled.
+    if (!this.captureReporterErrors || !libraryConfigurationCh.hasSubscribers) return
 
     this.isFinalizing = true
     // Playwright 1.60 and 1.61 only expose reporter errors through this exact console call.
@@ -212,7 +202,6 @@ class DatadogPlaywrightReporter {
   /**
    * Implements the reporter v2 lifecycle hook required by older Playwright versions.
    *
-   * @returns {void}
    */
   onExit () {}
 
@@ -220,7 +209,6 @@ class DatadogPlaywrightReporter {
    * Reports errors emitted by Playwright while later reporters are finalizing.
    *
    * @param {unknown} error
-   * @returns {void}
    */
   onError (error) {
     if (this.isFinalizing) {
@@ -233,7 +221,6 @@ class DatadogPlaywrightReporter {
   /**
    * Keeps the internal reporter from affecting Playwright's output reporter selection.
    *
-   * @returns {boolean}
    */
   printsToStdio () {
     return false