dd-trace 6.16.0 → 6.17.0

package/packages/datadog-instrumentations/src/openai-realtime/audio-accumulator.js

@@ -0,0 +1,241 @@
+'use strict'
+
+const {
+  LLMOBS_AUDIO_ACCUMULATE_MAX_BYTES,
+} = require('../../../dd-trace/src/llmobs/constants/audio')
+
+/**
+ * Collects one side of a realtime turn's audio, decoding each base64 frame to a `Buffer` as it
+ * arrives.
+ *
+ * Decoding eagerly rather than retaining base64 costs 1x memory instead of 1.33x, and — because the
+ * segment is then just bytes — lets `trimLeading` and `capTo` cut at an exact byte offset with a
+ * `subarray`, where operating on base64 would have to decode and re-encode the straddling frame.
+ *
+ * `present` records that audio was seen at all, so a turn can still surface an `[audio]` marker when
+ * the bytes were dropped; `oversize` marks that the retention cap is currently spent, which stops
+ * `append` retaining anything further. It is a statement about the bytes held right now, not a
+ * permanent mark on the segment: `trimLeading` re-derives it from what survived, so shedding a
+ * lead-in that spent the cap reopens the segment for the speech that follows.
+ *
+ * Constructed with `retain = false` when nothing consumes the audio, which is the default APM-only
+ * configuration: the byte *count* still drives the speech windows, but no frame is decoded and no
+ * segment is held.
+ */
+class AudioAccumulator {
+  /** @type {Buffer[]} */
+  chunks = []
+
+  present = false
+
+  oversize = false
+
+  /**
+   * Wall clock (epoch ms) when the first frame of this segment was observed, anchoring it on the
+   * session timeline. Set even when the bytes are later dropped, since `present` still surfaces a
+   * marker.
+   *
+   * @type {number | undefined}
+   */
+  startTime = undefined
+
+  /**
+   * The audio format in force when this segment's first frame arrived. A segment keeps the format it
+   * was captured under, so a later `session.update` cannot retime bytes that arrived before it.
+   *
+   * @type {string}
+   */
+  mimeType = ''
+
+  /** @type {number} */
+  sampleRate = 0
+
+  /**
+   * Total bytes seen for this segment, never reduced by the retention cap. Playback duration — and
+   * therefore the speaking window — is derived from this, so it stays accurate even when `chunks`
+   * was dropped.
+   */
+  totalDecodedBytes = 0
+
+  /** Bytes currently retained across `chunks`. */
+  #retainedBytes = 0
+
+  /**
+   * Whether anything consumes the bytes. When false only `totalDecodedBytes` is maintained.
+   *
+   * Resolved from `#shouldRetain` on the frame that opens the segment, not at construction: a
+   * pending input segment is created as soon as the previous turn starts and then sits open across
+   * the whole agent response, so construction time can be many seconds before any audio arrives and
+   * whatever was true then may not be true now. Deciding on the opening frame is as late as
+   * possible while still being once per segment, so retention can never flip mid-clip and leave a
+   * segment holding only part of itself.
+   *
+   * @type {boolean}
+   */
+  #retain = true
+
+  /** @type {() => boolean} */
+  #shouldRetain
+
+  /**
+   * @param {(() => boolean) | boolean} [shouldRetain]
+   */
+  constructor (shouldRetain = true) {
+    this.#shouldRetain = typeof shouldRetain === 'function' ? shouldRetain : () => shouldRetain
+  }
+
+  /**
+   * Add one base64 audio frame, reporting its decoded byte count for the input-buffer clock.
+   *
+   * @param {string} base64
+   * @param {number} now - Epoch ms at which this frame was observed.
+   * @param {string} [mimeType] - The session's audio format, recorded on the first frame only.
+   * @param {number} [sampleRate]
+   */
+  append (base64, now, mimeType = '', sampleRate = 0) {
+    if (typeof base64 !== 'string' || base64.length === 0) return 0
+
+    if (this.startTime === undefined) {
+      this.startTime = now
+      this.mimeType = mimeType
+      this.sampleRate = sampleRate
+      this.#retain = this.#shouldRetain()
+    }
+    this.present = true
+
+    // Size the frame without allocating — `byteLength` is exactly what `Buffer.from(base64,
+    // 'base64').length` would be — so every path that ends up discarding the frame pays nothing for
+    // it. Decoding first would make the retention cap a bound on what is *kept* rather than on peak
+    // allocation, and an oversize live stream would keep paying for discarded decodes.
+    const decodedLength = Buffer.byteLength(base64, 'base64')
+    this.totalDecodedBytes += decodedLength
+
+    if (!this.#retain || this.oversize) return decodedLength
+
+    if (this.#retainedBytes + decodedLength > LLMOBS_AUDIO_ACCUMULATE_MAX_BYTES) {
+      // Free what we had: the size guard would drop the whole segment anyway. `#retainedBytes` goes
+      // with it, so it never describes more bytes than `chunks` holds.
+      this.oversize = true
+      this.chunks = []
+      this.#retainedBytes = 0
+      return decodedLength
+    }
+
+    this.#retainedBytes += decodedLength
+    this.chunks.push(Buffer.from(base64, 'base64'))
+    return decodedLength
+  }
+
+  /**
+   * Drop this segment's first `decodedBytes` bytes.
+   *
+   * Cuts the pre-speech audio a continuously-streaming client appends — the microphone keeps sending
+   * while the agent talks — off the front of a user turn, so the captured audio covers the same
+   * window the span reports.
+   *
+   * @param {number} decodedBytes
+   */
+  trimLeading (decodedBytes) {
+    if (!(decodedBytes > 0)) return
+
+    if (decodedBytes >= this.totalDecodedBytes) {
+      // Everything seen so far precedes the onset, so the segment starts empty. Reset outright,
+      // retention cap included: otherwise a long silent lead-in — the buffer stays open across the
+      // whole previous agent response — could spend the cap before the speech even starts and leave
+      // the turn with nothing but an `[audio]` marker.
+      this.clear()
+      return
+    }
+
+    let remaining = decodedBytes
+    while (this.chunks.length > 0 && remaining > 0) {
+      const chunk = this.chunks[0]
+      if (chunk.length > remaining) {
+        this.chunks[0] = chunk.subarray(remaining)
+        break
+      }
+      this.chunks.shift()
+      remaining -= chunk.length
+    }
+
+    this.#retainedBytes = 0
+    for (const chunk of this.chunks) this.#retainedBytes += chunk.length
+
+    // Reopen retention around whatever survived. This is what the trim is for: on a continuously
+    // streaming client the lead-in is what spends the cap — the buffer stays open across the whole
+    // previous agent response — and once `append` trips, it drops every later frame. Leaving the
+    // segment closed here would discard the user's actual speech and leave the turn with nothing but
+    // an `[audio]` marker, which is the outcome trimming exists to prevent.
+    //
+    // A segment that had already tripped the cap holds nothing, so it reopens empty and the clip
+    // starts at the next frame. `audio_start_ms` carries the session's `prefix_padding_ms`, so the
+    // bytes missing from the front are that padding rather than speech — `speech_started` fires at
+    // the onset, before there is speech to lose. The duration derived from `totalDecodedBytes`
+    // therefore runs a padding's-width longer than the clip it describes, which is the price of
+    // keeping the speech at all.
+    this.oversize = this.#retainedBytes > LLMOBS_AUDIO_ACCUMULATE_MAX_BYTES
+
+    this.totalDecodedBytes -= decodedBytes
+  }
+
+  /**
+   * Shrink this segment to its first `decodedBytes` bytes.
+   *
+   * The mirror of `trimLeading`, for audio that was delivered but never heard: when the listener cuts
+   * the agent off, everything past that point is generated-but-unplayed. Absolute and shrink-only, so
+   * a client truncation and the server's acknowledgement of it apply the cap once between them.
+   *
+   * @param {number} decodedBytes
+   */
+  capTo (decodedBytes) {
+    if (decodedBytes >= this.totalDecodedBytes) return
+
+    if (decodedBytes <= 0) {
+      // Nothing was heard at all, so the segment is empty rather than zero-length-but-present.
+      this.clear()
+      return
+    }
+
+    let kept = 0
+    const chunks = []
+    for (const chunk of this.chunks) {
+      if (kept + chunk.length <= decodedBytes) {
+        chunks.push(chunk)
+        kept += chunk.length
+        continue
+      }
+      const partial = chunk.subarray(0, decodedBytes - kept)
+      if (partial.length > 0) {
+        chunks.push(partial)
+        kept += partial.length
+      }
+      break
+    }
+
+    this.chunks = chunks
+    this.#retainedBytes = kept
+    this.totalDecodedBytes = decodedBytes
+  }
+
+  /**
+   * The retained audio as one buffer. Empty when the segment was dropped or never had bytes.
+   *
+   * @returns {Buffer}
+   */
+  toBuffer () {
+    return this.chunks.length === 1 ? this.chunks[0] : Buffer.concat(this.chunks, this.#retainedBytes)
+  }
+
+  clear () {
+    this.chunks = []
+    this.present = false
+    this.oversize = false
+    this.startTime = undefined
+    this.mimeType = ''
+    this.sampleRate = 0
+    this.totalDecodedBytes = 0
+    this.#retainedBytes = 0
+  }
+}
+
+module.exports = AudioAccumulator

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

@@ -0,0 +1,76 @@
+'use strict'
+
+/**
+ * @typedef {import('./turns').ToolCall} ToolCall
+ * @typedef {import('./turns').ToolResult} ToolResult
+ */
+
+/**
+ * Collapse SDK naming drift so `response.output_audio.*` / `response.output_text.*` match their
+ * older `response.audio.*` / `response.text.*` equivalents.
+ *
+ * @param {string} eventType
+ */
+function normalizeResponseEventType (eventType) {
+  // Only `response.*` events carry the renamed segments, and they are a small fraction of the
+  // stream, so skip the three replacements entirely for everything else.
+  if (!eventType.startsWith('response.')) return eventType
+
+  return eventType
+    .replace('.output_audio_transcript', '.audio_transcript')
+    .replace('.output_audio', '.audio')
+    .replace('.output_text', '.text')
+}
+
+/**
+ * Pull function and MCP tool usage out of a `response.done`'s output items.
+ *
+ * Function calls become tool calls — the app returns their result later via `function_call_output`,
+ * captured on the next turn's input. MCP calls run server-side, so their result is inline on the
+ * item and is captured as a tool result alongside the call.
+ *
+ * `arguments` is left as the raw JSON string the API sent; the LLM Observability plugin parses it,
+ * so this stays a provider-native extraction.
+ *
+ * @param {{ output?: Array<Record<string, unknown>> }} response
+ * @returns {{ toolCalls: ToolCall[], toolResults: ToolResult[] }}
+ */
+function extractResponseTools (response) {
+  /** @type {ToolCall[]} */
+  const toolCalls = []
+  /** @type {ToolResult[]} */
+  const toolResults = []
+
+  const output = response?.output
+  if (!output) return { toolCalls, toolResults }
+
+  for (const item of output) {
+    if (item?.type === 'function_call') {
+      toolCalls.push({
+        name: String(item.name ?? ''),
+        arguments: item.arguments,
+        toolId: String(item.call_id ?? item.id ?? ''),
+        type: 'function',
+      })
+    } else if (item?.type === 'mcp_call') {
+      const toolId = String(item.id ?? '')
+      const name = String(item.name ?? '')
+
+      toolCalls.push({ name, arguments: item.arguments, toolId, type: 'mcp_call' })
+
+      const { output, error } = item
+      if (output != null || error != null) {
+        toolResults.push({
+          name,
+          result: String(output ?? error),
+          toolId,
+          type: 'mcp_tool_result',
+        })
+      }
+    }
+  }
+
+  return { toolCalls, toolResults }
+}
+
+module.exports = { extractResponseTools, normalizeResponseEventType }

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

@@ -0,0 +1,301 @@
+'use strict'
+
+const dc = require('dc-polyfill')
+
+const { getValueFromEnvSources } = require('../../../dd-trace/src/config/helper')
+const log = require('../../../dd-trace/src/log')
+const shimmer = require('../../../datadog-shimmer')
+const RealtimeSession = require('./session')
+
+/**
+ * @typedef {import('./session').TurnDescriptor} TurnDescriptor
+ * @typedef {import('./turns').ResponseTurn} ResponseTurn
+ */
+
+// One span per phase of a turn. `user speech` and `agent speech` share a channel: they differ only
+// by name and resource, which is data, not a type.
+const turnChannel = dc.tracingChannel('apm:openai:realtime:turn')
+const responseChannel = dc.tracingChannel('apm:openai:realtime:response')
+const speechChannel = dc.tracingChannel('apm:openai:realtime:speech')
+
+// Published once per turn at `response.created`. The tracing and LLM Observability plugins each
+// compose a `runInContext` onto the turn, so the tree replayed at finalize nests under whatever
+// context the caller had active — the active context at finalize is the socket's, not theirs.
+const captureContextChannel = dc.channel('dd-trace:openai:realtime:capture-context')
+
+// Never published on — subscribed to as a capability signal, the way `captureContextChannel` is
+// probed before publishing. Only LLM Observability consumes a turn's audio bytes (the tracing
+// plugins read the model and the phase boundaries), and a disabled plugin unsubscribes its channels,
+// so `hasSubscribers` here is exactly "someone will read the audio". Without it the default
+// APM-only configuration decodes and buffers every frame of every turn for no consumer.
+//
+// A dedicated channel is what makes the distinction possible: the two plugin families share the
+// `apm:openai:realtime:*` prefixes, so the turn channel cannot tell them apart.
+const audioChannel = dc.channel('dd-trace:openai:realtime:audio')
+
+const USER_SPEECH = { operation: 'createRealtimeUserSpeech', llmobsName: 'user speech' }
+const AGENT_SPEECH = { operation: 'createRealtimeAgentSpeech', llmobsName: 'agent speech' }
+
+/** @type {WeakMap<object, { session: RealtimeSession, finalize: () => void }>} */
+const connections = new WeakMap()
+
+/**
+ * Live sessions, weakly, so a process exiting without closing its connections still reports the
+ * turns they hold. Weak because a realtime connection can outlive many turns and we must not be the
+ * reason one stays reachable.
+ *
+ * @type {Set<WeakRef<RealtimeSession>>}
+ */
+const liveSessions = new Set()
+
+function noop () {}
+
+/**
+ * Replay a finished turn as a back-dated span tree. Nesting falls out of the synchronous scoping of
+ * `traceSync`: the phase spans are created inside the turn root's callback, so each picks the root
+ * up as its parent from the active store without any explicit parent stamping.
+ *
+ * @param {TurnDescriptor} turn
+ */
+function emitTurn (turn) {
+  const run = turn.runInContext ?? (fn => fn())
+
+  run(() => {
+    turnChannel.traceSync(() => {
+      const { userSpeech, agentSpeech } = turn
+
+      if (userSpeech !== undefined) {
+        speechChannel.traceSync(noop, { turn, phase: USER_SPEECH, ...userSpeech })
+      }
+
+      responseChannel.traceSync(noop, {
+        turn,
+        startTime: turn.llm.startTime,
+        finishTime: turn.llm.finishTime,
+      })
+
+      if (agentSpeech !== undefined) {
+        speechChannel.traceSync(noop, { turn, phase: AGENT_SPEECH, ...agentSpeech })
+      }
+    }, { turn, startTime: turn.root.startTime, finishTime: turn.root.finishTime })
+  })
+}
+
+/**
+ * @param {ResponseTurn} turn
+ */
+function captureContext (turn) {
+  if (captureContextChannel.hasSubscribers) captureContextChannel.publish(turn)
+}
+
+/**
+ * Start tracking a connection, reading the model and base path off the URL the SDK already built.
+ *
+ * @param {object} emitter
+ * @returns {{ session: RealtimeSession, finalize: () => void }}
+ */
+function createConnection (emitter) {
+  let model
+  let basePath = ''
+
+  try {
+    const { url } = emitter
+    if (url) {
+      // Azure names it `deployment`; a sideband `call_id` connection has neither, and picks the
+      // model up from `session.created` instead.
+      model = url.searchParams.get('model') ?? url.searchParams.get('deployment') ?? undefined
+      // Origin and path only. The query string carries `Authorization` / `api-key` on the Azure
+      // path, before the SDK redacts them.
+      basePath = url.origin + url.pathname
+    }
+  } catch {
+    // The URL shape is not guaranteed across SDK versions; the session works without it.
+  }
+
+  // Asked per segment rather than snapshotted here: a plugin can be reconfigured while a connection
+  // is open, and a session that outlived its consumer would otherwise keep buffering audio nothing
+  // reads.
+  const session = new RealtimeSession({
+    emitTurn,
+    captureContext,
+    model,
+    basePath,
+    shouldRetainAudio: () => audioChannel.hasSubscribers,
+  })
+
+  const reference = new WeakRef(session)
+  liveSessions.add(reference)
+
+  /**
+   * @param {boolean} [failed] - Whether the connection ended abnormally, so a response still in
+   *   flight is reported as failed rather than as a clean finish.
+   */
+  const finalize = (failed = false) => {
+    liveSessions.delete(reference)
+    session.finishSession(Date.now(), failed)
+  }
+
+  const connection = { session, finalize }
+  attachSocketClose(emitter, finalize)
+  return connection
+}
+
+// Close codes that mean the conversation ended on purpose: a normal close, the peer going away, and
+// the "no status received" code `ws` reports for a close frame that carried none. Anything else — a
+// dropped connection (1006), an internal error (1011) — cut a response short, so a turn still in
+// flight is a failure rather than a clean finish.
+const NORMAL_CLOSE_CODES = new Set([1000, 1001, 1005])
+
+/**
+ * @param {unknown} code
+ */
+function isAbnormalClose (code) {
+  return typeof code === 'number' && !NORMAL_CLOSE_CODES.has(code)
+}
+
+/**
+ * Finalize when the server closes the connection, so a caller that never calls `close()` — or whose
+ * connection drops — still reports its turns. `close` alone covers both transports: `ws` emits
+ * `error` then always `close`, and a global `WebSocket` that fails to connect does the same.
+ *
+ * @param {object} emitter
+ * @param {(failed?: boolean) => void} finalize
+ */
+function attachSocketClose (emitter, finalize) {
+  try {
+    const { socket } = emitter
+    if (socket == null) return
+
+    // `ws` sockets are Node EventEmitters and also expose `addEventListener`, so check `on` first.
+    // The close code arrives as an argument on the `ws` surface and on the `CloseEvent` on the DOM
+    // one; an app-initiated `close()` goes through the shim below instead and is never flagged.
+    if (typeof socket.on === 'function') {
+      socket.once('close', code => finalize(isAbnormalClose(code)))
+    } else if (typeof socket.addEventListener === 'function') {
+      socket.addEventListener('close', event => finalize(isAbnormalClose(event?.code)), { once: true })
+    }
+  } catch (error) {
+    log.debug('Error attaching OpenAI realtime close listener: %s', error?.message)
+  }
+}
+
+/**
+ * @param {object} emitter
+ * @returns {{ session: RealtimeSession, finalize: () => void } | undefined}
+ */
+function getConnection (emitter) {
+  const connection = connections.get(emitter)
+  if (connection !== undefined) return connection
+
+  // Nothing is listening, so never allocate. Checked only on the miss path, so an established
+  // connection pays one WeakMap lookup per event.
+  if (!turnChannel.start.hasSubscribers) return
+
+  const created = createConnection(emitter)
+  connections.set(emitter, created)
+  return created
+}
+
+/**
+ * Wrap the emitter's `_emit` — the single funnel every server event passes through, ahead of the
+ * app's own listeners.
+ *
+ * `_emit` is inherited from the SDK's generic `EventEmitter`, which its streaming helpers also use;
+ * `shimmer.wrap` defines an own property on the realtime prototype instead of touching that shared
+ * one.
+ *
+ * @param {object} prototype
+ */
+function patchRealtimeEmitter (prototype) {
+  if (prototype == null) return
+
+  shimmer.wrap(prototype, '_emit', _emit => function (name, event) {
+    // `_emit` fires twice per server event — once as `event`, once as the event's own type — so the
+    // second half of the traffic is eliminated by a pointer compare before any other work.
+    if (name === 'event') {
+      const connection = getConnection(this)
+      // Observed before the app's listeners run: this feature is timestamps, and the app's own
+      // audio-playback callbacks would otherwise land inside the measured window.
+      if (connection !== undefined) connection.session.onServerEvent(event, Date.now())
+    }
+
+    return _emit.apply(this, arguments)
+  })
+}
+
+/**
+ * Wrap a concrete realtime transport's `send` (every client event) and `close` (session end).
+ *
+ * @param {object} prototype
+ */
+function patchRealtimeTransport (prototype) {
+  if (prototype == null) return
+
+  shimmer.wrap(prototype, 'send', send => function (event) {
+    // Recorded only after the send succeeds, so a failed send doesn't attribute unsent audio to the
+    // next turn.
+    const result = send.apply(this, arguments)
+
+    const connection = getConnection(this)
+    if (connection !== undefined) connection.session.onClientEvent(event, Date.now())
+
+    return result
+  })
+
+  shimmer.wrap(prototype, 'close', close => function () {
+    const connection = connections.get(this)
+    try {
+      return close.apply(this, arguments)
+    } finally {
+      // In a `finally` deliberately. Every realtime transport wraps `socket.close()` in its own
+      // try/catch and routes a failure to `_onError` (which rejects a promise rather than
+      // rethrowing), so this call does not throw and the two placements are equivalent today —
+      // but if that ever changes, finalizing is what keeps the session from leaking. The socket's
+      // close event is the other half of that guarantee.
+      connection?.finalize()
+    }
+  })
+}
+
+/**
+ * Realtime is a large wrapping surface that buffers audio in memory, so it can be turned off on its
+ * own without giving up the rest of the OpenAI integration.
+ *
+ * Read through every configuration source, not just `process.env`: this is an operator-facing kill
+ * switch, and an org that sets it through Fleet Automation or local stable config would otherwise
+ * see it reported as disabled in configuration telemetry while the patching stayed on. Resolving it
+ * here also applies the option's registered boolean parser and its `true` default.
+ */
+function realtimeEnabled () {
+  return getValueFromEnvSources('DD_OPENAI_REALTIME_ENABLED') !== false
+}
+
+/**
+ * Submit whatever live sessions still hold, at process exit.
+ *
+ * This is the only backstop for a connection the app drops without closing. A `FinalizationRegistry`
+ * would not help: the socket's own `message` handler closes over the emitter, and libuv holds the
+ * socket for as long as the connection is open, so the emitter is never unreachable while there is
+ * anything left to report.
+ */
+function flushLiveSessions () {
+  for (const reference of liveSessions) {
+    const session = reference.deref()
+    if (session === undefined) {
+      liveSessions.delete(reference)
+      continue
+    }
+    // Idempotent, so a session already closed by `close()` or a socket close costs nothing here.
+    session.finishSession(Date.now())
+  }
+  liveSessions.clear()
+}
+
+globalThis[Symbol.for('dd-trace')]?.beforeExitHandlers?.add(flushLiveSessions)
+
+module.exports = {
+  flushLiveSessions,
+  patchRealtimeEmitter,
+  patchRealtimeTransport,
+  realtimeEnabled,
+}