dd-trace 5.86.0 → 5.87.0

package/packages/dd-trace/src/debugger/devtools_client/index.js

@@ -6,7 +6,7 @@ const { NODE_MAJOR } = require('../../../../../version')
 const processTags = require('../../process-tags')
 const { breakpointToProbes } = require('./state')
 const session = require('./session')
-const { getLocalStateForCallFrame } = require('./snapshot')
+const { getLocalStateForCallFrame, evaluateCaptureExpressions } = require('./snapshot')
 const send = require('./send')
 const { getStackFromCallFrames } = require('./state')
 const { ackEmitting } = require('./status')
@@ -67,9 +67,13 @@ session.on('Debugger.paused', async ({ params }) => {
     throw new Error(`Unexpected Debugger.paused reason: ${params.reason}`)
   }
 
-  let maxReferenceDepth, maxCollectionSize, maxFieldCount, maxLength
+  let maxReferenceDepth = 0
+  let maxCollectionSize = 0
+  let maxFieldCount = 0
+  let maxLength = 0
   let sampled = false
   let numberOfProbesWithSnapshots = 0
+  let probesWithCaptureExpressions = false
   const probes = []
   let templateExpressions = ''
 
@@ -104,7 +108,7 @@ session.on('Debugger.paused', async ({ params }) => {
         continue
       }
 
-      if (probe.captureSnapshot === true) {
+      if (probe.captureSnapshot === true || probe.compiledCaptureExpressions !== undefined) {
         // This algorithm to calculate number of sampled snapshots within the last second is not perfect, as it's not a
         // sliding window. But it's quick and easy :)
         if (i === 0 && start - globalSnapshotSamplingRateWindowStart > oneSecondNs) {
@@ -116,11 +120,15 @@ session.on('Debugger.paused', async ({ params }) => {
           snapshotsSampledWithinTheLastSecond++
         }
 
-        snapshotProbeIndex[numberOfProbesWithSnapshots++] = probes.length
-        maxReferenceDepth = highestOrUndefined(probe.capture?.maxReferenceDepth, maxReferenceDepth)
-        maxCollectionSize = highestOrUndefined(probe.capture?.maxCollectionSize, maxCollectionSize)
-        maxFieldCount = highestOrUndefined(probe.capture?.maxFieldCount, maxFieldCount)
-        maxLength = highestOrUndefined(probe.capture?.maxLength, maxLength)
+        if (probe.captureSnapshot === true) {
+          snapshotProbeIndex[numberOfProbesWithSnapshots++] = probes.length
+          maxReferenceDepth = Math.max(probe.capture.maxReferenceDepth, maxReferenceDepth)
+          maxCollectionSize = Math.max(probe.capture.maxCollectionSize, maxCollectionSize)
+          maxFieldCount = Math.max(probe.capture.maxFieldCount, maxFieldCount)
+          maxLength = Math.max(probe.capture.maxLength, maxLength)
+        } else {
+          probesWithCaptureExpressions = true
+        }
       }
 
       if (probe.condition !== undefined) {
@@ -173,16 +181,32 @@ session.on('Debugger.paused', async ({ params }) => {
   }
 
   // TODO: Create unique states for each affected probe based on that probes unique `capture` settings (DEBUG-2863)
-  let processLocalState, captureErrors
+  let processLocalState
+  /** @type {Error[] | undefined} */
+  let fatalSnapshotErrors
   if (numberOfProbesWithSnapshots !== 0) {
-    const opts = {
-      maxReferenceDepth,
-      maxCollectionSize,
-      maxFieldCount,
-      maxLength,
-      deadlineNs: start + config.dynamicInstrumentation.captureTimeoutNs,
+    const result = await getLocalStateForCallFrame(
+      params.callFrames[0],
+      { maxReferenceDepth, maxCollectionSize, maxFieldCount, maxLength },
+      start + config.dynamicInstrumentation.captureTimeoutNs
+    )
+    processLocalState = result.processLocalState
+    fatalSnapshotErrors = result.fatalErrors
+  }
+
+  // Evaluate capture expressions for probes that have them
+  let captureExpressionResults = null
+  if (probesWithCaptureExpressions === true) {
+    captureExpressionResults = new Map()
+    for (const probe of probes) {
+      if (probe.compiledCaptureExpressions === undefined) continue
+      // eslint-disable-next-line no-await-in-loop
+      captureExpressionResults.set(probe.id, await evaluateCaptureExpressions(
+        params.callFrames[0],
+        probe.compiledCaptureExpressions,
+        start + config.dynamicInstrumentation.captureTimeoutNs
+      ))
     }
-    ;({ processLocalState, captureErrors } = await getLocalStateForCallFrame(params.callFrames[0], opts))
   }
 
   await session.post('Debugger.resume')
@@ -228,16 +252,48 @@ session.on('Debugger.paused', async ({ params }) => {
     }
 
     if (probe.captureSnapshot) {
-      if (captureErrors?.length > 0) {
+      if (fatalSnapshotErrors && fatalSnapshotErrors.length > 0) {
         // There was an error collecting the snapshot for this probe, let's not try again
         probe.captureSnapshot = false
-        probe.permanentEvaluationErrors = captureErrors.map(error => ({
+        probe.permanentEvaluationErrors = fatalSnapshotErrors.map(error => ({
           expr: '',
           message: error.message,
         }))
       }
       snapshot.captures = {
-        lines: { [probe.location.lines[0]]: { locals: processLocalState() } },
+        lines: { [probe.location.lines[0]]: { locals: /** @type {Function} */ (processLocalState)() } },
+      }
+    } else if (probe.compiledCaptureExpressions !== undefined) {
+      const expressionResult = /** @type {Map} */ (captureExpressionResults).get(probe.id)
+      if (expressionResult) {
+        // Handle fatal capture errors - disable capture expressions for this probe permanently
+        if (expressionResult.fatalErrors?.length > 0) {
+          probe.compiledCaptureExpressions = undefined
+          probe.permanentEvaluationErrors = expressionResult.fatalErrors.map(error => ({
+            expr: '',
+            message: error.message,
+          }))
+        }
+
+        snapshot.captures = {
+          lines: { [probe.location.lines[0]]: { captureExpressions: expressionResult.processCaptureExpressions() } },
+        }
+
+        // Handle transient evaluation errors - include in snapshot for this capture
+        if (expressionResult.evaluationErrors?.length > 0) {
+          if (snapshot.evaluationErrors === undefined) {
+            snapshot.evaluationErrors = expressionResult.evaluationErrors
+          } else {
+            snapshot.evaluationErrors.push(...expressionResult.evaluationErrors)
+          }
+        }
+      } else {
+        log.error('[debugger:devtools_client] Missing capture expression results for probe %s (version: %s)',
+          probe.id, probe.version)
+        snapshot.evaluationErrors = [{
+          expr: '',
+          message: 'Internal error: capture expression results not found',
+        }]
       }
     }
 
@@ -275,10 +331,6 @@ session.on('Debugger.paused', async ({ params }) => {
   }
 })
 
-function highestOrUndefined (num, max) {
-  return num === undefined ? max : Math.max(num, max ?? 0)
-}
-
 function processDD (result) {
   return result?.trace_id === undefined ? undefined : result
 }

package/packages/dd-trace/src/debugger/devtools_client/remote_config.js

@@ -5,7 +5,7 @@ const { addBreakpoint, removeBreakpoint, modifyBreakpoint } = require('./breakpo
 const { ackReceived, ackInstalled, ackError } = require('./status')
 const log = require('./log')
 
-// Example log line probe (simplified):
+// Example log line probe with captureSnapshot (simplified):
 // {
 //   id: '100c9a5c-45ad-49dc-818b-c570d31e11d1',
 //   version: 0,
@@ -19,6 +19,23 @@ const log = require('./log')
 //   evaluateAt: 'EXIT' // only used for method probes
 // }
 //
+// Example log line probe with captureExpressions (simplified):
+// Note: captureSnapshot and captureExpressions are mutually exclusive
+// {
+//   id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+//   version: 0,
+//   type: 'LOG_PROBE',
+//   where: { sourceFile: 'index.js', lines: ['25'] },
+//   template: 'Captured expressions',
+//   segments: [{ str: 'Captured expressions' }],
+//   captureExpressions: [
+//     { name: 'myVar', expr: { dsl: 'myVar', json: { ref: 'myVar' } }, capture: { maxReferenceDepth: 2 } },
+//     { name: 'obj.foo', expr: { dsl: 'obj.foo', json: { getmember: [{ ref: 'obj' }, 'foo'] } } }
+//   ],
+//   capture: { maxReferenceDepth: 3 }, // default limits for expressions without explicit capture
+//   sampling: { snapshotsPerSecond: 1 }
+// }
+//
 // Example log method probe (simplified):
 // {
 //   id: 'd692ee6d-5734-4df7-9d86-e3bc6449cc8c',
@@ -63,6 +80,11 @@ async function processMsg (action, probe) {
       `Unsupported probe insertion point! Only line-based probes are supported (id: ${probe.id}, version: ${probe.version})`
     )
   }
+  if (probe.captureSnapshot && probe.captureExpressions?.length > 0) {
+    throw new Error(
+      `Cannot set both captureSnapshot and captureExpressions (probe: ${probe.id}, version: ${probe.version})`
+    )
+  }
 
   switch (action) {
     case 'unapply':

package/packages/dd-trace/src/debugger/devtools_client/snapshot/collector.js

@@ -56,13 +56,13 @@ module.exports = {
 
 /**
  * @typedef {object} GetObjectOptions
- * @property {object} maxReferenceDepth - The maximum depth of the object to traverse
+ * @property {number} maxReferenceDepth - The maximum depth of the object to traverse
  * @property {number} maxCollectionSize - The maximum size of a collection to include in the snapshot
  * @property {number} maxFieldCount - The maximum number of properties on an object to include in the snapshot
  * @property {bigint} deadlineNs - The deadline in nanoseconds compared to `process.hrtime.bigint()`
  * @property {object} ctx - A context object to track the state/progress of the snapshot collection.
  * @property {boolean} ctx.deadlineReached - Will be set to `true` if the deadline has been reached.
- * @property {Error[]} ctx.captureErrors - An array on which errors can be pushed if an issue is detected while
+ * @property {Error[]} ctx.fatalErrors - An array on which errors can be pushed if an issue is detected while
  *   collecting the snapshot.
  */
 
@@ -99,7 +99,7 @@ async function collectObjectProperties (objectId, opts, depth = 0, collection =
     // Trim the number of properties on the object if there's too many.
     const size = result.length
     if (size > LARGE_OBJECT_SKIP_THRESHOLD) {
-      opts.ctx.captureErrors.push(new Error(
+      opts.ctx.fatalErrors.push(new Error(
         `An object with ${size} properties was detected while collecting a snapshot. ` +
         `This exceeds the maximum number of allowed properties of ${LARGE_OBJECT_SKIP_THRESHOLD}. ` +
         'Future snapshots for existing probes in this location will be skipped until the Node.js process is restarted'

package/packages/dd-trace/src/debugger/devtools_client/snapshot/index.js

@@ -1,55 +1,41 @@
 'use strict'
 
-const {
-  DEFAULT_MAX_REFERENCE_DEPTH,
-  DEFAULT_MAX_COLLECTION_SIZE,
-  DEFAULT_MAX_FIELD_COUNT,
-  DEFAULT_MAX_LENGTH,
-} = require('./constants')
+const session = require('../session')
 const { collectObjectProperties } = require('./collector')
-const { processRawState } = require('./processor')
+const { processRawState, processRemoteObject } = require('./processor')
 
 const BIGINT_MAX = (1n << 256n) - 1n
 
 module.exports = {
   getLocalStateForCallFrame,
+  evaluateCaptureExpressions,
 }
 
 /**
- * @typedef {object} GetLocalStateForCallFrameOptions
- * @property {number} [maxReferenceDepth] - The maximum depth of the object to traverse. Defaults to
- *   {@link DEFAULT_MAX_REFERENCE_DEPTH}.
- * @property {number} [maxCollectionSize] - The maximum size of a collection to include in the snapshot. Defaults to
- *   {@link DEFAULT_MAX_COLLECTION_SIZE}.
- * @property {number} [maxFieldCount] - The maximum number of properties on an object to include in the snapshot.
- *   Defaults to {@link DEFAULT_MAX_FIELD_COUNT}.
- * @property {number} [maxLength] - The maximum length of a string to include in the snapshot. Defaults to
- *   {@link DEFAULT_MAX_LENGTH}.
- * @property {bigint} [deadlineNs] - The deadline in nanoseconds compared to `process.hrtime.bigint()`. Defaults to
- *   {@link BIGINT_MAX}. If the deadline is reached, the snapshot will be truncated.
+ * @typedef {object} CaptureLimits - Fully resolved capture limits (all fallbacks already applied)
+ * @property {number} maxReferenceDepth - The maximum depth of the object to traverse
+ * @property {number} maxCollectionSize - The maximum size of a collection to include in the snapshot
+ * @property {number} maxFieldCount - The maximum number of properties on an object to include in the snapshot
+ * @property {number} maxLength - The maximum length of a string to include in the snapshot
  */
 
 /**
  * Get the local state for a call frame.
  *
  * @param {import('inspector').Debugger.CallFrame} callFrame - The call frame to get the local state for
- * @param {GetLocalStateForCallFrameOptions} [opts] - The options for the snapshot
- * @returns {Promise<object>} The local state for the call frame
+ * @param {CaptureLimits} limits - The capture limits
+ * @param {bigint} [deadlineNs] - The deadline in nanoseconds compared to `process.hrtime.bigint()`. Defaults to
+ *   {@link BIGINT_MAX}. If the deadline is reached, the snapshot will be truncated.
+ * @returns {Promise<{ processLocalState: () => ReturnType<typeof processRawState>, fatalErrors: Error[] }>} The local
+ *   state for the call frame
  */
-async function getLocalStateForCallFrame (
-  callFrame,
-  {
-    maxReferenceDepth = DEFAULT_MAX_REFERENCE_DEPTH,
-    maxCollectionSize = DEFAULT_MAX_COLLECTION_SIZE,
-    maxFieldCount = DEFAULT_MAX_FIELD_COUNT,
-    maxLength = DEFAULT_MAX_LENGTH,
-    deadlineNs = BIGINT_MAX,
-  } = {}
-) {
-  /** @type {{ deadlineReached: boolean, captureErrors: Error[] }} */
-  const ctx = { deadlineReached: false, captureErrors: [] }
+async function getLocalStateForCallFrame (callFrame, limits, deadlineNs = BIGINT_MAX) {
+  const { maxReferenceDepth, maxCollectionSize, maxFieldCount, maxLength } = limits
+  /** @type {{ deadlineReached: boolean, fatalErrors: Error[] }} */
+  const ctx = { deadlineReached: false, fatalErrors: [] }
   const opts = { maxReferenceDepth, maxCollectionSize, maxFieldCount, deadlineNs, ctx }
   const rawState = []
+  /** @type {ReturnType<typeof processRawState> | null} */
   let processedState = null
 
   for (const scope of callFrame.scopeChain) {
@@ -63,21 +49,167 @@ async function getLocalStateForCallFrame (
       // eslint-disable-next-line no-await-in-loop
       rawState.push(...await collectObjectProperties(objectId, opts))
     } catch (err) {
-      ctx.captureErrors.push(new Error(
+      ctx.fatalErrors.push(new Error(
         `Error getting local state for closure scope (type: ${scope.type}). ` +
-        'Future snapshots for existing probes in this location will be skipped until the Node.js process is restarted',
+        'Future snapshots for existing probes in this location will be skipped until the probes are re-applied',
         { cause: err } // TODO: The cause is not used by the backend
       ))
     }
     if (ctx.deadlineReached === true) break // TODO: Bad UX; Variables in remaining scopes are silently dropped
   }
 
-  // Delay calling `processRawState` so the caller gets a chance to resume the main thread before processing `rawState`
+  // Delay calling `processRawState` so caller can resume the main thread before processing `rawState`
   return {
     processLocalState () {
       processedState = processedState ?? processRawState(rawState, maxLength)
       return processedState
     },
-    captureErrors: ctx.captureErrors,
+    fatalErrors: ctx.fatalErrors,
+  }
+}
+
+/**
+ * @typedef {object} CompiledCaptureExpression
+ * @property {string} name - The name of the expression (used as key in snapshot)
+ * @property {string} expression - The compiled expression string to evaluate
+ * @property {CaptureLimits} limits - Fully resolved capture limits (precomputed at probe setup)
+ */
+
+/**
+ * @typedef {object} CaptureExpressionResult
+ * @property {() => Record<string, ReturnType<typeof processRemoteObject>>} processCaptureExpressions - Callback to
+ *   process raw data into snapshot format
+ * @property {{ expr: string, message: string }[]} evaluationErrors - Transient errors from expression evaluation
+ *   (safe to retry)
+ * @property {Error[]} fatalErrors - Fatal errors that should disable capture expressions for this probe permanently
+ */
+
+/**
+ * @typedef {object} EvaluateOnCallFrameResult
+ * @property {import('./processor').RemoteObjectWithProperties} result - The result of the evaluation
+ * @property {import('inspector').Runtime.ExceptionDetails} [exceptionDetails] - Exception details if evaluation failed
+ */
+
+/**
+ * Evaluate capture expressions for a call frame.
+ *
+ * Collects raw data while paused, returns a callback to process after resume.
+ *
+ * @param {import('inspector').Debugger.CallFrame} callFrame - The call frame to evaluate expressions on
+ * @param {CompiledCaptureExpression[]} expressions - The compiled expressions with precomputed capture limits
+ * @param {bigint} [deadlineNs] - The deadline in nanoseconds. Defaults to {@link BIGINT_MAX}. If the deadline is
+ *   reached, the snapshot will be truncated.
+ * @returns {Promise<CaptureExpressionResult>} Raw results with deferred processing callback
+ */
+async function evaluateCaptureExpressions (callFrame, expressions, deadlineNs = BIGINT_MAX) {
+  /** @type {{ name: string, remoteObject: object, maxLength: number }[]} */
+  const rawResults = []
+  /** @type {{ expr: string, message: string }[]} */
+  const evaluationErrors = []
+  /** @type {Error[]} */
+  const fatalErrors = []
+  /** @type {Record<string, ReturnType<typeof processRemoteObject>> | null} */
+  let processedResult = null
+
+  for (let i = 0; i < expressions.length; i++) {
+    const { name, expression, limits } = expressions[i]
+    const { maxReferenceDepth, maxCollectionSize, maxFieldCount, maxLength } = limits
+
+    try {
+      const { result, exceptionDetails } = /** @type {EvaluateOnCallFrameResult} */ (
+        // eslint-disable-next-line no-await-in-loop
+        await session.post('Debugger.evaluateOnCallFrame', {
+          callFrameId: callFrame.callFrameId,
+          expression,
+        })
+      )
+
+      // Handle evaluation exceptions (maybe transient - bad expression, undefined var, etc.)
+      if (exceptionDetails) {
+        evaluationErrors.push({ expr: name, message: extractErrorMessage(exceptionDetails) })
+        continue
+      }
+
+      // Collect raw properties for objects/functions while still paused
+      if ((result.type === 'object' || result.type === 'function') && result.objectId && maxReferenceDepth > 0) {
+        const ctx = { deadlineReached: false, fatalErrors: [] }
+        const isCollection = result.subtype === 'array' || result.subtype === 'typedarray'
+
+        // eslint-disable-next-line no-await-in-loop
+        result.properties = await collectObjectProperties(
+          result.objectId,
+          {
+            // The expression result itself is depth 0, so we subtract 1 when collecting its properties (depth 1+)
+            maxReferenceDepth: maxReferenceDepth - 1,
+            maxCollectionSize,
+            maxFieldCount,
+            deadlineNs,
+            ctx,
+          },
+          0,
+          isCollection
+        )
+
+        // Propagate fatal errors from nested collection
+        if (ctx.fatalErrors.length > 0) {
+          fatalErrors.push(...ctx.fatalErrors)
+        }
+
+        if (ctx.deadlineReached === true) {
+          // Add the current expression (properties may be incomplete due to timeout)
+          rawResults.push({ name, remoteObject: result, maxLength })
+          // Add stub entries for remaining uncaptured expressions
+          for (let j = i + 1; j < expressions.length; j++) {
+            rawResults.push({
+              name: expressions[j].name,
+              remoteObject: { notCapturedReason: 'timeout' },
+              maxLength: 0,
+            })
+          }
+          break
+        }
+      }
+
+      rawResults.push({ name, remoteObject: result, maxLength })
+    } catch (err) {
+      fatalErrors.push(new Error(
+        `Error capturing expression "${name}". ` +
+        'Capture expressions for this probe will be skipped until the probe is re-applied',
+        { cause: err } // TODO: The cause is not used by the backend
+      ))
+    }
+  }
+
+  // Delay calling `processRemoteObject` so caller can resume the main thread before processing `remoteObject`
+  return {
+    processCaptureExpressions () {
+      if (processedResult !== null) return processedResult
+
+      processedResult = {}
+      for (const { name, remoteObject, maxLength } of rawResults) {
+        // If the remote object has notCapturedReason (e.g., timeout), use it as-is without processing
+        processedResult[name] = remoteObject.notCapturedReason === undefined
+          ? processRemoteObject(remoteObject, maxLength)
+          : remoteObject
+      }
+
+      return processedResult
+    },
+    evaluationErrors,
+    fatalErrors,
   }
 }
+
+/**
+ * Extract the error message from the exception details.
+ *
+ * @param {import('inspector').Runtime.ExceptionDetails} exceptionDetails - The exception details
+ * @returns {string} The error message
+ */
+function extractErrorMessage (exceptionDetails) {
+  const description = exceptionDetails.exception?.description
+  if (!description) return 'Unknown evaluation error'
+  const startOfStackTraceIndex = description.indexOf('\n    at ')
+  if (startOfStackTraceIndex === -1) return description
+  return description.slice(0, startOfStackTraceIndex)
+}

package/packages/dd-trace/src/debugger/devtools_client/snapshot/processor.js

@@ -6,6 +6,24 @@ const { normalizeName, REDACTED_IDENTIFIERS } = require('./redaction')
 
 module.exports = {
   processRawState: processProperties,
+  processRemoteObject,
+}
+
+/**
+ * A RemoteObject with collected properties attached.
+ *
+ * @typedef {import('inspector').Runtime.RemoteObject & { properties?: object[] }} RemoteObjectWithProperties
+ */
+
+/**
+ * Process a RemoteObject into the snapshot format.
+ *
+ * @param {RemoteObjectWithProperties} remoteObject
+ * @param {number} maxLength - Maximum string length
+ * @returns {object} The processed value in snapshot format
+ */
+function processRemoteObject (remoteObject, maxLength) {
+  return getPropertyValueRaw({ value: remoteObject }, maxLength)
 }
 
 // Matches classes in source code, no matter how it's written:

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

@@ -38,5 +38,5 @@ const HttpsAgent = createAgentClass(https.Agent)
 
 module.exports = {
   httpAgent: new HttpAgent(),
-  HttpsAgent: new HttpsAgent(),
+  httpsAgent: new HttpsAgent(),
 }

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

@@ -10,7 +10,7 @@ module.exports = {
 
   EVALUATIONS_INTAKE: 'api',
   EVALUATIONS_EVENT_TYPE: 'evaluation_metric',
-  EVALUATIONS_ENDPOINT: '/api/intake/llm-obs/v1/eval-metric',
+  EVALUATIONS_ENDPOINT: '/api/intake/llm-obs/v2/eval-metric',
 
   EVP_PAYLOAD_SIZE_LIMIT: 5 << 20, // 5MB (actual limit is 5.1MB)
   EVP_EVENT_SIZE_LIMIT: (1 << 20) - 1024, // 999KB (actual limit is 1MB)

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

@@ -359,15 +359,15 @@ class LLMObs extends NoopLLMObs {
         throw new Error('timestampMs must be a non-negative integer. Evaluation metric data will not be sent')
       }
 
-      const { label, value, tags } = options
+      const { label, value, tags, reasoning, assessment, metadata } = options
       const metricType = options.metricType?.toLowerCase()
       if (!label) {
         err = 'invalid_metric_label'
         throw new Error('label must be the specified name of the evaluation metric')
       }
-      if (!metricType || !['categorical', 'score', 'boolean'].includes(metricType)) {
+      if (!metricType || !['categorical', 'score', 'boolean', 'json'].includes(metricType)) {
         err = 'invalid_metric_type'
-        throw new Error('metricType must be one of "categorical" or "score"')
+        throw new Error('metricType must be one of "categorical", "score", "boolean" or "json"')
       }
       if (metricType === 'categorical' && typeof value !== 'string') {
         err = 'invalid_metric_value'
@@ -381,6 +381,22 @@ class LLMObs extends NoopLLMObs {
         err = 'invalid_metric_value'
         throw new Error('value must be a boolean for a boolean metric')
       }
+      if (metricType === 'json' && !(typeof value === 'object' && value != null && !Array.isArray(value))) {
+        err = 'invalid_metric_value'
+        throw new Error('value must be a JSON object for a json metric')
+      }
+      if (assessment != null && assessment !== 'pass' && assessment !== 'fail') {
+        err = 'invalid_assessment'
+        throw new Error('assessment must be pass or fail')
+      }
+      if (reasoning != null && typeof reasoning !== 'string') {
+        err = 'invalid_reasoning'
+        throw new Error('reasoning must be a string')
+      }
+      if (metadata != null && (typeof metadata !== 'object' || Array.isArray(metadata))) {
+        err = 'invalid_metadata'
+        throw new Error('metadata must be a JSON object')
+      }
 
       const evaluationTags = {
         'ddtrace.version': tracerVersion,
@@ -412,8 +428,12 @@ class LLMObs extends NoopLLMObs {
       }
 
       const payload = {
-        span_id: spanId,
-        trace_id: traceId,
+        join_on: {
+          span: {
+            span_id: spanId,
+            trace_id: traceId,
+          },
+        },
         label,
         metric_type: metricType,
         ml_app: mlApp,
@@ -421,6 +441,15 @@ class LLMObs extends NoopLLMObs {
         timestamp_ms: timestampMs,
         tags: Object.entries(evaluationTags).map(([key, value]) => `${key}:${value}`),
       }
+      if (reasoning != null) {
+        payload.reasoning = reasoning
+      }
+      if (metadata != null) {
+        payload.metadata = metadata
+      }
+      if (assessment != null) {
+        payload.assessment = assessment
+      }
       const currentStore = storage.getStore()
       const routing = currentStore?.routingContext
       evalMetricAppendCh.publish({ payload, routing })