dd-trace 6.15.0 → 6.17.0

package/packages/dd-trace/src/evp_proxy/path.js

@@ -1,7 +1,15 @@
 'use strict'
 
 const LEADING_SLASHES = /^\/+/
-const TRAILING_SLASHES = /\/+$/
+
+/**
+ * @param {string} value
+ */
+function stripTrailingSlashes (value) {
+  let end = value.length
+  while (end > 0 && value[end - 1] === '/') end--
+  return end === value.length ? value : value.slice(0, end)
+}
 
 /**
  * Joins a caller-supplied EVP proxy path and product endpoint.
@@ -10,13 +18,12 @@ const TRAILING_SLASHES = /\/+$/
  *
  * @param {string} basePath - EVP proxy base path
  * @param {string} endpoint - Product intake endpoint
- * @returns {string} Joined request path
  */
 function joinEVPProxyPath (basePath, endpoint) {
-  const normalizedBasePath = basePath.replace(TRAILING_SLASHES, '')
+  const normalizedBasePath = stripTrailingSlashes(basePath)
   const normalizedEndpoint = endpoint.replace(LEADING_SLASHES, '')
 
   return `${normalizedBasePath}/${normalizedEndpoint}`
 }
 
-module.exports = { joinEVPProxyPath }
+module.exports = { joinEVPProxyPath, stripTrailingSlashes }

package/packages/dd-trace/src/exporters/agent/writer.js

