dd-trace 6.16.0 → 6.18.0

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') {

package/packages/dd-trace/src/llmobs/experiments/dataset.js

@@ -330,7 +330,6 @@ class Dataset {
    * @param {string} recordId Dataset record id.
    * @param {'add' | 'remove' | 'replace'} operation Tag operation to queue.
    * @param {string[]} tags Tags in key:value format.
-   * @returns {void}
    */
   #queueTagOperation (recordId, operation, tags) {
     if (operation !== 'replace' && tags.length === 0) return
@@ -503,7 +502,6 @@ class Dataset {
    * Detach tag changes sent by this batch so edits made while the request is in flight
    * are queued relative to the response that this batch will commit.
    * @param {PendingBatch} pending
-   * @returns {void}
    */
   #detachCommittedTagOperations (pending) {
     pending.inFlightTagOperations = new Map()
@@ -527,7 +525,6 @@ class Dataset {
   /**
    * Restore tag changes when a batch request fails, including edits made while it was in flight.
    * @param {PendingBatch} pending
-   * @returns {void}
    */
   #restoreFailedTagOperations (pending) {
     if (!pending.inFlightTagOperations) return
@@ -549,7 +546,6 @@ class Dataset {
   /**
    * Clear the changes represented by a completed batch while retaining concurrent local edits.
    * @param {PendingBatch} pending
-   * @returns {void}
    */
   #clearCommittedChanges (pending) {
     for (const [recordId, payload] of pending.insertPayloads) {

package/packages/dd-trace/src/llmobs/experiments/experiment.js

@@ -1015,9 +1015,6 @@ class ExternalExperiment {
     this.#experiment = experiment
   }
 
-  /**
-   * @returns {string}
-   */
   name () {
     return this.#experiment.name()
   }

package/packages/dd-trace/src/llmobs/experiments/index.js

@@ -35,8 +35,8 @@ class Experiments {
 
   constructor (config, llmobs) {
     this.#config = config
-    this.#llmobs = config.llmobs?.mlApp || config.service ? llmobs : undefined
-    this.#projectName = config.llmobs?.projectName || DEFAULT_PROJECT_NAME
+    this.#llmobs = config.llmobs?.DD_LLMOBS_ML_APP || config.service ? llmobs : undefined
+    this.#projectName = config.llmobs?.DD_LLMOBS_PROJECT_NAME || DEFAULT_PROJECT_NAME
     this.#client = this.#clientForProject(this.#projectName)
   }
 
@@ -179,9 +179,9 @@ class Experiments {
     const projectName = options?.projectName ?? datasetProjectName
     const client = this.#clientForOperation(projectName)
     const usesDatasetOverride = datasetProjectName !== undefined && datasetProjectName !== this.#projectName
-    const resolvedProjectName = projectName ?? this.#config.llmobs?.projectName
+    const resolvedProjectName = projectName ?? this.#config.llmobs?.DD_LLMOBS_PROJECT_NAME
     const experimentOptions = options?.projectName === undefined &&
-      (usesDatasetOverride || this.#config.llmobs?.projectName !== undefined) &&
+      (usesDatasetOverride || this.#config.llmobs?.DD_LLMOBS_PROJECT_NAME !== undefined) &&
       resolvedProjectName !== undefined
       ? { ...options, projectName: resolvedProjectName }
       : options
@@ -198,8 +198,9 @@ class Experiments {
    */
   startExperiment (options) {
     const client = this.#clientForOperation(options?.projectName)
-    const experimentOptions = options?.projectName === undefined && this.#config.llmobs?.projectName !== undefined
-      ? { ...options, projectName: this.#config.llmobs.projectName }
+    const experimentOptions = options?.projectName === undefined &&
+      this.#config.llmobs?.DD_LLMOBS_PROJECT_NAME !== undefined
+      ? { ...options, projectName: this.#config.llmobs.DD_LLMOBS_PROJECT_NAME }
       : options
     return new Experiment(client, { ...experimentOptions, external: true }).start()
       .then(experiment => new ExternalExperiment(experiment))

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

@@ -14,7 +14,6 @@ const EVALUATOR_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/
 
 /**
  * @param {object | null | undefined} value
- * @returns {boolean}
  */
 function hasEntries (value) {
   if (!value) return false
@@ -47,16 +46,12 @@ function tagOperationsAreEmpty (operations) {
 /**
  * @param {unknown} value
  * @param {string} name
- * @returns {number}
  */
 function normalizePositiveInteger (value, name) {
   if (!Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer`)
-  return value
+  return /** @type {number} */ (value)
 }
 
-/**
- * @returns {string}
- */
 function generateRunId () {
   return randomUUID()
 }
@@ -77,7 +72,6 @@ function validateEvaluatorName (name) {
 /**
  * @param {(...args: unknown[]) => unknown} fn
  * @param {string} fallback
- * @returns {string}
  */
 function functionName (fn, fallback) {
   return typeof fn.name === 'string' && fn.name.length > 0 ? fn.name : fallback
@@ -124,7 +118,6 @@ function normalizeEvaluators (evaluators, kind) {
 
 /**
  * @param {unknown} value
- * @returns {string}
  */
 function inferMetricType (value) {
   if (typeof value === 'boolean') return 'boolean'
@@ -184,7 +177,6 @@ function normalizeJsonMetricValue (value) {
 
 /**
  * @param {unknown} value
- * @returns {string}
  */
 function stringify (value) {
   if (value == null) return ''
@@ -270,7 +262,6 @@ function sleep (ms) {
 /**
  * @param {unknown} value
  * @param {number} fallback
- * @returns {number}
  */
 function timestampMs (value, fallback = Date.now()) {
   if (value === null || value === undefined) return fallback
@@ -286,7 +277,6 @@ function timestampMs (value, fallback = Date.now()) {
 /**
  * @param {{ durationMs?: unknown, completedAt?: unknown }} row
  * @param {number} startMs
- * @returns {number}
  */
 function durationNs (row, startMs) {
   if (typeof row.durationMs === 'number' && Number.isFinite(row.durationMs)) {

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

@@ -152,7 +152,6 @@ function disable () {
  * Keeps retired writers reachable until their destroy-triggered deliveries complete.
  * @param {LLMObsSpanWriter | null} retiredSpanWriter
  * @param {LLMObsEvalMetricsWriter | null} retiredEvalWriter
- * @returns {void}
  */
 function retireWriters (retiredSpanWriter, retiredEvalWriter) {
   const retiredWriters = [retiredSpanWriter, retiredEvalWriter].filter(Boolean)
@@ -183,7 +182,7 @@ function handleLLMObsInjection (injection) {
   const mlApp =
     mlObsSpanTags?.[ML_APP] ||
     parentContext?._trace?.tags?.[PROPAGATED_ML_APP_KEY] ||
-    globalTracerConfig.llmobs.mlApp
+    globalTracerConfig.llmobs.DD_LLMOBS_ML_APP
 
   const sampleRate =
     mlObsSpanTags?.[SAMPLE_RATE] ?? parentContext?._trace?.tags?.[PROPAGATED_SAMPLE_RATE_KEY]
@@ -239,7 +238,6 @@ function handleLLMObsInjection (injection) {
  * @param {Function} [done]
  * @param {LLMObsSpanWriter | null} [currentSpanWriter]
  * @param {LLMObsEvalMetricsWriter | null} [currentEvalWriter]
- * @returns {boolean} `true` when a writer throws synchronously.
  */
 function flushWriters (done, currentSpanWriter = spanWriter, currentEvalWriter = evalWriter) {
   let failed = false

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

@@ -1,5 +1,7 @@
 'use strict'
 
+const NoopPrompts = require('./prompts/noop')
+
 let NoopExperiments
 
 class NoopLLMObs {
@@ -16,6 +18,14 @@ class NoopLLMObs {
     return new NoopExperiments('LLM Observability is not enabled')
   }
 
+  /**
+   * Prompt Management API.
+   * @returns {import('../../../../index').llmobs.Prompts}
+   */
+  get prompts () {
+    return new NoopPrompts()
+  }
+
   enable (options) {}
 
   disable () {}

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

@@ -337,7 +337,6 @@ function getToolNameFromTags (tags) {
 
 /**
  * @param {unknown} value
- * @returns {string}
  */
 function stringifyToolCallResult (value) {
   return JSON.stringify(value) ?? UNPARSABLE_TOOL_RESULT
@@ -345,7 +344,6 @@ function stringifyToolCallResult (value) {
 
 /**
  * @param {ToolCallContentPart[]} value
- * @returns {string}
  */
 function formatToolCallContent (value) {
   if (!Array.isArray(value)) return UNPARSABLE_TOOL_RESULT
@@ -388,7 +386,6 @@ function formatToolCallContent (value) {
 
 /**
  * @param {ToolCallResultContent | null | undefined} content
- * @returns {string}
  */
 function getToolCallResultContent (content) {
   try {
@@ -426,7 +423,6 @@ function getToolCallResultContent (content) {
  * Computes the LLM Observability `ai` span name
  * @param {string} operation
  * @param {string} functionId
- * @returns {string}
  */
 function getLlmObsSpanName (operation, functionId) {
   return functionId ? `${functionId}.${operation}` : operation

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

@@ -62,7 +62,6 @@ function formatAnthropicToolResultContent (content) {
  *
  * @param {AnthropicLlmObsMessage[]} messages
  * @param {{ role: string, content: string | Array<TextBlock | ImageBlock | ToolUseBlock | ToolResultBlock> }} message
- * @returns {void}
  */
 function appendMessage (messages, { role, content }) {
   if (typeof content === 'string') {