dd-trace 6.17.0 → 6.19.0

package/packages/datadog-instrumentations/src/cypress-config.js

@@ -426,15 +426,16 @@ function registerManualAfterScreenshotHandlers (on, handlers, datadogHandler) {
 }
 
 /**
- * Registers one Cypress after:spec handler that runs every collected handler
+ * Registers one Cypress lifecycle handler that runs every collected handler
  * in registration order. Cypress 10+ otherwise keeps only the last handler.
  *
  * @param {Function} on Cypress event registration function
- * @param {Function[]} handlers collected after:spec handlers
- * @param {Function} [datadogHandler] manual Datadog after:spec handler
+ * @param {'before:run'|'after:spec'} event lifecycle event
+ * @param {Function[]} handlers collected lifecycle handlers
+ * @param {Function} [datadogHandler] Datadog lifecycle handler
  * @param {Function} [cleanup] removes generated support files after an error
  */
-function registerAfterSpecHandlers (on, handlers, datadogHandler, cleanup) {
+function registerLifecycleHandlers (on, event, handlers, datadogHandler, cleanup) {
   const userHandlers = datadogHandler
     ? handlers.filter(handler => handler !== datadogHandler)
     : handlers
@@ -442,27 +443,31 @@ function registerAfterSpecHandlers (on, handlers, datadogHandler, cleanup) {
   if (userHandlers.length === 0) {
     if (datadogHandler) {
       if (cleanup) {
-        on('after:spec', (...args) => Promise.resolve().then(() => datadogHandler(...args)).catch((error) => {
+        on(event, (...args) => Promise.resolve().then(() => datadogHandler(...args)).catch((error) => {
           cleanup()
           throw error
         }))
       } else {
-        on('after:spec', datadogHandler)
+        on(event, datadogHandler)
       }
     }
     return
   }
 
-  on('after:spec', (spec, results) => {
+  on(event, (...args) => {
     const callHandler = datadogHandler
-      ? handler => runUserHandler(() => handler(spec, results))
-      : handler => handler(spec, results)
+      ? handler => runUserHandler(() => handler(...args))
+      : handler => handler(...args)
     const chain = userHandlers.reduce(
       (promise, handler) => promise.then(() => callHandler(handler)),
       Promise.resolve()
     )
     if (!datadogHandler) return chain
-    const finalization = finalizeAfterUserHandlers(chain, (...args) => datadogHandler(spec, results, ...args))
+    const finalization = finalizeAfterUserHandlers(chain, (...errors) => {
+      // A failed setup hook must abort the run before Datadog starts its session.
+      if (event === 'before:run' && errors.length > 0) return
+      return datadogHandler(...args, ...errors)
+    })
     if (!cleanup) return finalization
     return finalization.catch((error) => {
       cleanup()
@@ -514,6 +519,9 @@ function registerDdTraceHooks (
   if (generatedSupportFiles) registerGeneratedFilesForExitCleanup(generatedSupportFiles)
 
   const cleanupWrapper = () => {
+    // Open mode reuses this support file across runs, including failed setup attempts.
+    // The registered process-exit cleanup owns its lifetime instead.
+    if (config.isInteractive) return
     if (generatedSupportFiles) cleanupGeneratedFiles(generatedSupportFiles)
   }
 
@@ -537,8 +545,13 @@ function registerDdTraceHooks (
     })
   }
 
+  const registerBeforeRun = handler => {
+    registerLifecycleHandlers(on, 'before:run', userBeforeRunHandlers, handler, cleanupWrapper)
+  }
+
   const registerNoopHandlers = () => {
-    registerAfterSpecHandlers(on, userAfterSpecHandlers)
+    registerBeforeRun()
+    registerLifecycleHandlers(on, 'after:spec', userAfterSpecHandlers)
     for (const h of userAfterScreenshotHandlers) on('after:screenshot', h)
     registerAfterRunWithCleanup()
     on('task', noopTask)
@@ -555,8 +568,8 @@ function registerDdTraceHooks (
         manualPlugin.initialConfig.experimentalInteractiveRunEvents = config.experimentalInteractiveRunEvents
       }
     }
-    for (const handler of userBeforeRunHandlers) on('before:run', handler)
-    registerAfterSpecHandlers(on, userAfterSpecHandlers, manualPlugin.afterSpecHandler, cleanupWrapper)
+    registerBeforeRun(manualPlugin.beforeRunHandler)
+    registerLifecycleHandlers(on, 'after:spec', userAfterSpecHandlers, manualPlugin.afterSpecHandler, cleanupWrapper)
     registerManualAfterScreenshotHandlers(on, userAfterScreenshotHandlers, manualPlugin.afterScreenshotHandler)
     registerAfterRunWithCleanup(manualPlugin.afterRunHandler)
     on('task', manualPlugin.taskHandler)
@@ -572,8 +585,6 @@ function registerDdTraceHooks (
     )
   }
 
-  for (const handler of userBeforeRunHandlers) on('before:run', handler)
-
   if (!setupNodeEventsCh.hasSubscribers) {
     registerNoopHandlers()
     return config
@@ -588,6 +599,7 @@ function registerDdTraceHooks (
     userAfterSpecHandlers,
     userAfterRunHandlers,
     userAfterScreenshotHandlers,
+    registerBeforeRun,
     cleanupWrapper,
     registered: false,
     configPromise: undefined,

package/packages/datadog-instrumentations/src/helpers/bundler-register.js

@@ -13,6 +13,7 @@ const {
 } = require('./instrumentation-utils')
 const hooks = require('./hooks')
 const instrumentations = require('./instrumentations')
+const { isRewriteActivationEnabled } = require('./rewriter/targets')
 const disabledInstrumentations = getDisabledInstrumentations()
 
 // register.js has now set up ritm (require-in-the-middle). In bundled
@@ -94,6 +95,11 @@ dc.subscribe(CHANNEL, (message) => {
   const name = payload.package
   if (disabledInstrumentations.has(name)) return
 
+  if (payload.activate && isRewriteActivationEnabled(name)) {
+    loadChannel.publish({ name })
+    return
+  }
+
   const isPrefixedWithNode = name.startsWith('node:')
   const isNodeModule = isPrefixedWithNode || !hooks[name]
 

package/packages/datadog-instrumentations/src/helpers/check-require-cache.js

@@ -69,6 +69,7 @@ const earlyLoadFrameworks = new Map([
  */
 module.exports.checkForRequiredModules = function () {
   const packages = require('./hooks')
+  const { isRewriteTargetName } = require('./rewriter/targets')
   const naughties = new Set()
   const frameworksSeen = new Set()
   let didWarn = false
@@ -98,7 +99,7 @@ module.exports.checkForRequiredModules = function () {
       continue
     }
 
-    if (naughties.has(pkg) || !(pkg in packages)) continue
+    if (naughties.has(pkg) || (!(pkg in packages) && !isRewriteTargetName(pkg))) continue
 
     loadOrderWarnings.push(
       () => `Warning: Package '${pkg}' was loaded before dd-trace! This may break instrumentation.`

package/packages/datadog-instrumentations/src/helpers/hooks.js

@@ -25,14 +25,12 @@ module.exports = {
   '@anthropic-ai/sdk': { esmFirst: true, fn: () => require('../anthropic') },
   '@apollo/server': () => require('../apollo-server'),
   '@apollo/gateway': () => require('../apollo'),
-  '@langchain/langgraph': { esmFirst: true, fn: () => require('../langgraph') },
   '@modelcontextprotocol/sdk': { esmFirst: true, fn: () => require('../modelcontextprotocol-sdk') },
   '@openai/agents': () => require('../openai-agents'),
   '@openai/agents-openai': () => require('../openai-agents'),
   'apollo-server-core': () => require('../apollo-server-core'),
   '@aws-sdk/smithy-client': () => require('../aws-sdk'),
   '@aws/durable-execution-sdk-js': () => require('../aws-durable-execution-sdk-js'),
-  '@azure/cosmos': { esmFirst: true, fn: () => require('../azure-cosmos') },
   '@azure/event-hubs': () => require('../azure-event-hubs'),
   '@azure/functions': () => require('../azure-functions'),
   'durable-functions': () => require('../azure-durable-functions'),
@@ -54,7 +52,6 @@ module.exports = {
   '@jest/test-sequencer': () => require('../jest'),
   '@jest/transform': () => require('../jest'),
   '@koa/router': () => require('../koa'),
-  '@langchain/core': { esmFirst: true, fn: () => require('../langchain') },
   '@node-redis/client': () => require('../redis'),
   '@opensearch-project/opensearch': () => require('../opensearch'),
   '@opentelemetry/sdk-trace': () => require('../otel-sdk-trace'),
@@ -78,7 +75,6 @@ module.exports = {
   bluebird: () => require('../bluebird'),
   'body-parser': () => require('../body-parser'),
   'browser-bunyan': () => require('../browser-bunyan'),
-  bullmq: () => require('../bullmq'),
   bunyan: () => require('../bunyan'),
   'cassandra-driver': () => require('../cassandra-driver'),
   connect: () => require('../connect'),
@@ -114,14 +110,12 @@ module.exports = {
   'koa-router': () => require('../koa'),
   '@confluentinc/kafka-javascript': () => require('../confluentinc-kafka-javascript'),
   kafkajs: () => require('../kafkajs'),
-  langchain: () => require('../langchain'),
   ldapjs: () => require('../ldapjs'),
   'light-my-request': () => require('../light-my-request'),
   'limitd-client': () => require('../limitd-client'),
   lodash: () => require('../lodash'),
   mariadb: { esmFirst: true, fn: () => require('../mariadb') },
   memcached: () => require('../memcached'),
-  mercurius: () => require('../mercurius'),
   'microgateway-core': () => require('../microgateway-core'),
   mocha: () => require('../mocha'),
   'mocha-each': () => require('../mocha'),

package/packages/datadog-instrumentations/src/helpers/register.js

@@ -25,6 +25,7 @@ const pathSepExpr = new RegExp(`\\${path.sep}`, 'g')
 const disabledInstrumentations = getDisabledInstrumentations()
 
 const loadChannel = channel('dd-trace:instrumentation:load')
+const orchestrionLoadChannel = channel('dd-trace:instrumentation:load:orchestrion')
 
 // Globals
 if (!disabledInstrumentations.has('fetch')) {
@@ -55,6 +56,25 @@ const instrumentedNodeModules = new Map()
 const instrumentedIntegrationsSuccess = new Map()
 /** @type {Set<string>} */
 const alreadyLoggedIncompatibleIntegrations = new Set()
+/** @type {Set<string>} */
+const compatibleOrchestrionTargets = new Set()
+
+orchestrionLoadChannel.subscribe(({ moduleName, version, result }) => {
+  const nameVersion = `${moduleName}@${version}`
+
+  if (result === 'unsupported') {
+    if (!compatibleOrchestrionTargets.has(nameVersion) && !instrumentedIntegrationsSuccess.has(nameVersion)) {
+      instrumentedIntegrationsSuccess.set(nameVersion, false)
+    }
+    return
+  }
+
+  if (result === 'matched' || result === 'rewritten') {
+    compatibleOrchestrionTargets.add(nameVersion)
+    instrumentedIntegrationsSuccess.set(nameVersion, true)
+    if (result === 'rewritten') loadChannel.publish({ name: moduleName })
+  }
+})
 
 for (const name of names) {
   if (disabledInstrumentations.has(name)) continue

package/packages/datadog-instrumentations/src/helpers/rewriter/index.js

@@ -19,7 +19,7 @@ const { getRewriteTarget } = require('./targets')
  *   { code: string, map?: string|object }} transform
  *
  * @typedef {(content: string|Buffer|ArrayBuffer|Uint8Array, filename: string, format?: string,
- *   target?: { moduleName: string, filePath: string }, sourceMap?: string|object) =>
+ *   target?: { moduleName: string, filePath: string, activate?: boolean }, sourceMap?: string|object) =>
  *   { code: string|Buffer|ArrayBuffer|Uint8Array, map?: string|object }} BundlerRewriter
  */
 
@@ -62,7 +62,7 @@ function normalizeFilename (filename) {
  * @param {string|Buffer|ArrayBuffer|Uint8Array} content
  * @param {string} filename
  * @param {string} [format]
- * @param {{ moduleName: string, filePath: string }} [target]
+ * @param {{ moduleName: string, filePath: string, activate?: boolean }} [target]
  * @returns {string|Buffer|ArrayBuffer|Uint8Array}
  */
 function rewrite (content, filename, format, target) {
@@ -74,7 +74,7 @@ function rewrite (content, filename, format, target) {
     if (!target) return content
 
     const moduleType = format === 'module' ? 'esm' : 'cjs'
-    const { moduleName, filePath } = target
+    const { moduleName, filePath, activate } = target
     if (disabled.has(moduleName)) return content
 
     const version = getVersion(filename, filePath)
@@ -82,10 +82,18 @@ function rewrite (content, filename, format, target) {
 
     const transformer = getMatcher(moduleType).getTransformer(moduleName, version, filePath)
 
-    if (!transformer) return content
+    if (!transformer && !activate) return content
 
     const source = getSourceText(content)
 
+    if (!transformer) {
+      return appendOrchestrionLoad(
+        source,
+        { moduleName, version, result: 'unsupported' },
+        moduleType
+      )
+    }
+
     // TODO: pass existing sourcemap as input for remapping
     let { code, map } = transformer.transform(source, moduleType)
 
@@ -98,6 +106,11 @@ function rewrite (content, filename, format, target) {
       map = shiftSourceMapLine(map)
     }
 
+    if (activate) {
+      const result = code === source ? 'matched' : 'rewritten'
+      code = appendOrchestrionLoad(code, { moduleName, version, result }, moduleType)
+    }
+
     if (!map) return code
 
     const inlineMap = Buffer.from(typeof map === 'string' ? map : JSON.stringify(map)).toString('base64')
@@ -236,6 +249,30 @@ function getSourceText (source) {
   return Buffer.from(source).toString('utf8')
 }
 
+/**
+ * Publish target-level compatibility on the application thread when a pure target is evaluated.
+ *
+ * @param {string} source
+ * @param {{ moduleName: string, version: string,
+ *   result: 'unsupported'|'matched'|'rewritten' }} payload
+ * @param {'cjs'|'esm'} moduleType
+ */
+function appendOrchestrionLoad (source, payload, moduleType) {
+  const dcModule = JSON.stringify(getDcPolyfillSpecifier(moduleType) ?? 'diagnostics_channel')
+  const message = JSON.stringify(payload)
+
+  if (moduleType === 'esm') {
+    let binding = 'ddTraceOrchestrionDc'
+    let suffix = 0
+    while (source.includes(binding)) binding = `ddTraceOrchestrionDc${++suffix}`
+
+    return `${source};import ${binding} from ${dcModule};` +
+      `${binding}.channel('dd-trace:instrumentation:load:orchestrion').publish(${message});`
+  }
+
+  return `${source};require(${dcModule}).channel('dd-trace:instrumentation:load:orchestrion').publish(${message});`
+}
+
 /**
  * Account for a shebang restored ahead of the generated program. The transformer already maps original positions
  * past the input shebang, so only the generated side needs an additional empty line.

package/packages/datadog-instrumentations/src/helpers/rewriter/instrumentation-registry.js

@@ -1,17 +1,19 @@
 'use strict'
 
-// activationName is the plugin-manager key published after a target is successfully rewritten.
+// Activated rewrites publish their module name to the plugin manager after evaluation.
+// Only pure Orchestrion integrations that need this activation set activate: true.
+// Other entries use hooks or another activation path, or do not need activation from a rewrite.
 const registry = [
   { instrumentations: require('./instrumentations/ai') },
-  { activationName: '@azure/cosmos', instrumentations: require('./instrumentations/azure-cosmos') },
+  { activate: true, instrumentations: require('./instrumentations/azure-cosmos') },
   { instrumentations: require('./instrumentations/azure-durable-functions') },
-  { activationName: 'bullmq', instrumentations: require('./instrumentations/bullmq') },
+  { activate: true, instrumentations: require('./instrumentations/bullmq') },
   { instrumentations: require('./instrumentations/claude-agent-sdk') },
   { instrumentations: require('./instrumentations/graphql') },
   { instrumentations: require('./instrumentations/graphql-jit') },
-  { activationName: '@langchain/core', instrumentations: require('./instrumentations/langchain') },
-  { activationName: '@langchain/langgraph', instrumentations: require('./instrumentations/langgraph') },
-  { activationName: 'mercurius', instrumentations: require('./instrumentations/mercurius') },
+  { activate: true, instrumentations: require('./instrumentations/langchain') },
+  { activate: true, instrumentations: require('./instrumentations/langgraph') },
+  { activate: true, instrumentations: require('./instrumentations/mercurius') },
   { instrumentations: require('./instrumentations/modelcontextprotocol-sdk') },
   { instrumentations: require('./instrumentations/openai-agents') },
   { instrumentations: require('./instrumentations/playwright') },
@@ -21,10 +23,10 @@ const registry = [
   { instrumentations: require('./instrumentations/supabase') },
 ]
 
-const activationNames = new Map()
-for (const { activationName, instrumentations } of registry) {
-  if (!activationName) continue
-  for (const { module } of instrumentations) activationNames.set(module.name, activationName)
+const activatedModules = new Set()
+for (const { activate, instrumentations } of registry) {
+  if (!activate) continue
+  for (const { module } of instrumentations) activatedModules.add(module.name)
 }
 
 const instrumentations = registry.flatMap(entry => entry.instrumentations)
@@ -32,8 +34,8 @@ const instrumentations = registry.flatMap(entry => entry.instrumentations)
 /**
  * @param {string} moduleName
  */
-function getRewriteActivationName (moduleName) {
-  return activationNames.get(moduleName)
+function isRewriteActivationEnabled (moduleName) {
+  return activatedModules.has(moduleName)
 }
 
-module.exports = { getRewriteActivationName, instrumentations, registry }
+module.exports = { isRewriteActivationEnabled, instrumentations, registry }

package/packages/datadog-instrumentations/src/helpers/rewriter/instrumentations/playwright.js

@@ -3,6 +3,57 @@
 // Playwright keeps several hook targets in private local classes/functions.
 // Keep these rewrites limited to bundled internals that addHook cannot wrap.
 module.exports = [
+  ...[
+    ['>=1.38.0 <1.60.0', 'lib/common/config.js'],
+    ['>=1.60.0', 'lib/common/index.js'],
+  ].map(([versionRange, filePath]) => ({
+    module: { name: 'playwright', versionRange, filePath },
+    functionQuery: { className: 'FullProjectInternal', methodName: 'constructor', kind: 'Sync' },
+    channelName: 'FullProjectInternal',
+  })),
+  {
+    module: {
+      name: '@playwright/test',
+      versionRange: '>=1.18.0 <1.38.0',
+      filePath: 'lib/reporters/multiplexer.js',
+    },
+    functionQuery: {
+      className: 'Multiplexer',
+      methodName: 'onError',
+      kind: 'Sync',
+    },
+    channelName: 'Multiplexer_onError',
+  },
+  {
+    module: {
+      name: 'playwright',
+      versionRange: '>=1.44.0 <1.60.0',
+      filePath: 'lib/runner/runner.js',
+    },
+    astQuery: 'FunctionDeclaration[id.name="writeLastRunInfo"] ' +
+      'CallExpression[callee.property.name="map"] > ArrowFunctionExpression',
+    channelName: 'lastRunTestId',
+  },
+  {
+    module: {
+      name: 'playwright',
+      versionRange: '>=1.44.0 <1.60.0',
+      filePath: 'lib/runner/lastRun.js',
+    },
+    astQuery: 'ClassDeclaration[id.name="LastRunReporter"] ' +
+      'CallExpression[callee.property.name="map"] > ArrowFunctionExpression',
+    channelName: 'lastRunTestId',
+  },
+  {
+    module: {
+      name: 'playwright',
+      versionRange: '>=1.60.0',
+      filePath: 'lib/runner/index.js',
+    },
+    astQuery: 'VariableDeclarator[id.name="LastRunReporter"] ' +
+      'CallExpression[callee.property.name="map"] > ArrowFunctionExpression',
+    channelName: 'lastRunTestId',
+  },
   {
     module: {
       name: 'playwright',

package/packages/datadog-instrumentations/src/helpers/rewriter/instrumentations/webdriverio.js

@@ -1,6 +1,19 @@
 'use strict'
 
 module.exports = [
+  {
+    module: {
+      name: '@wdio/config',
+      versionRange: '>=9.0.0',
+      filePath: 'build/node/index.js',
+    },
+    functionQuery: {
+      className: 'ConfigParser',
+      methodName: 'shard',
+      kind: 'Sync',
+    },
+    channelName: 'ConfigParser_shard',
+  },
   {
     module: {
       name: '@wdio/cli',

package/packages/datadog-instrumentations/src/helpers/rewriter/targets.js

@@ -1,7 +1,8 @@
 'use strict'
 
-// Generated by scripts/generate-rewriter-targets.js from ./instrumentations. Do not edit by hand.
+// targets.json is generated by scripts/generate-rewriter-targets.js from ./instrumentation-registry.
 const targets = require('./targets.json')
+const rewriteTargetNames = new Set(Object.values(targets))
 
 const NODE_MODULES = '/node_modules/'
 
@@ -9,6 +10,7 @@ const NODE_MODULES = '/node_modules/'
  * @typedef {object} RewriteTarget
  * @property {string} moduleName
  * @property {string} filePath
+ * @property {boolean} [activate]
  */
 
 /**
@@ -20,13 +22,36 @@ function getRewriteTarget (filename) {
   if (nodeModulesIndex === -1) return
 
   const modulePath = filename.slice(nodeModulesIndex + NODE_MODULES.length)
+  if (!Object.hasOwn(targets, modulePath)) return
   const moduleName = targets[modulePath]
   if (typeof moduleName !== 'string') return
+  const activate = isRewriteActivationEnabled(moduleName)
 
-  return {
+  const rewriteTarget = {
     moduleName,
     filePath: modulePath.slice(moduleName.length + 1),
   }
+  if (activate) rewriteTarget.activate = true
+  return rewriteTarget
 }
 
-module.exports = { getRewriteTarget }
+function getRewriteTargetNames () {
+  return rewriteTargetNames.values()
+}
+
+/**
+ * @param {string} name
+ */
+function isRewriteTargetName (name) {
+  return rewriteTargetNames.has(name)
+}
+
+/**
+ * @param {string} moduleName
+ */
+function isRewriteActivationEnabled (moduleName) {
+  // Keep target-name-only consumers from loading every instrumentation descriptor.
+  return require('./instrumentation-registry').isRewriteActivationEnabled(moduleName)
+}
+
+module.exports = { getRewriteTarget, getRewriteTargetNames, isRewriteActivationEnabled, isRewriteTargetName }

package/packages/datadog-instrumentations/src/helpers/rewriter/targets.json

@@ -30,6 +30,7 @@
   "@modelcontextprotocol/sdk/dist/esm/server/mcp.js": "@modelcontextprotocol/sdk",
   "@openai/agents-openai/dist/openaiChatCompletionsModel.js": "@openai/agents-openai",
   "@openai/agents-openai/dist/openaiChatCompletionsModel.mjs": "@openai/agents-openai",
+  "@playwright/test/lib/reporters/multiplexer.js": "@playwright/test",
   "@supabase/auth-js/dist/main/GoTrueClient.js": "@supabase/auth-js",
   "@supabase/auth-js/dist/module/GoTrueClient.js": "@supabase/auth-js",
   "@supabase/functions-js/dist/main/FunctionsClient.js": "@supabase/functions-js",
@@ -41,6 +42,7 @@
   "@supabase/storage-js/dist/index.cjs": "@supabase/storage-js",
   "@supabase/storage-js/dist/index.mjs": "@supabase/storage-js",
   "@wdio/cli/build/index.js": "@wdio/cli",
+  "@wdio/config/build/node/index.js": "@wdio/config",
   "@wdio/jasmine-framework/build/index.js": "@wdio/jasmine-framework",
   "@wdio/local-runner/build/index.js": "@wdio/local-runner",
   "@wdio/runner/build/index.js": "@wdio/runner",
@@ -75,8 +77,12 @@
   "jasmine-core/lib/jasmine-core/jasmine.js": "jasmine-core",
   "mercurius/index.js": "mercurius",
   "playwright-core/lib/coreBundle.js": "playwright-core",
+  "playwright/lib/common/config.js": "playwright",
+  "playwright/lib/common/index.js": "playwright",
   "playwright/lib/index.js": "playwright",
   "playwright/lib/runner/index.js": "playwright",
+  "playwright/lib/runner/lastRun.js": "playwright",
+  "playwright/lib/runner/runner.js": "playwright",
   "postgres/cjs/src/connection.js": "postgres",
   "postgres/cjs/src/index.js": "postgres",
   "postgres/cjs/src/query.js": "postgres",

package/packages/datadog-instrumentations/src/jest/session-error.js

@@ -0,0 +1,102 @@
+'use strict'
+
+const { stripVTControlCharacters } = require('node:util')
+
+const { MAX_META_VALUE_LENGTH_TEST_OPTIMIZATION: MAX_LENGTH } =
+  require('../../../dd-trace/src/encode/tags-processors')
+const log = require('../../../dd-trace/src/log')
+
+/**
+ * @typedef {{ name?: unknown, type?: unknown, message?: unknown, stack?: unknown }} SuiteError
+ * @typedef {object} JestResults
+ * @property {number} [numFailedTestSuites]
+ * @property {number} [numFailedTests]
+ * @property {{ testExecError?: SuiteError, failureMessage?: unknown, numFailingTests?: number }[]} [testResults]
+ */
+
+/**
+ * Includes complete, deduplicated suite errors only when all details fit.
+ *
+ * @param {JestResults} results
+ * @returns {Error}
+ */
+function getSessionError (results = {}) {
+  const { numFailedTestSuites = 0, numFailedTests = 0 } = results
+  const summary = `Failed test suites: ${numFailedTestSuites}. Failed tests: ${numFailedTests}`
+  const error = new Error(summary)
+  const groups = new Map()
+  let size = 0
+  try {
+    const { testResults } = results
+    if (!testResults) return error
+    for (const result of testResults) {
+      let name, message, stack
+      try {
+        const { testExecError } = result
+        if (testExecError && !result.numFailingTests) {
+          name = readField(testExecError.name)
+          if (name === '') name = readField(testExecError.type)
+          message = readField(testExecError.message)
+          stack = readField(testExecError.stack)
+        } else {
+          // Jest's report includes assertion failures, hook errors and any suite execution error.
+          name = 'Error'
+          message = readField(result.failureMessage)
+          stack = message
+        }
+      } catch {
+        log.debug('Skipping unreadable Jest suite error in the test session summary')
+        continue
+      }
+      if (name === undefined || message === undefined || stack === undefined) return omitDetails(error)
+      if (!message && !stack) continue
+      name ||= 'Error'
+      const key = JSON.stringify([name, message, stack])
+      const group = groups.get(key)
+      if (group) {
+        group.count++
+      } else {
+        // Retained text must fit across error.message and error.stack; also bound grouping memory.
+        size += name.length + message.length + stack.length
+        if (size > 2 * MAX_LENGTH) return omitDetails(error)
+        groups.set(key, { name, message, stack, count: 1 })
+      }
+    }
+  } catch {
+    log.debug('Unable to read Jest results for the test session summary')
+    return error
+  }
+  if (!groups.size) return error
+
+  const errors = [...groups.keys()].sort().map(key => groups.get(key))
+  let message = summary
+  let stack = ''
+  for (const { name, message: detail, stack: originalStack, count } of errors) {
+    message += `\n\n${name}: ${detail} (${count} suite${count === 1 ? '' : 's'})`
+    const prefix = errors.length === 1 ? '' : `Affected suites: ${count}\n`
+    stack += (stack ? '\n\n' : '') + prefix + (originalStack || `${name}: ${detail}`)
+    if (message.length > MAX_LENGTH || stack.length > MAX_LENGTH) return omitDetails(error)
+  }
+  error.name = errors.length === 1 ? errors[0].name : 'Error'
+  error.message = message
+  error.stack = stack
+  return error
+}
+
+/**
+ * Returns undefined for oversized input before scanning or copying it.
+ * @param {unknown} value
+ */
+function readField (value) {
+  if (typeof value !== 'string') return ''
+  if (value.length > MAX_LENGTH) return
+  return stripVTControlCharacters(value)
+}
+
+/** @param {Error} error */
+function omitDetails (error) {
+  error.message += '\n\nError details exceed the size limit. See test and suite events for full details.'
+  return error
+}
+
+module.exports = { getSessionError }