dd-trace 6.8.0 → 6.10.0

package/ci/test-optimization-validation/scenarios/helpers.js

@@ -4,6 +4,7 @@ const fs = require('node:fs')
 const path = require('path')
 
 const { getArtifactId } = require('../artifact-id')
+const { BLOCKER_CATEGORIES } = require('../blocker-category')
 const { buildDatadogEnv, buildOfflineCaptureEnv, runCommand } = require('../command-runner')
 const {
   cleanupGeneratedRuntimeFiles,
@@ -19,8 +20,10 @@ const { readOfflineOutput } = require('../offline-output')
 const { sanitizeForReport, sanitizeString } = require('../redaction')
 const { getGeneratedCommand } = require('../runner-command')
 const { ensureSafeDirectory, writeFileSafely } = require('../safe-files')
+const { getValidationBlockerEvidence } = require('../validation-blocker')
 
-const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}${String.raw`\[[0-?]*[ -/]*[@-~]`}`, 'g')
+const ANSI_PATTERN =
+  new RegExp(`${String.fromCharCode(27)}${String.raw`\[[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]`}`, 'g')
 
 function frameworkOutDir (out, framework, scenario) {
   return path.join(out, 'runs', getArtifactId(framework.id), scenario)
@@ -193,10 +196,11 @@ async function prepareGeneratedScenario (framework, scenarioId) {
 function requireGeneratedScenario (framework, scenarioId, scenarioName) {
   const strategy = framework.generatedTestStrategy
   if (strategy?.status === 'not_possible') {
-    return skip(
+    return incomplete(
       framework,
       scenarioName,
-      `Skipped because this advanced feature is not eligible: ${strategy.reason}`,
+      `The validator cannot create a collectible test for this advanced feature: ${strategy.reason} ` +
+        'No conclusion was reached for this advanced feature.',
       getGeneratedStrategySkipEvidence(framework, scenarioName, scenarioId)
     )
   }
@@ -254,9 +258,9 @@ function getGeneratedStrategySkipEvidence (framework, scenarioName, scenarioId)
     reasonCode = 'generated-test-strategy-not-verified'
   }
 
-  return {
+  const evidence = {
     featureEligibility: {
-      eligible: false,
+      ...(reasonCode === 'generated-test-strategy-not-possible' ? {} : { eligible: false }),
       blockedBy: 'generated-test-strategy',
       reason: strategy?.reason,
       reasonCode,
@@ -265,6 +269,12 @@ function getGeneratedStrategySkipEvidence (framework, scenarioName, scenarioId)
       requiredGeneratedScenario: scenarioId,
     },
   }
+  if (reasonCode === 'generated-test-strategy-not-possible') {
+    evidence.blockerCategory = BLOCKER_CATEGORIES.VALIDATOR_LIMITATION
+    evidence.recommendation = 'Report that the selected runner configuration cannot collect validator-generated ' +
+      'tests to validator engineering. Basic Reporting remains valid; project setup changes are not required.'
+  }
+  return evidence
 }
 
 function basicEventEvidence (events) {
@@ -442,6 +452,8 @@ function copy (target, source, key) {
 
 function summarizeDebugRerun ({ result, events, offline, outDir }) {
   const output = `${result.stdout}\n${result.stderr}`
+  const testEvents = eventsOfType(events, 'test')
+  const sourceFiles = new Set(testEvents.map(test => test.testSourceFile).filter(Boolean))
 
   return {
     ran: true,
@@ -449,8 +461,12 @@ function summarizeDebugRerun ({ result, events, offline, outDir }) {
     commandTimedOut: result.timedOut,
     debugCommandFailed: result.exitCode !== 0 || result.timedOut === true,
     offlineExporterInitialized: offline.initialized,
+    settingsLoadedFromCache: offline.inputs.settings?.status === 'loaded',
     artifactDirectory: outDir,
     ...basicEventEvidence(events),
+    testEventsWithoutSourceFile: testEvents.length - testEvents.filter(test => test.testSourceFile).length,
+    testSourceFileCount: sourceFiles.size,
+    testSourceFiles: [...sourceFiles].slice(0, 5),
     debugLines: findInterestingLines(output, [
       /dd-trace/i,
       /test optimization/i,
@@ -541,7 +557,15 @@ function inconclusive (framework, scenario, diagnosis, evidence = {}, outDir, ex
 }
 
 function error (framework, scenario, err, outDir = err?.artifactDirectory) {
-  return result(framework, scenario, 'error', err && err.stack ? err.stack : String(err), {}, outDir)
+  const blockerEvidence = getValidationBlockerEvidence(err)
+  return result(
+    framework,
+    scenario,
+    blockerEvidence ? 'blocked' : 'error',
+    blockerEvidence ? err.message : (err && err.stack ? err.stack : String(err)),
+    blockerEvidence || {},
+    outDir
+  )
 }
 
 function result (framework, scenario, status, diagnosis, evidence, outDir, extraArtifacts) {

package/ci/test-optimization-validation/static-diagnosis.js

@@ -8,6 +8,7 @@ const {
   getFrameworkDefinitions,
   runDiagnosis,
 } = require('../diagnose')
+const { BLOCKER_CATEGORIES } = require('./blocker-category')
 const { sanitizeForReport } = require('./redaction')
 const { writeFileSafely } = require('./safe-files')
 
@@ -45,6 +46,7 @@ function runStaticDiagnosis ({ manifest, out }) {
 function getStaticBlocker (framework, diagnosis) {
   if (!SUPPORTED_FRAMEWORKS.has(framework.framework)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.VALIDATOR_LIMITATION,
       reason: `Unsupported test framework detected: ${getUnsupportedFrameworkName(framework)}.`,
       recommendation: 'Choose Jest, Mocha, Cucumber, Cypress, Playwright, or Vitest for live validation.',
     }
@@ -56,6 +58,7 @@ function getStaticBlocker (framework, diagnosis) {
   const version = parseVersion(framework.frameworkVersion)
   if (version && !satisfies(version, definition.supportedRange)) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.UNSUPPORTED_VERSION,
       reason:
         `${definition.name} ${version} is not supported. Supported range is ${definition.supportedRange}.`,
       recommendation: definition.recommendation,
@@ -65,6 +68,7 @@ function getStaticBlocker (framework, diagnosis) {
   const staticVersionError = findStaticVersionError(definition, diagnosis, framework, version)
   if (staticVersionError) {
     return {
+      blockerCategory: BLOCKER_CATEGORIES.UNSUPPORTED_VERSION,
       reason: staticVersionError.title,
       recommendation: staticVersionError.recommendation || staticVersionError.message,
     }
@@ -117,8 +121,11 @@ function getExactFrameworkLocations (diagnosis, framework) {
   const locations = new Set()
   addRelativeFrameworkLocation(locations, diagnosis, framework.project?.packageJson)
 
-  for (const configFile of framework.project?.configFiles || []) {
-    addRelativeFrameworkLocation(locations, diagnosis, configFile)
+  const configFiles = framework.project?.configFiles
+  if (configFiles) {
+    for (const configFile of configFiles) {
+      addRelativeFrameworkLocation(locations, diagnosis, configFile)
+    }
   }
 
   return locations
@@ -149,7 +156,7 @@ function normalizeRelativePath (location) {
 
 function parseVersion (rawVersion) {
   if (typeof rawVersion !== 'string') return null
-  const match = rawVersion.match(/\d+\.\d+\.\d+/)
+  const match = rawVersion.match(/(?<!\d)\d+\.\d+\.\d+/)
   return match ? match[0] : null
 }
 

package/ci/test-optimization-validation/test-output.js

@@ -4,7 +4,8 @@ const cypressAdapter = require('./framework-adapters/cypress')
 const cucumberAdapter = require('./framework-adapters/cucumber')
 const playwrightAdapter = require('./framework-adapters/playwright')
 
-const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}${String.raw`\[[0-?]*[ -/]*[@-~]`}`, 'g')
+const ANSI_PATTERN =
+  new RegExp(`${String.fromCharCode(27)}${String.raw`\[[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]`}`, 'g')
 
 /**
  * Extracts the final test count from common JavaScript test-runner summaries.

package/ci/test-optimization-validation/validation-blocker.js

@@ -0,0 +1,21 @@
+'use strict'
+
+function createValidationBlocker (message, { kind, recommendation, suppressReport = false }) {
+  const error = new Error(message)
+  error.validationBlocker = { kind, recommendation }
+  error.validationExitCode = 2
+  error.suppressReport = suppressReport
+  return error
+}
+
+function getValidationBlockerEvidence (error) {
+  if (!error?.validationBlocker) return
+  return {
+    blockerKind: error.validationBlocker.kind,
+    domain: 'validator_state',
+    recommendation: error.validationBlocker.recommendation,
+    validationIncomplete: true,
+  }
+}
+
+module.exports = { createValidationBlocker, getValidationBlockerEvidence }

package/ci/vitest-no-worker-init-setup.mjs

@@ -3,17 +3,19 @@ import { afterEach, beforeAll, beforeEach, inject } from 'vitest'
 // Instrumentation-less setup for DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT.
 // It applies Test Optimization execution changes without initializing dd-trace and also supports Browser Mode.
 const VITEST_NO_WORKER_INIT_ACTIVE_ENV = 'DD_TEST_OPT_VITEST_NO_WORKER_INIT_ACTIVE'
+const SERIALIZED_CONTEXT_PREFIX = '\u0000dd-vitest-context:'
 const providedContext = getProvidedContext()
 const isNoWorkerInitActive = providedContext.isActive ?? getIsNoWorkerInitActive()
 const attemptToFixTests = providedContext.attemptToFixTests || {}
 const attemptToFixRetries = providedContext.attemptToFixRetries || 0
 const disabledTests = providedContext.disabledTests || {}
-const earlyFlakeDetectionRetries = providedContext.earlyFlakeDetectionRetries || 0
-const earlyFlakeDetectionRetryThresholds = Array.isArray(providedContext.earlyFlakeDetectionRetryThresholds)
-  ? providedContext.earlyFlakeDetectionRetryThresholds
-  : []
-const earlyFlakeDetectionSlowRetries = providedContext.earlyFlakeDetectionSlowRetries || {}
-const hasEarlyFlakeDetectionSlowRetries = Object.keys(earlyFlakeDetectionSlowRetries).length > 0
+const efdSuiteAdmissionBrowserCommand = providedContext.efdSuiteAdmissionBrowserCommand
+const earlyFlakeDetectionRetryPolicy = providedContext.earlyFlakeDetectionRetryPolicy || {
+  durationRetryCounts: [],
+  schedulingRetryCount: 0,
+}
+const earlyFlakeDetectionRetries = earlyFlakeDetectionRetryPolicy.schedulingRetryCount
+const isEfdSuiteAdmissionEnabled = providedContext.isEfdSuiteAdmissionEnabled === true
 const isEarlyFlakeDetectionEnabled = providedContext.isEarlyFlakeDetectionEnabled === true
 const knownTests = providedContext.knownTests || {}
 const modifiedFiles = providedContext.modifiedFiles || {}
@@ -35,6 +37,7 @@ const earlyFlakeDetectionStartByTask = new WeakMap()
 const nextAttemptIndexByTask = new WeakMap()
 const retryAttemptIndexByTask = new WeakMap()
 const usedRumTestExecutionIds = new Set()
+let browserCommands
 let now
 let timeOrigin
 // Use an unfaked monotonic clock in Node and Vitest's parent frame in Browser Mode.
@@ -49,18 +52,42 @@ if (typeof globalThis.process?.uptime === 'function') {
   timeOrigin = Number.isFinite(clock?.timeOrigin) ? clock.timeOrigin : Date.now() - now()
 }
 
+/**
+ * Requests permission from the Vitest main process to schedule Browser Mode EFD retries for one suite.
+ *
+ * @param {string} testSuite
+ * @param {boolean} hasNewTest
+ * @returns {Promise<boolean>}
+ */
+async function requestBrowserEfdSuiteAdmission (testSuite, hasNewTest) {
+  try {
+    if (!browserCommands) {
+      const vitestBrowser = await import('@vitest/browser/context')
+      browserCommands = vitestBrowser.commands
+    }
+    return await browserCommands[efdSuiteAdmissionBrowserCommand](testSuite, hasNewTest) === true
+  } catch (error) {
+    // Browser Mode setup runs without dd-trace, so the tracer logger is unavailable.
+    globalThis.console?.error('Datadog Test Optimization could not request Vitest EFD suite admission.', error)
+    return false
+  }
+}
+
 if (isNoWorkerInitActive) {
   // eslint-disable-next-line no-empty-pattern
-  beforeAll(function ({}, suite) {
+  beforeAll(async function ({}, suite) {
     suite ||= arguments[0]
-    applyExecutionChanges(suite)
+    const efdSuiteCandidate = getEarlyFlakeDetectionSuiteCandidate(suite)
+    const isEfdSuiteAdmissionAllowed = !efdSuiteCandidate || !isEfdSuiteAdmissionEnabled ||
+      await requestBrowserEfdSuiteAdmission(efdSuiteCandidate.testSuite, efdSuiteCandidate.hasNewTest)
+    applyExecutionChanges(suite, isEfdSuiteAdmissionAllowed)
   })
 
   beforeEach(function ({ onTestFinished, task, skip }) {
     const testSuite = getTestSuite(task)
     const testName = getTestName(task)
     const isAttemptToFixTest = attemptToFixTests[testSuite]?.[testName]
-    const isEarlyFlakeDetectionTestAttempt = isEarlyFlakeDetectionTest(testSuite, testName)
+    const isEarlyFlakeDetectionTestAttempt = isEarlyFlakeDetectionTask(task)
     const isQuarantinedTest = quarantinedTests[testSuite]?.[testName] && !isAttemptToFixTest
     const attemptIndex = getNextAttemptIndex(task)
     const attemptStart = now()
@@ -109,27 +136,30 @@ if (isNoWorkerInitActive) {
   })
 }
 
-function applyExecutionChanges (suite) {
-  for (const task of suite?.tasks || []) {
-    if (task.type === 'suite') {
-      applyExecutionChanges(task)
-      continue
-    }
+function applyExecutionChanges (suite, isEfdSuiteAdmissionAllowed) {
+  const tasks = suite?.tasks
+  if (tasks) {
+    for (const task of tasks) {
+      if (task.type === 'suite') {
+        applyExecutionChanges(task, isEfdSuiteAdmissionAllowed)
+        continue
+      }
 
-    const testSuite = getTestSuite(task)
-    const testName = getTestName(task)
-    if (attemptToFixTests[testSuite]?.[testName]) {
-      task.retry = 0
-      task.repeats = attemptToFixRetries
-      task.meta.__ddTestOptAtfRetries = attemptToFixRetries
-    } else if (disabledTests[testSuite]?.[testName]) {
-      task.mode = 'skip'
-    } else if (isEarlyFlakeDetectionTest(testSuite, testName)) {
-      task.retry = 0
-      task.repeats = earlyFlakeDetectionRetries
-      task.meta.__ddTestOptEfdRetries = earlyFlakeDetectionRetries
+      const testSuite = getTestSuite(task)
+      const testName = getTestName(task)
+      if (attemptToFixTests[testSuite]?.[testName]) {
+        task.retry = 0
+        task.repeats = attemptToFixRetries
+        task.meta.__ddTestOptAtfRetries = attemptToFixRetries
+      } else if (disabledTests[testSuite]?.[testName]) {
+        task.mode = 'skip'
+      } else if (isEfdSuiteAdmissionAllowed && isEarlyFlakeDetectionTest(testSuite, testName)) {
+        task.retry = 0
+        task.repeats = earlyFlakeDetectionRetries
+        task.meta.__ddTestOptEfdRetries = earlyFlakeDetectionRetries
+      }
+      wrapRetryCondition(task)
     }
-    wrapRetryCondition(task)
   }
 }
 
@@ -331,7 +361,7 @@ function recordTestOptimizationStatus (task, attemptIndex = task.result?.repeatC
 
   if (attemptToFixTests[testSuite]?.[testName]) {
     recordAttemptToFixStatus(task, attemptIndex, onlyIfNewErrors)
-  } else if (isEarlyFlakeDetectionTest(testSuite, testName)) {
+  } else if (isEarlyFlakeDetectionTask(task)) {
     recordEarlyFlakeDetectionStatus(task, attemptIndex, onlyIfNewErrors)
   } else if (task.repeats > 0) {
     recordManualRepeatStatus(task, attemptIndex)
@@ -380,7 +410,7 @@ function recordEarlyFlakeDetectionStatus (task, attemptIndex, onlyIfNewErrors) {
     earlyFlakeDetectionRetriesByTask.set(task, retryCount)
     task.repeats = retryCount
     task.meta.__ddTestOptEfdRetries = retryCount
-    if (retryCount === 0 && hasEarlyFlakeDetectionSlowRetries) {
+    if (retryCount === 0) {
       task.meta.__ddTestOptEfdAbortReason = 'slow'
     }
   }
@@ -508,7 +538,7 @@ function getFinalAttemptIndex (task) {
   if (attemptToFixTests[testSuite]?.[testName]) {
     return getAttemptToFixRetryCount(task)
   }
-  if (isEarlyFlakeDetectionTest(testSuite, testName)) {
+  if (isEarlyFlakeDetectionTask(task)) {
     return getEarlyFlakeDetectionRetryCountForTask(task)
   }
 
@@ -606,7 +636,7 @@ function prepareEarlyFlakeDetectionAttempt (task, attemptIndex) {
     earlyFlakeDetectionRetriesByTask.set(task, retryCount)
     task.repeats = retryCount
     task.meta.__ddTestOptEfdRetries = retryCount
-    if (retryCount === 0 && hasEarlyFlakeDetectionSlowRetries) {
+    if (retryCount === 0) {
       task.meta.__ddTestOptEfdAbortReason = 'slow'
     }
   }
@@ -633,16 +663,10 @@ function prepareEarlyFlakeDetectionAttempt (task, attemptIndex) {
 }
 
 function getEarlyFlakeDetectionRetryCount (task) {
-  if (!hasEarlyFlakeDetectionSlowRetries) {
-    return earlyFlakeDetectionRetries
-  }
-
   const executionStart = earlyFlakeDetectionStartByTask.get(task)
   const duration = executionStart === undefined ? task.result?.duration ?? 0 : now() - executionStart
-  for (const { key, limitMs } of earlyFlakeDetectionRetryThresholds) {
-    if (duration < limitMs) {
-      return earlyFlakeDetectionSlowRetries[key] ?? 0
-    }
+  for (const { durationLimitMs, retryCount } of earlyFlakeDetectionRetryPolicy.durationRetryCounts) {
+    if (duration < durationLimitMs) return retryCount
   }
   return 0
 }
@@ -675,6 +699,64 @@ function isEarlyFlakeDetectionTest (testSuite, testName) {
   return !testsForSuite.includes(testName)
 }
 
+/**
+ * Returns whether Datadog admitted this task for EFD retries.
+ *
+ * @param {object} task
+ * @returns {boolean}
+ */
+function isEarlyFlakeDetectionTask (task) {
+  return task.meta.__ddTestOptEfdRetries !== undefined
+}
+
+/**
+ * Returns suite admission data when a collected suite contains an EFD candidate.
+ *
+ * @param {object} suite
+ * @returns {{ hasNewTest: boolean, testSuite: string }|undefined}
+ */
+function getEarlyFlakeDetectionSuiteCandidate (suite) {
+  const tasks = suite?.tasks
+  if (!tasks) return
+
+  let candidate
+  for (const task of tasks) {
+    if (task.type === 'suite') {
+      const nestedCandidate = getEarlyFlakeDetectionSuiteCandidate(task)
+      if (nestedCandidate) {
+        candidate ||= nestedCandidate
+        candidate.hasNewTest ||= nestedCandidate.hasNewTest
+      }
+      continue
+    }
+
+    if (task.mode === 'skip' || task.mode === 'todo') continue
+
+    const testSuite = getTestSuite(task)
+    const testName = getTestName(task)
+    if (attemptToFixTests[testSuite]?.[testName] || disabledTests[testSuite]?.[testName]) continue
+    if (!isEarlyFlakeDetectionTest(testSuite, testName)) continue
+
+    candidate ||= {
+      hasNewTest: false,
+      testSuite,
+    }
+    candidate.hasNewTest ||= isNewTest(testSuite, testName)
+  }
+  return candidate
+}
+
+/**
+ * Returns whether a collected test is absent from the known-tests response.
+ *
+ * @param {string} testSuite
+ * @param {string} testName
+ * @returns {boolean}
+ */
+function isNewTest (testSuite, testName) {
+  return !(knownTests[testSuite] || []).includes(testName)
+}
+
 function isModifiedTest (testSuite) {
   return modifiedFiles[testSuite]?.length > 0
 }
@@ -716,12 +798,28 @@ function getIsNoWorkerInitActive () {
 
 function getProvidedContext () {
   try {
-    return inject('_ddVitestWorkerSetup') || {}
+    return parseProvidedContextValue(inject('_ddVitestWorkerSetup'))
   } catch {
     try {
-      return globalThis.__vitest_worker__.providedContext._ddVitestWorkerSetup || {}
+      return parseProvidedContextValue(globalThis.__vitest_worker__.providedContext._ddVitestWorkerSetup)
     } catch {
       return {}
     }
   }
 }
+
+/**
+ * Restore context serialized to keep Vitest's inline browser bootstrap script valid.
+ *
+ * @param {object|string|undefined} value
+ * @returns {object}
+ */
+function parseProvidedContextValue (value) {
+  if (typeof value !== 'string' || !value.startsWith(SERIALIZED_CONTEXT_PREFIX)) return value || {}
+
+  try {
+    return JSON.parse(value.slice(SERIALIZED_CONTEXT_PREFIX.length))
+  } catch {
+    return {}
+  }
+}

package/index.d.ts

@@ -71,7 +71,7 @@ interface Tracer extends opentracing.Tracer {
    * @param plugin The name of a built-in plugin.
    * @param config Configuration options. Can also be `false` to disable the plugin.
    */
-  use<P extends keyof Plugins> (plugin: P, config?: Plugins[P] | boolean): this;
+  use<P extends tracer.PluginName> (plugin: P, config?: tracer.PluginOptions[P] | boolean): this;
 
   /**
    * Returns a reference to the current scope.
@@ -314,6 +314,9 @@ interface Plugins {
 }
 
 declare namespace tracer {
+  export interface PluginOptions extends Plugins {}
+  export type PluginName = keyof PluginOptions;
+
   export type SpanOptions = Omit<opentracing.SpanOptions, 'childOf'> & {
   /**
    * Set childOf to 'null' to create a root span without a parent, even when a parent span
@@ -3711,6 +3714,13 @@ declare namespace tracer {
        */
       submitEvaluation (spanContext: llmobs.ExportedLLMObsSpan, options: llmobs.EvaluationOptions): void
 
+      /**
+       * Submits end-user feedback for a span, trace, session, or customer-defined entity.
+       * Exactly one target must be provided in the options.
+       * @param options An object containing the label, metric type, value, submitter and target of the feedback.
+       */
+      submitFeedback (options: llmobs.FeedbackOptions): void
+
 
       /**
        * Annotates all spans, including auto-instrumented spans, with the provided tags created in the context of the callback function.
@@ -3957,6 +3967,93 @@ declare namespace tracer {
       metadata?: { [key: string]: any }
     }
 
+    interface FeedbackSubmitter {
+      /**
+       * The identifier of the end user who submitted the feedback.
+       */
+      id: string,
+
+      /**
+       * The type of submitter, e.g. 'user'.
+       */
+      type?: string
+    }
+
+    interface FeedbackOptions {
+      /**
+       * The name of the feedback metric
+       */
+      label: string,
+
+      /**
+       * The type of feedback metric, one of 'categorical', 'score', 'boolean', 'json' or 'text'
+       */
+      metricType: 'categorical' | 'score' | 'boolean' | 'json' | 'text',
+
+      /**
+       * The value of the feedback metric.
+       * Must be string for 'categorical' and 'text' metrics, number for 'score' metrics, boolean for 'boolean' metrics and a JSON object for 'json' metrics.
+       */
+      value: string | number | boolean | { [key: string]: any },
+
+      /**
+       * Who submitted the feedback.
+       */
+      submitter: llmobs.FeedbackSubmitter,
+
+      /**
+       * The span context of the span to attach the feedback to, as returned by `llmobs.exportSpan()`.
+       * Exactly one of `span`, `spanId`, `traceId`, `sessionId` or `feedbackJoinKey` must be provided.
+       */
+      span?: llmobs.ExportedLLMObsSpan,
+
+      /**
+       * The ID of the span to attach the feedback to.
+       */
+      spanId?: string,
+
+      /**
+       * The ID of the trace to attach the feedback to.
+       */
+      traceId?: string,
+
+      /**
+       * The ID of the session to attach the feedback to.
+       */
+      sessionId?: string,
+
+      /**
+       * A customer-defined key to attach the feedback to.
+       */
+      feedbackJoinKey?: string,
+
+      /**
+       * An object of string key-value pairs to tag the feedback with.
+       * A `null` or `undefined` value is sent as the string `"null"` or `"undefined"`.
+       */
+      tags?: { [key: string]: string | null | undefined },
+
+      /**
+       * The name of the ML application
+       */
+      mlApp?: string,
+
+      /**
+       * The timestamp in milliseconds when the feedback was generated.
+       */
+      timestampMs?: number,
+
+      /**
+       * Reasoning for the feedback.
+       */
+      reasoning?: string,
+
+      /**
+       * Whether the feedback passed or failed. Valid values are pass and fail.
+       */
+      assessment?: 'pass' | 'fail'
+    }
+
     interface Document {
       /**
        * Document text
@@ -4002,6 +4099,11 @@ declare namespace tracer {
        * Audio segments attached to the message (e.g. speech input/output)
        */
       audioParts?: AudioPart[],
+
+      /**
+       * Images attached to the message (e.g. vision input, generated output)
+       */
+      imageParts?: ImagePart[],
     }
 
     /**
@@ -4019,6 +4121,43 @@ declare namespace tracer {
       content: string,
     }
 
+    /**
+     * Represents an image attached to an LLM chat model message, carrying exactly
+     * one of inline `content` or an `attachmentKey`. Supplying neither or both is
+     * rejected by the tagger, and the union keeps both shapes from type-checking.
+     */
+    type ImagePart = {
+      /**
+       * The MIME type of the image (e.g. "image/png", "image/jpeg")
+       */
+      mimeType: string,
+
+      /**
+       * The image content as a base64-encoded string
+       */
+      content: string,
+
+      /**
+       * Explicitly excluded when inline content is present to maintain type safety.
+       */
+      attachmentKey?: never,
+    } | {
+      /**
+       * The MIME type of the image (e.g. "image/png", "image/jpeg")
+       */
+      mimeType: string,
+
+      /**
+       * Key of an already-uploaded image, in place of inline content
+       */
+      attachmentKey: string,
+
+      /**
+       * Explicitly excluded when an attachment key is present to maintain type safety.
+       */
+      content?: never,
+    }
+
     /**
      * Represents a single tool call for an LLM chat model message
      */

package/init.js

@@ -1,22 +1,6 @@
 'use strict'
 
-// In PM2 cluster mode, per-app env vars arrive as a `pm2_env`
-// JSON string after --require has already run so we extract them
-// manually if present.
-var pm2EnvStr = process.env.pm2_env
-if (typeof pm2EnvStr === 'string') {
-  try {
-    var pm2Config = JSON.parse(pm2EnvStr)
-    var pm2Keys = Object.keys(pm2Config)
-    for (var i = 0; i < pm2Keys.length; i++) {
-      var k = pm2Keys[i]
-      var v = pm2Config[k]
-      if (v != null) {
-        process.env[k] = String(v)
-      }
-    }
-  } catch (e) {}
-}
+require('./packages/dd-trace/src/guardrails/apply-pm2-env')
 
 var guard = require('./packages/dd-trace/src/guardrails')