dd-trace 6.16.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,6 +3,7 @@
 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')
@@ -297,9 +298,10 @@ for (const extension of extensions) {
           // chat.completions and completions
           const stream = streamedResponse && getOption(args, 'stream', false)
 
-          const intercepted = !stream && interceptChannel?.hasSubscribers
+          const tracing = ch.start.hasSubscribers
+          const intercepted = interceptChannel?.hasSubscribers
 
-          if (!ch.start.hasSubscribers && !intercepted) {
+          if (!tracing && !intercepted) {
             return methodFn.apply(this, args)
           }
 
@@ -325,7 +327,7 @@ for (const extension of extensions) {
             // 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 })
+              responsePromiseContexts.set(apiProm.responsePromise, { ctx, stream, interceptCtx, tracing })
             }
 
             ch.end.publish(ctx)
@@ -339,20 +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, interceptCtx } = state
+  const { ctx, stream, interceptCtx, tracing } = state
 
   return heldUntil(apiProm, interceptCtx?.beforeResult?.())
     .then(([{ response, options }, body]) => {
       if (stream) {
-        const wrapIterator = wrapStreamIterator(response, options, ctx)
-
-        if (body.iterator) {
-          shimmer.wrap(body, 'iterator', wrapIterator)
-        } else {
-          shimmer.wrap(body.response.body, Symbol.asyncIterator, wrapIterator)
-        }
-        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 = {

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