@@ -44,7 +44,6 @@ class AgentWriter extends BaseWriter {
    * Test Optimization owns its own request lifecycle tracking.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flushDirect (done, options) {
     if (this.#requestTracker) {

package/packages/dd-trace/src/exporters/agentless/index.js

@@ -63,7 +63,6 @@ class AgentlessExporter {
   /**
    * Sets the intake URL.
    * @param {string} urlString - The new intake URL
-   * @returns {boolean} True if URL was set successfully
    */
   setUrl (urlString) {
     try {

package/packages/dd-trace/src/exporters/agentless/intake.js

@@ -25,7 +25,6 @@ const INTAKE_PATH = '/api/v2/spans'
  * reattach the TLD, e.g. 'us2.ddog-gov.com' -> 'https://browser-intake-us2-ddog-gov.com'.
  *
  * @param {string} [site] - The Datadog site, e.g. 'us3.datadoghq.com'. Defaults to 'datadoghq.com'.
- * @returns {string} The intake origin, without a path.
  */
 function computeIntakeUrl (site = 'datadoghq.com') {
   const normalized = site.toLowerCase()

package/packages/dd-trace/src/exporters/agentless/writer.js

@@ -117,9 +117,6 @@ class AgentlessWriter extends BaseWriter {
     }
   }
 
-  /**
-   * @returns {string} The full agentless intake endpoint.
-   */
   #endpoint () {
     const endpoint = new URL(this._url)
     endpoint.pathname = INTAKE_PATH

package/packages/dd-trace/src/exporters/common/docker.js

@@ -12,7 +12,10 @@ const uuidSource =
 const containerSource = '[0-9a-f]{64}'
 const taskSource = String.raw`[0-9a-f]{32}-\d+`
 const lineReg = /^(\d+):([^:]*):(.+)$/m
-const entityReg = new RegExp(String.raw`.*(${uuidSource}|${containerSource}|${taskSource})(?:\.scope)?$`, 'm')
+const entityReg = new RegExp(
+  String.raw`(?:^|/)[^/\r\n\u2028\u2029]*?(${uuidSource}|${containerSource}|${taskSource})(?:\.scope)?$`,
+  'm'
+)
 
 let inode = 0
 let cgroup = ''

package/packages/dd-trace/src/exporters/common/final-flush-request-tracker.js

@@ -45,7 +45,6 @@ class FinalFlushRequestTracker {
    *
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flush (done, options) {
     if (options?.deadline === undefined) {
@@ -112,7 +111,6 @@ class FinalFlushRequestTracker {
    * @param {RequestOptions} options
    * @param {(error: Error|null, result?: string|null, statusCode?: number,
    *   headers?: import('node:http').IncomingHttpHeaders) => void} callback
-   * @returns {void}
    */
   send (request, data, options, callback) {
     const controller = new AbortController()
@@ -141,7 +139,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #dropRequest (pendingRequest) {
     this.#pendingRequests.delete(pendingRequest)
@@ -155,7 +152,6 @@ class FinalFlushRequestTracker {
   /**
    * @param {FinalFlush} finalFlush
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #attachRequest (finalFlush, pendingRequest) {
     finalFlush.requests.add(pendingRequest)
@@ -165,7 +161,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #updateRequestDeadline (pendingRequest) {
     let deadline = 0
@@ -177,7 +172,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {FinalFlush} finalFlush
-   * @returns {void}
    */
   #finishFinalFlush (finalFlush) {
     if (!this.#finalFlushes.has(finalFlush) || !finalFlush.writerDone || finalFlush.requests.size !== 0) return

package/packages/dd-trace/src/exporters/common/proxy.js

@@ -44,6 +44,9 @@ function getHttpsProxyAgent (url, directAgent) {
       ? { keepAlive: directAgent.keepAlive, maxSockets: directAgent.maxSockets }
       : undefined
     agent = new HttpsProxyAgent(proxyUrl, options)
+    // AgentBase normally infers this from the node:https call stack. Interceptors such as MSW
+    // construct http.ClientRequest directly, so identify the target protocol explicitly.
+    agent.protocol = 'https:'
     agents.set(proxyUrl, agent)
   }
   return agent

package/packages/dd-trace/src/exporters/common/request.js

@@ -170,6 +170,7 @@ function request (data, options, callback) {
         }
         const error = new log.NoTransmitError(errorMessage)
         error.status = res.statusCode
+        if (options.includeErrorResponseBody) error.responseBody = responseData
 
         complete(error, null, res.statusCode, res.headers)
       }

package/packages/dd-trace/src/exporters/common/url.js

@@ -7,7 +7,6 @@ const { urlToHttpOptions } = require('./url-to-http-options-polyfill')
 
 /**
  * @param {string} hostname
- * @returns {boolean}
  */
 function isLoopbackHost (hostname) {
   // Gate the 127/8 prefix on an IPv4 literal so names such as 127.example.com cannot pass.
@@ -20,7 +19,6 @@ function isLoopbackHost (hostname) {
 /**
  * @param {string|undefined} protocol
  * @param {string|undefined} hostname
- * @returns {boolean}
  */
 function canSendApiKey (protocol, hostname) {
   return protocol === 'https:' || protocol === 'unix:' ||

package/packages/dd-trace/src/exporters/common/writer.js

@@ -27,7 +27,6 @@ class Writer {
    * Flushes queued telemetry, retaining delivery on supported serverless platforms.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flush (done, options) {
     if (this.#deliveryTracker) {
@@ -40,7 +39,6 @@ class Writer {
    * Flushes queued telemetry without registering serverless delivery retention.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flushDirect (done = noop, options) {
     const count = this._encoder.count()

package/packages/dd-trace/src/id.js

@@ -36,7 +36,6 @@ class Identifier {
 
   /**
    * @param {number} [radix]
-   * @returns {string}
    */
   toString (radix = 16) {
     if (radix === 16) {
@@ -50,9 +49,6 @@ class Identifier {
     return toNumberString(this.#buffer, radix)
   }
 
-  /**
-   * @returns {bigint}
-   */
   toBigInt () {
     this.#bigInt ??= Buffer.from(this.#buffer).readBigUInt64BE(0)
     return this.#bigInt
@@ -75,9 +71,6 @@ class Identifier {
     return this.#buffer.slice(-8)
   }
 
-  /**
-   * @returns {string}
-   */
   toJSON () {
     return this.toString()
   }
@@ -88,7 +81,6 @@ class Identifier {
    * only this identifier's hex representation.
    *
    * @param {string | undefined} traceIdHigh - 16-char hex of the upper 64 bits, or undefined
-   * @returns {string}
    */
   toTraceIdHex (traceIdHigh) {
     if (traceIdHigh && this.#buffer.length <= 8) {
@@ -99,7 +91,6 @@ class Identifier {
 
   /**
    * @param {Identifier} other
-   * @returns {boolean}
    */
   equals (other) {
     // Big-endian suffix compare: when buffers differ in length, only the
@@ -182,7 +173,6 @@ function fromString (str, raddix) {
 /**
  * @param {number[] | Uint8Array} buffer
  * @param {number} [radix]
- * @returns {string}
  */
 function toNumberString (buffer, radix) {
   let high = readInt32(buffer, buffer.length - 8)
@@ -233,7 +223,6 @@ function pseudoRandom () {
 /**
  * @param {number[] | Uint8Array} buffer
  * @param {number} offset
- * @returns {number}
  */
 function readInt32 (buffer, offset) {
   return (buffer[offset + 0] * 16_777_216) +

package/packages/dd-trace/src/llmobs/audio-codec.js

@@ -0,0 +1,192 @@
+'use strict'
+
+// Raw-audio primitives shared by the LLM Observability integrations: mapping provider audio formats
+// to MIME types, decoding telephony audio to PCM16, wrapping PCM16 in a WAV container, and deriving
+// a segment's playback duration from its byte count. Deliberately free of LLM Observability concepts
+// so the realtime instrumentation can use the timing half without pulling in span plumbing.
+
+const { G711_SAMPLE_RATE, PCM16_BYTES_PER_SAMPLE, WAV_HEADER_BYTES } = require('./constants/audio')
+
+// OpenAI Realtime audio `format` values (legacy string form) that don't map to `audio/<format>`.
+// A Map rather than an object literal so a hostile format string ("constructor", "__proto__") can't
+// resolve to something off Object.prototype.
+const REALTIME_FORMAT_MIME_TYPES = new Map([
+  ['pcm16', 'audio/pcm'],
+  ['pcm', 'audio/pcm'],
+  ['g711_ulaw', 'audio/pcmu'],
+  ['g711_alaw', 'audio/pcma'],
+])
+
+// Raw little-endian PCM16. Not renderable on its own, but losslessly wrappable in a WAV container.
+const PCM16_MIME_TYPES = new Set(['audio/pcm', 'audio/pcm16', 'audio/l16'])
+
+// G.711 telephony audio (8 kHz, 8-bit companded), used by Realtime for phone-call integrations.
+const G711_MIME_TO_VARIANT = new Map([
+  ['audio/pcmu', 'ulaw'],
+  ['audio/g711_ulaw', 'ulaw'],
+  ['audio/pcma', 'alaw'],
+  ['audio/g711_alaw', 'alaw'],
+])
+
+/**
+ * Decode one G.711 mu-law byte to a signed 16-bit linear PCM sample (CCITT G.711).
+ *
+ * @param {number} byte
+ */
+function decodeUlawSample (byte) {
+  byte = ~byte & 0xFF
+  let sample = ((byte & 0x0F) << 3) + 0x84
+  sample <<= (byte & 0x70) >> 4
+  return (byte & 0x80) ? (0x84 - sample) : (sample - 0x84)
+}
+
+/**
+ * Decode one G.711 A-law byte to a signed 16-bit linear PCM sample (CCITT G.711).
+ *
+ * @param {number} byte
+ */
+function decodeAlawSample (byte) {
+  byte ^= 0x55
+  let sample = (byte & 0x0F) << 4
+  const segment = (byte & 0x70) >> 4
+  if (segment === 0) {
+    sample += 8
+  } else if (segment === 1) {
+    sample += 0x1_08
+  } else {
+    sample = (sample + 0x1_08) << (segment - 1)
+  }
+  return (byte & 0x80) ? sample : -sample
+}
+
+// The input domain is a single byte, so both decodes collapse to a 256-entry lookup built once.
+const ULAW_TABLE = new Int16Array(256)
+const ALAW_TABLE = new Int16Array(256)
+for (let byte = 0; byte < 256; byte++) {
+  ULAW_TABLE[byte] = decodeUlawSample(byte)
+  ALAW_TABLE[byte] = decodeAlawSample(byte)
+}
+
+/**
+ * Map an OpenAI Realtime audio format to a MIME type.
+ *
+ * Handles both the legacy string form (e.g. "pcm16", "g711_ulaw") and the newer discriminated-union
+ * object whose `type` is already a MIME type (e.g. "audio/pcm"). Yields an empty string when the
+ * format is absent or unusable, which callers treat as "unknown" rather than guessing a rate.
+ *
+ * @param {string | { type?: string } | undefined} format
+ */
+function realtimeAudioFormatToMime (format) {
+  const type = typeof format === 'object' && format !== null ? format.type : format
+  if (typeof type !== 'string') return ''
+
+  const normalized = type.trim().toLowerCase()
+  if (!normalized) return ''
+  if (normalized.startsWith('audio/')) return normalized
+
+  return REALTIME_FORMAT_MIME_TYPES.get(normalized) ?? `audio/${normalized}`
+}
+
+/**
+ * @param {string} mimeType
+ */
+function isPcm16AudioMime (mimeType) {
+  return typeof mimeType === 'string' && PCM16_MIME_TYPES.has(mimeType.trim().toLowerCase())
+}
+
+/**
+ * @param {string} mimeType
+ * @returns {'ulaw' | 'alaw' | undefined} The G.711 variant, or `undefined` for any other format.
+ */
+function g711Variant (mimeType) {
+  if (typeof mimeType !== 'string') return
+  return G711_MIME_TO_VARIANT.get(mimeType.trim().toLowerCase())
+}
+
+/**
+ * Decode G.711 audio to raw little-endian PCM16.
+ *
+ * @param {Buffer} data
+ * @param {'ulaw' | 'alaw'} variant
+ * @returns {Buffer}
+ */
+function g711ToPcm16 (data, variant) {
+  const table = variant === 'alaw' ? ALAW_TABLE : ULAW_TABLE
+  const pcm = Buffer.allocUnsafe(data.length * PCM16_BYTES_PER_SAMPLE)
+  for (let i = 0; i < data.length; i++) {
+    pcm.writeInt16LE(table[data[i]], i * PCM16_BYTES_PER_SAMPLE)
+  }
+  return pcm
+}
+
+/**
+ * Wrap raw little-endian PCM16 audio in a WAV container.
+ *
+ * Lossless and cheap — it only prepends a 44-byte header — and turns raw PCM, which the UI can't
+ * render, into a playable `audio/wav` payload.
+ *
+ * @param {Buffer} pcm
+ * @param {number} [sampleRate]
+ * @param {number} [channels]
+ * @returns {Buffer}
+ */
+function pcm16ToWav (pcm, sampleRate = 24_000, channels = 1) {
+  const blockAlign = channels * PCM16_BYTES_PER_SAMPLE
+  const header = Buffer.allocUnsafe(WAV_HEADER_BYTES)
+
+  header.write('RIFF', 0, 'latin1')
+  header.writeUInt32LE(WAV_HEADER_BYTES - 8 + pcm.length, 4) // RIFF chunk size: everything after this field
+  header.write('WAVE', 8, 'latin1')
+  header.write('fmt ', 12, 'latin1')
+  header.writeUInt32LE(16, 16) // fmt chunk size, 16 for PCM
+  header.writeUInt16LE(1, 20) // audio format, 1 for uncompressed PCM
+  header.writeUInt16LE(channels, 22)
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(sampleRate * blockAlign, 28) // byte rate
+  header.writeUInt16LE(blockAlign, 32)
+  header.writeUInt16LE(PCM16_BYTES_PER_SAMPLE * 8, 34) // bits per sample
+  header.write('data', 36, 'latin1')
+  header.writeUInt32LE(pcm.length, 40)
+
+  return Buffer.concat([header, pcm], WAV_HEADER_BYTES + pcm.length)
+}
+
+/**
+ * Byte rate of a raw audio format: PCM16 is 2 bytes per sample at the session's rate, G.711 is 1
+ * byte per sample at the fixed 8 kHz rate. Any other or unknown format returns `undefined` — we do
+ * not guess a rate, so durations and offsets derived from it are simply unavailable.
+ *
+ * @param {string} mimeType
+ * @param {number} sampleRate
+ * @returns {number | undefined}
+ */
+function bytesPerSecond (mimeType, sampleRate) {
+  if (sampleRate > 0 && isPcm16AudioMime(mimeType)) return sampleRate * PCM16_BYTES_PER_SAMPLE
+  if (g711Variant(mimeType) !== undefined) return G711_SAMPLE_RATE
+}
+
+/**
+ * Playback duration (in milliseconds) of an audio segment, from its decoded byte count. Sizes the
+ * user-speech and agent-speech spans and the turn root's end, so it may be fractional.
+ *
+ * @param {number} decodedBytes
+ * @param {string} mimeType
+ * @param {number} sampleRate
+ * @returns {number | undefined}
+ */
+function segmentDurationMs (decodedBytes, mimeType, sampleRate) {
+  if (!(decodedBytes > 0)) return
+  const rate = bytesPerSecond(mimeType, sampleRate)
+  if (!rate) return
+  return decodedBytes / rate * 1000
+}
+
+module.exports = {
+  bytesPerSecond,
+  g711ToPcm16,
+  g711Variant,
+  isPcm16AudioMime,
+  pcm16ToWav,
+  realtimeAudioFormatToMime,
+  segmentDurationMs,
+}

package/packages/dd-trace/src/llmobs/audio-utils.js

@@ -0,0 +1,121 @@
+'use strict'
+
+// Building `audioPart`s for LLM Observability messages: mapping provider audio formats to MIME
+// types, and keeping inline audio within the per-span-event size budget. The raw-audio primitives
+// these build on (WAV wrapping, G.711 decoding, byte rates) live in `audio-codec.js`.
+
+const log = require('../log')
+const { LLMOBS_AUDIO_INLINE_MAX_BYTES } = require('./constants/audio')
+
+/**
+ * @typedef {{ mimeType: string, content: string }} AudioPart
+ */
+
+// Raw audio formats the UI cannot render as a player. For these we keep the transcript as the
+// message content and skip the inline audio part, since raw bytes would only bloat the payload.
+const NON_RENDERABLE_AUDIO_MIME_TYPES = new Set([
+  'audio/pcm',
+  'audio/pcm16',
+  'audio/l16',
+  'audio/pcmu',
+  'audio/pcma',
+  'audio/g711_ulaw',
+  'audio/g711_alaw',
+  'audio/basic',
+])
+
+/**
+ * Length of `byteLength` bytes after standard base64 encoding: 4 characters per 3 bytes, padded.
+ *
+ * @param {number} byteLength
+ */
+function base64EncodedLength (byteLength) {
+  return Math.ceil(byteLength / 3) * 4
+}
+
+// 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]
+ */
+function audioMimeTypeFromFormat (fmt, mimeTypeLookup = {}) {
+  fmt = typeof fmt === 'string' ? fmt.trim().toLowerCase() : ''
+  if (!fmt) return 'audio/wav'
+  // `hasOwn` rather than a plain lookup: a format of "constructor" would otherwise resolve to
+  // something off Object.prototype and be returned as the MIME type.
+  return Object.hasOwn(mimeTypeLookup, fmt) ? mimeTypeLookup[fmt] : `audio/${fmt}`
+}
+
+/**
+ * Whether a MIME type can be rendered as an audio player in the UI. Raw PCM cannot.
+ *
+ * @param {string} mimeType
+ */
+function isRenderableAudioMime (mimeType) {
+  return typeof mimeType === 'string' &&
+    mimeType.length > 0 &&
+    !NON_RENDERABLE_AUDIO_MIME_TYPES.has(mimeType.trim().toLowerCase())
+}
+
+// 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 {AudioPart}
+ */
+function formatAudioPart (data, mimeType) {
+  const content = Buffer.isBuffer(data) || ArrayBuffer.isView(data)
+    ? Buffer.from(data).toString('base64')
+    : data
+  return { mimeType, content }
+}
+
+/**
+ * Whether `byteLength` bytes of audio fit the inline budget once base64-encoded.
+ *
+ * Compares the *encoded* size: `formatAudioPart` base64-encodes the bytes (~4/3 expansion), and it
+ * is that encoded content which counts against the per-span-event limit. Exposed separately so a
+ * caller that has to allocate to produce those bytes — decoding G.711 to PCM16, wrapping raw PCM in
+ * a WAV container — can check the size it is about to produce before paying for it.
+ *
+ * @param {number} byteLength
+ * @param {number} [maxBytes]
+ */
+function fitsInlineAudioBudget (byteLength, maxBytes = LLMOBS_AUDIO_INLINE_MAX_BYTES) {
+  const encodedLength = base64EncodedLength(byteLength)
+  if (encodedLength <= maxBytes) return true
+
+  log.debug('Audio (%d encoded bytes) exceeds inline budget %d; omitting inline audio content',
+    encodedLength, maxBytes)
+  return false
+}
+
+/**
+ * Build a playable audio part, but only for renderable formats within the size budget. Returns
+ * `undefined` for a non-renderable format (e.g. raw PCM) or oversize audio; callers fall back to the
+ * transcript as the message content in that case.
+ *
+ * @param {Buffer} audioBytes
+ * @param {string} mimeType
+ * @param {number} [maxBytes]
+ * @returns {AudioPart | undefined}
+ */
+function formatAudioPartWithGuard (audioBytes, mimeType, maxBytes = LLMOBS_AUDIO_INLINE_MAX_BYTES) {
+  if (!audioBytes?.length || !isRenderableAudioMime(mimeType)) return
+  if (!fitsInlineAudioBudget(audioBytes.length, maxBytes)) return
+
+  return formatAudioPart(audioBytes, mimeType)
+}
+
+module.exports = {
+  audioMimeTypeFromFormat,
+  fitsInlineAudioBudget,
+  formatAudioPart,
+  formatAudioPartWithGuard,
+  isRenderableAudioMime,
+}

package/packages/dd-trace/src/llmobs/constants/audio.js

@@ -0,0 +1,35 @@
+'use strict'
+
+module.exports = {
+  // Surfaced as a message's content when audio was captured but couldn't be turned into a playable
+  // part (unsupported format, or over the size budget) and there is no transcript to show instead.
+  AUDIO_FALLBACK: '[audio]',
+
+  // G.711 telephony audio is always 8 kHz mono.
+  G711_SAMPLE_RATE: 8000,
+
+  // Budget for inline audio, measured on the *base64-encoded* size, since that is what actually
+  // rides the span event. Kept below the 5 MB per-span-event limit with headroom for the rest of the
+  // event, whose whole I/O is dropped backend-side when oversize. 4 MiB encoded is ~3 MiB of audio.
+  //
+  // Per *event*, not per audio part. An event carrying audio on more than one message — a realtime
+  // turn has both the user's and the agent's — has to divide this between them, or two individually
+  // accepted clips sum past the limit and cost the event all of its I/O.
+  LLMOBS_AUDIO_INLINE_MAX_BYTES: 4 * 1024 * 1024,
+
+  // Cap on the raw audio buffered per side of a realtime turn: the point at which base64 encoding
+  // would put a 1:1 format over `LLMOBS_AUDIO_INLINE_MAX_BYTES` anyway (4 chars per 3 bytes).
+  // Beyond this the size guard would drop the audio at tag time, so we stop retaining it rather
+  // than hold megabytes in memory only to discard them. A memory bound, not a correctness one — the
+  // guard still decides.
+  //
+  // A format that expands on the way to a playable part inlines less than this: G.711 decodes to
+  // PCM16 at 2 bytes per sample, so only about half of it can ever ride the span event. Callers
+  // check the *converted* size against the budget before converting (`fitsInlineAudioBudget`), so
+  // the excess is never paid for in allocations — it is only retained and then dropped.
+  LLMOBS_AUDIO_ACCUMULATE_MAX_BYTES: 3 * 1024 * 1024,
+
+  PCM16_BYTES_PER_SAMPLE: 2,
+
+  WAV_HEADER_BYTES: 44,
+}

package/packages/dd-trace/src/llmobs/constants/prompts.js

@@ -0,0 +1,14 @@
+'use strict'
+
+module.exports = {
+  ERROR_NAMES: {
+    API: 'PromptAPIError',
+    AUTH: 'PromptAuthError',
+    CONFLICT: 'PromptConflictError',
+    NOT_FOUND: 'PromptNotFoundError',
+    SERVER: 'PromptServerError',
+    VALIDATION: 'PromptValidationError',
+  },
+  PROMPTS_PATH: '/api/unstable/llm-obs/v1/prompts',
+  SOURCE_CACHE: 'cache',
+}

package/packages/dd-trace/src/llmobs/constants/tags.js

@@ -69,6 +69,23 @@ module.exports = {
   INSTRUMENTATION_METHOD_ANNOTATED: 'annotated',
   INSTRUMENTATION_METHOD_UNKNOWN: 'unknown',
 
+  GEN_AI_OPERATION_NAME: 'gen_ai.operation.name',
+  GEN_AI_REQUEST_MODEL: 'gen_ai.request.model',
+  GEN_AI_PROVIDER_NAME: 'gen_ai.provider.name',
+  GEN_AI_APPLICATION_NAME: 'gen_ai.application.name',
+  GEN_AI_CONVERSATION_ID: 'gen_ai.conversation.id',
+
+  GEN_AI_USAGE_INPUT_TOKENS_METRIC_KEY: 'gen_ai.usage.input_tokens',
+  GEN_AI_USAGE_OUTPUT_TOKENS_METRIC_KEY: 'gen_ai.usage.output_tokens',
+  GEN_AI_USAGE_TOTAL_TOKENS_METRIC_KEY: 'gen_ai.usage.total_tokens',
+  GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_METRIC_KEY: 'gen_ai.usage.cache_read_input_tokens',
+  GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS_METRIC_KEY: 'gen_ai.usage.cache_write_input_tokens',
+  GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_METRIC_KEY: 'gen_ai.usage.reasoning_output_tokens',
+
+  // Marks the `gen_ai.*` tags on an APM span as tracer-emitted. Without it the backend reads them
+  // as user-set and builds a duplicate LLMObs span out of the APM span.
+  ARTIFICIAL_GEN_AI_TAGS: '_dd.llmobs.artificial_gen_ai_tags',
+
   ROUTING_API_KEY: '_dd.llmobs.routing.api_key',
   ROUTING_SITE: '_dd.llmobs.routing.site',
 }

package/packages/dd-trace/src/llmobs/eval-metric.js

@@ -61,7 +61,6 @@ const TERMS = {
 
 /**
  * @param {string[]} metricTypes
- * @returns {string} the quoted list, e.g. `"categorical", "score" or "json"`
  */
 function formatMetricTypes (metricTypes) {
   const quoted = metricTypes.map(metricType => `"${metricType}"`)
@@ -99,7 +98,6 @@ function invalidTagsError (kind) {
 /**
  * @param {unknown} timestampMs
  * @param {MetricEventKind} kind
- * @returns {void}
  */
 function validateTimestamp (timestampMs, kind) {
   if (typeof timestampMs !== 'number' || timestampMs < 0) {
@@ -137,7 +135,6 @@ function validateLabel (label, kind) {
 /**
  * @param {string | undefined} metricType - Already lower-cased metric type.
  * @param {MetricEventKind} kind
- * @returns {void}
  */
 function validateMetricType (metricType, kind) {
   if (!metricType || !METRIC_TYPES[kind].includes(metricType)) {
@@ -148,7 +145,6 @@ function validateMetricType (metricType, kind) {
 /**
  * @param {string | undefined} metricType - Metric type already validated for the submitted kind.
  * @param {unknown} value
- * @returns {void}
  */
 function validateMetricValue (metricType, value) {
   if (metricType === 'categorical' && typeof value !== 'string') {
@@ -170,7 +166,6 @@ function validateMetricValue (metricType, value) {
 
 /**
  * @param {unknown} assessment
- * @returns {void}
  */
 function validateAssessment (assessment) {
   if (assessment != null && assessment !== 'pass' && assessment !== 'fail') {
@@ -180,7 +175,6 @@ function validateAssessment (assessment) {
 
 /**
  * @param {unknown} reasoning
- * @returns {void}
  */
 function validateReasoning (reasoning) {
   if (reasoning != null && typeof reasoning !== 'string') {