dd-trace 6.16.0 → 6.18.0

package/packages/datadog-plugin-cypress/src/finalization.js

@@ -19,9 +19,6 @@ function runUserHandler (handler) {
   return userHandlerContext.run(true, handler)
 }
 
-/**
- * @returns {boolean} whether a managed finalizer owns the current lifecycle event
- */
 function shouldDeferLegacyFinalization () {
   return userHandlerContext.getStore() === true
 }

package/packages/datadog-plugin-cypress/src/index.js

@@ -26,6 +26,7 @@ class CypressPlugin extends Plugin {
         userAfterRunHandlers,
         userAfterScreenshotHandlers,
         cleanupWrapper,
+        registerBeforeRun,
       } = payload
 
       const registerAfterRunWithCleanup = (afterRunHandler) => {
@@ -79,6 +80,7 @@ class CypressPlugin extends Plugin {
       }
 
       if (cypressPlugin._isInit) {
+        registerBeforeRun()
         // Already initialized by manual plugin call — just chain user handlers.
         // Pass the plugin's afterScreenshot so chaining a user handler doesn't drop the upload
         // (the chained registration replaces the one plugin.js set, so it must include it).
@@ -94,7 +96,7 @@ class CypressPlugin extends Plugin {
         return
       }
 
-      on('before:run', cypressPlugin.beforeRun.bind(cypressPlugin))
+      registerBeforeRun(cypressPlugin.beforeRun.bind(cypressPlugin))
       registerAfterScreenshot(datadogAfterScreenshotHandler)
 
       on('after:spec', (spec, results) => {

package/packages/datadog-plugin-cypress/src/source-map-utils.js

@@ -15,7 +15,6 @@ const SOURCE_MAP_CACHE = new Map()
 /**
  * Whether a file path references JavaScript.
  * @param {string} absoluteFilePath
- * @returns {boolean}
  */
 function isJavaScriptFile (absoluteFilePath) {
   return absoluteFilePath.endsWith('.js') || absoluteFilePath.endsWith('.cjs') || absoluteFilePath.endsWith('.mjs')
@@ -25,7 +24,6 @@ function isJavaScriptFile (absoluteFilePath) {
  * Decide whether invocationDetails line can be trusted as final source line.
  * @param {string} absoluteFilePath
  * @param {number} testSourceLine
- * @returns {boolean}
  */
 function shouldTrustInvocationDetailsLine (absoluteFilePath, testSourceLine) {
   if (!Number.isInteger(testSourceLine) || testSourceLine < 1) return false
@@ -38,7 +36,6 @@ function shouldTrustInvocationDetailsLine (absoluteFilePath, testSourceLine) {
  * Decode one VLQ-encoded integer from `str` at `cursor.pos`, advancing the cursor in place.
  * @param {string} str
  * @param {{ pos: number }} cursor
- * @returns {number}
  */
 function decodeVLQ (str, cursor) {
   let result = 0
@@ -243,7 +240,6 @@ function templateBodyToRegExp (templateBody) {
  * Count 1-indexed line number for a character index in `content`.
  * @param {string} content
  * @param {number} endIndex
- * @returns {number}
  */
 function lineNumberForIndex (content, endIndex) {
   let line = 1

package/packages/datadog-plugin-cypress/src/support.js

@@ -16,10 +16,15 @@ let testManagementTests = {}
 let isImpactedTestsEnabled = false
 let isModifiedTest = false
 let isTestIsolationEnabled = false
+let isDynamicAtrEnabled = false
+let isTextTerminal = false
 let hasWarnedMissingBeforeEachTaskResult = false
 let hasWarnedMissingBeforeEachRetryResult = false
 // Array of test names that have been retried and the reason
 const retryReasonsByTestName = new Map()
+// Dynamic ATR computes the selected budget after the first attempt. Keep that result
+// in browser state and apply it when Cypress starts the retry runnable.
+const dynamicAtrRetryCountByTest = new Map()
 // Track test errors suppressed by test management so we can still report them to Datadog.
 const suppressedTestFailures = new Map()
 
@@ -93,7 +98,6 @@ function getTestProperties (testName) {
 
 /**
  * @param {string} message
- * @returns {void}
  */
 function warnMissingBeforeEachTaskResult (message) {
   // eslint-disable-next-line no-console
@@ -192,7 +196,6 @@ function setRumCorrelationCookie (traceId) {
 
 /**
  * @param {boolean} isCookieSet
- * @returns {void}
  */
 function restartRumSession (isCookieSet) {
   if (!isCookieSet || isTestIsolationEnabled || !originalWindow) {
@@ -362,20 +365,47 @@ Cypress.mocha.getRunner().runTests = function (suite, fn) {
   return oldRunTests.apply(this, [suite, fn])
 }
 
-Cypress.on('test:before:run', (attributes, test) => {
+/**
+ * @param {{ id: string }} test
+ */
+function getDynamicAtrTestKey (test) {
+  // Cypress preserves the runnable ID when cloning a retry, including across browser reloads.
+  return `${Cypress.mocha.getRootSuite().file}\0${test.id}`
+}
+
+/**
+ * @param {{ id: string, _retries: number }} test
+ */
+function configureTestRetries (test) {
   if (shouldDisableFrameworkRetries(test)) {
     disableFrameworkRetries(test)
+    return
+  }
+
+  if (!isTextTerminal) return
+
+  const dynamicAtrRetryCount = dynamicAtrRetryCountByTest.get(getDynamicAtrTestKey(test))
+  if (Number.isSafeInteger(dynamicAtrRetryCount)) {
+    test._retries = dynamicAtrRetryCount
+  } else if (isDynamicAtrEnabled) {
+    // Cypress forbids calling retries(count) on the original runnable.
+    // Ensure local retries: 0 overrides still reach the duration-based budget selection.
+    test._retries = Math.max(1, test._retries)
   }
+}
+
+Cypress.on('test:before:run', (attributes, test) => {
+  configureTestRetries(test)
 })
 
 Cypress.on('test:before:run:async', (attributes, test) => {
-  if (shouldDisableFrameworkRetries(test)) {
-    disableFrameworkRetries(test)
-  }
+  configureTestRetries(test)
 })
 
 beforeEach(function () {
   const currentTest = Cypress.mocha.getRunner().suite.ctx.currentTest
+  // The first test:before:run event can precede the suite configuration task.
+  configureTestRetries(currentTest)
   const testName = currentTest.fullTitle()
 
   const retryMessage = retryReasonsByTestName.get(testName)
@@ -427,6 +457,7 @@ before(function () {
   cy.task('dd:testSuiteStart', {
     testSuite: Cypress.mocha.getRootSuite().file,
     testSuiteAbsolutePath: Cypress.spec && Cypress.spec.absolute,
+    isTextTerminal: Cypress.config('isTextTerminal'),
   }).then((suiteConfig) => {
     if (suiteConfig) {
       isEarlyFlakeDetectionEnabled = suiteConfig.isEarlyFlakeDetectionEnabled
@@ -439,6 +470,12 @@ before(function () {
       isImpactedTestsEnabled = suiteConfig.isImpactedTestsEnabled
       isModifiedTest = suiteConfig.isModifiedTest
       isTestIsolationEnabled = suiteConfig.isTestIsolationEnabled
+      isDynamicAtrEnabled = suiteConfig.isDynamicAtrEnabled
+      isTextTerminal = suiteConfig.isTextTerminal
+      if (isDynamicAtrEnabled && isTextTerminal) {
+        // The first test event can precede this task, and an earlier user hook can skip our beforeEach.
+        Cypress.mocha.getRootSuite().eachTest(configureTestRetries)
+      }
       rumTestExecutionIdCookieName = suiteConfig.rumTestExecutionIdCookieName
       if (Number.isFinite(suiteConfig.rumFlushWaitMillis)) {
         rumFlushWaitMillis = suiteConfig.rumFlushWaitMillis
@@ -448,6 +485,7 @@ before(function () {
 })
 
 after(() => {
+  dynamicAtrRetryCountByTest.clear()
   try {
     if (safeGetRum(originalWindow)) {
       originalWindow.dispatchEvent(new Event('beforeunload'))
@@ -475,6 +513,7 @@ afterEach(function () {
     : currentTest.err
 
   const testInfo = {
+    testId: currentTest.id,
     testName,
     testItTitle: currentTest.title,
     testSuite: Cypress.mocha.getRootSuite().file,
@@ -522,5 +561,11 @@ afterEach(function () {
     suppressedTestFailures.delete(testName)
   }
 
-  cy.task('dd:afterEach', { test: testInfo, coverage, commands: commandsToReport })
+  cy.task('dd:afterEach', { test: testInfo, coverage, commands: commandsToReport }).then((taskResult) => {
+    // Preserve the first-attempt result until Cypress starts the retry runnable.
+    // Changing the completed test here is too late for Cypress's retry lifecycle.
+    if (taskResult && Number.isSafeInteger(taskResult.dynamicAtrRetryCount)) {
+      dynamicAtrRetryCountByTest.set(getDynamicAtrTestKey(currentTest), taskResult.dynamicAtrRetryCount)
+    }
+  })
 })

package/packages/datadog-plugin-graphql/src/resolve-error.js

@@ -62,7 +62,7 @@ class GraphQLToolsResolveErrorPlugin extends TracingPlugin {
  */
 function recordResolveErrorForPath (error, path, fieldNodes) {
   const rootCtx = legacyStorage.getStore()?.graphqlRootCtx
-  if (!rootCtx?.config.collapse || !rootCtx.fields) return
+  if (!rootCtx?.config?.collapse || !rootCtx.fields) return
 
   const field = findResolveField(rootCtx.fields, getPathString(path), fieldNodes?.[0])
   if (field) recordResolveError(field, error)
@@ -70,7 +70,6 @@ function recordResolveErrorForPath (error, path, fieldNodes) {
 
 /**
  * @param {(string | number)[]} path
- * @returns {string}
  */
 function getPathString (path) {
   let pathString = ''

package/packages/datadog-plugin-graphql/src/utils.js

@@ -54,7 +54,6 @@ function getRequestCache (owner, configuredLimit) {
 /**
  * @param {string | null | undefined} operationName
  * @param {boolean} calculateSignature
- * @returns {string}
  */
 function operationCacheKey (operationName, calculateSignature) {
   return `${calculateSignature === false ? 0 : 1}\n${operationName ?? ''}`
@@ -309,7 +308,6 @@ const HEALTH_CHECK_QUERY = 'query __ApolloServiceHealthCheck__ { __typename }'
  * Matches the raw query string before it is parsed (the only input parse has).
  *
  * @param {unknown} source Raw query string or a graphql `Source` body.
- * @returns {boolean}
  */
 function isApolloHealthCheckSource (source) {
   return source === HEALTH_CHECK_QUERY
@@ -319,7 +317,6 @@ function isApolloHealthCheckSource (source) {
  * Matches Apollo's parsed health-check operation exactly for cached documents.
  *
  * @param {import('graphql').OperationDefinitionNode | undefined} operation
- * @returns {boolean}
  */
 function isApolloHealthCheck (operation) {
   const selections = operation?.selectionSet?.selections
@@ -342,7 +339,6 @@ function isApolloHealthCheck (operation) {
 
 /**
  * @param {import('graphql').GraphQLOutputType} type
- * @returns {string}
  */
 function getBaseTypeName (type) {
   let current = type
@@ -357,7 +353,6 @@ let tools
  * @param {string | undefined} operationName
  * @param {import('graphql').OperationTypeNode} operationType
  * @param {boolean} [calculate]
- * @returns {string}
  */
 function getSignature (document, operationName, operationType, calculate) {
   if (calculate !== false && tools !== false) {

package/packages/datadog-plugin-jest/src/index.js

@@ -41,6 +41,7 @@ const {
   TEST_HAS_FAILED_ALL_RETRIES,
   TEST_RETRY_REASON_TYPES,
   TEST_IS_MODIFIED,
+  setExpectedEmptyTestSessionTags,
 } = require('../../dd-trace/src/plugins/util/test')
 const { COMPONENT } = require('../../dd-trace/src/constants')
 const id = require('../../dd-trace/src/id')
@@ -116,12 +117,21 @@ class JestPlugin extends CiPlugin {
       isEarlyFlakeDetectionEnabled,
       isEarlyFlakeDetectionFaulty,
       isTestManagementTestsEnabled,
+      testSessionEmptyReason,
       onDone,
     }) => {
       const finishSession = () => {
         this.testSessionSpan.setTag(TEST_STATUS, status)
         this.testModuleSpan.setTag(TEST_STATUS, status)
 
+        if (testSessionEmptyReason) {
+          setExpectedEmptyTestSessionTags(
+            this.testSessionSpan,
+            this.testModuleSpan,
+            testSessionEmptyReason
+          )
+        }
+
         if (error) {
           this.testSessionSpan.setTag('error', error)
           this.testModuleSpan.setTag('error', error)
@@ -204,6 +214,8 @@ class JestPlugin extends CiPlugin {
         config._ddIsTestManagementTestsEnabled = this.libraryConfig?.isTestManagementEnabled ?? false
         config._ddTestManagementAttemptToFixRetries = this.libraryConfig?.testManagementAttemptToFixRetries ?? 0
         config._ddFlakyTestRetriesCount = this.libraryConfig?.flakyTestRetriesCount
+        config._ddIsDynamicAtrEnabled = this.libraryConfig?.isDynamicAtrEnabled ?? false
+        config._ddDynamicAtrBuckets = this.libraryConfig?.dynamicAtrBuckets
         config._ddIsDiEnabled = this.libraryConfig?.isDiEnabled ?? false
         config._ddIsKnownTestsEnabled = this.libraryConfig?.isKnownTestsEnabled ?? false
         config._ddIsImpactedTestsEnabled = this.libraryConfig?.isImpactedTestsEnabled ?? false

package/packages/datadog-plugin-kafkajs/src/producer.js

@@ -58,7 +58,6 @@ class KafkajsProducerPlugin extends ProducerPlugin {
   /**
    *
    * @param {{ result: ProducerResponseItem[] }} ctx
-   * @returns {void}
    */
   commit (ctx) {
     const commitList = ctx.result

package/packages/datadog-plugin-mocha/src/index.js

@@ -12,6 +12,9 @@ const {
   getEfdRetryCountForDuration,
   hasEfdRetries,
 } = require('../../dd-trace/src/ci-visibility/efd-retry-policy')
+const {
+  getDynamicAtrRetryCount,
+} = require('../../dd-trace/src/ci-visibility/dynamic-atr-retries')
 const {
   SCREENSHOT_UPLOAD_RESULT_ERROR,
   SCREENSHOT_UPLOAD_RESULT_UPLOADED,
@@ -65,6 +68,7 @@ const {
   TEST_BROWSER_NAME,
   TEST_BROWSER_VERSION,
   TEST_IS_RUM_ACTIVE,
+  setExpectedEmptyTestSessionTags,
 } = require('../../dd-trace/src/plugins/util/test')
 const { COMPONENT } = require('../../dd-trace/src/constants')
 const {
@@ -184,7 +188,6 @@ function setWebdriverioRumTestCorrelation (context, activeSpan) {
  * Converts a screenshot capture failure into its upload result.
  *
  * @param {unknown} error
- * @returns {string}
  */
 function handleWebdriverioScreenshotError (error) {
   log.error('Error capturing WebdriverIO failure screenshot: %s', error?.message || String(error))
@@ -882,6 +885,7 @@ class MochaPlugin extends CiPlugin {
       isTestManagementEnabled,
       isParallel,
       isFrameworkError,
+      testSessionEmptyReason,
       onDone,
     }) => {
       this._exportPendingWorkerTraces()
@@ -894,6 +898,14 @@ class MochaPlugin extends CiPlugin {
         this.testSessionSpan.setTag(TEST_STATUS, status)
         this.testModuleSpan.setTag(TEST_STATUS, status)
 
+        if (testSessionEmptyReason) {
+          setExpectedEmptyTestSessionTags(
+            this.testSessionSpan,
+            this.testModuleSpan,
+            testSessionEmptyReason
+          )
+        }
+
         if (error) {
           this.testSessionSpan.setTag('error', error)
           this.testModuleSpan.setTag('error', error)
@@ -1027,7 +1039,17 @@ class MochaPlugin extends CiPlugin {
     } else if (isEarlyFlakeDetection) {
       retryCount = this.libraryConfig.earlyFlakeDetectionRetryPolicy.schedulingRetryCount
     } else if (isAtr) {
-      retryCount = this.libraryConfig.flakyTestRetriesCount
+      // When dynamic ATR is enabled, use the max bucket value as the initial count.
+      // The actual duration-based count is computed after the first attempt.
+      if (this.libraryConfig.isDynamicAtrEnabled) {
+        const maximumDynamicAtrRetries = this.libraryConfig.dynamicAtrBuckets
+          ? Math.max(...this.libraryConfig.dynamicAtrBuckets)
+          : this.libraryConfig.earlyFlakeDetectionRetryPolicy.schedulingRetryCount
+        // Dynamic ATR guarantees one retry, including the >5m EFD fallback bucket.
+        retryCount = Math.max(1, maximumDynamicAtrRetries)
+      } else {
+        retryCount = this.libraryConfig.flakyTestRetriesCount
+      }
     }
 
     const test = {
@@ -1041,6 +1063,7 @@ class MochaPlugin extends CiPlugin {
       isAttemptToFix,
       isAtr,
       isDisabled,
+      isDynamicAtr: isAtr && this.libraryConfig?.isDynamicAtrEnabled,
       isEarlyFlakeDetection,
       isModified,
       isNew,
@@ -1090,7 +1113,6 @@ class MochaPlugin extends CiPlugin {
    *
    * @param {object} test
    * @param {object|undefined} parentStore
-   * @returns {void}
    */
   #startWebdriverioJasmineAttempt (test, parentStore) {
     test.attemptStart = performance.now()
@@ -1121,7 +1143,6 @@ class MochaPlugin extends CiPlugin {
    * Delays Jasmine's parent runner until every Datadog-managed spec execution has completed.
    *
    * @param {object} context
-   * @returns {void}
    */
   #configureWebdriverioJasmineLifecycle (context) {
     const isLegacyJasmine = Boolean(context.self?.queueableFn)
@@ -1215,6 +1236,19 @@ class MochaPlugin extends CiPlugin {
       }
     }
 
+    // Dynamic ATR: after the first attempt, compute the duration-based retry budget.
+    if (
+      testStatus !== 'skip' &&
+      test.isDynamicAtr &&
+      test.attempt === 0
+    ) {
+      test.retryCount = getDynamicAtrRetryCount(
+        performance.now() - test.attemptStart,
+        this.libraryConfig.earlyFlakeDetectionRetryPolicy,
+        this.libraryConfig.dynamicAtrBuckets
+      )
+    }
+
     const hasManagedRetry = testStatus !== 'skip' && test.attempt < test.retryCount
     test.willRetry = hasManagedRetry && (
       test.isAttemptToFix ||
@@ -1250,7 +1284,6 @@ class MochaPlugin extends CiPlugin {
    *
    * @param {object} test
    * @param {WebdriverioJasmineResult} result
-   * @returns {void}
    */
   #finishWebdriverioJasmineRetry (test, result) {
     const status = getJasmineStatus(test.reportedStatus || result.status)
@@ -1290,7 +1323,6 @@ class MochaPlugin extends CiPlugin {
    * Advances a Jasmine test and starts its next attempt span.
    *
    * @param {object} test
-   * @returns {void}
    */
   #startNextWebdriverioJasmineAttempt (test) {
     test.attempt++
@@ -1404,7 +1436,6 @@ class MochaPlugin extends CiPlugin {
    *
    * @param {object} test
    * @param {WebdriverioJasmineResult} result
-   * @returns {void}
    */
   #completeWebdriverioJasmineTest (test, result) {
     const state = this._webdriverioJasmineState
@@ -1460,7 +1491,6 @@ class MochaPlugin extends CiPlugin {
    *
    * @param {object} span - Failed test span
    * @param {() => void} [onDone] - Called after the screenshot upload finishes
-   * @returns {boolean} Whether a screenshot upload exists for the span
    */
   #startWebdriverioScreenshotUpload (span, onDone) {
     if (
@@ -1547,7 +1577,6 @@ class MochaPlugin extends CiPlugin {
    * @param {object} span - Failed test span
    * @param {{callbacks: Array<() => void>, finished: boolean}} upload - Upload state
    * @param {string} result - Aggregate screenshot upload result
-   * @returns {void}
    */
   #finishWebdriverioScreenshotUpload (span, upload, result) {
     if (upload.finished) return
@@ -1577,7 +1606,6 @@ class MochaPlugin extends CiPlugin {
    * @param {object} span - Failed test span
    * @param {string|string[]} screenshots - Base64-encoded PNG data
    * @param {(result: string) => void} onDone - Aggregate upload completion callback
-   * @returns {void}
    */
   #uploadWebdriverioScreenshots (span, screenshots, onDone) {
     const screenshotList = Array.isArray(screenshots) ? screenshots : [screenshots]
@@ -1647,7 +1675,6 @@ class MochaPlugin extends CiPlugin {
    *   resolveCallback?: (onDone: () => void) => void,
    *   rejectCallback?: (onDone: () => void) => void
    * }} context
-   * @returns {void}
    */
   #finishWebdriverioJasmineWorker (context) {
     const state = this._webdriverioJasmineState

package/packages/datadog-plugin-mongodb-core/src/query.js

@@ -206,7 +206,6 @@ const REDACT_LEAF = '"?"'
 
 /**
  * @param {RegExp} value
- * @returns {string}
  */
 function stringifyRegExp (value) {
   return `{"$regex":${JSON.stringify(value.source)},"$options":${JSON.stringify(value.flags)}}`

package/packages/datadog-plugin-openai/src/index.js

@@ -2,15 +2,30 @@
 
 const CompositePlugin = require('../../dd-trace/src/plugins/composite')
 const OpenAiLLMObsPlugin = require('../../dd-trace/src/llmobs/plugins/openai')
+const OpenAiRealtimeLLMObsPlugins = require('../../dd-trace/src/llmobs/plugins/openai/realtime')
+const OpenAiRealtimeTracingPlugins = require('./realtime')
 const OpenAiTracingPlugin = require('./tracing')
 
 class OpenAiPlugin extends CompositePlugin {
   static id = 'openai'
   static get plugins () {
-    return {
+    const plugins = {
       llmobs: OpenAiLLMObsPlugin,
       tracing: OpenAiTracingPlugin,
     }
+
+    // LLM Obs plugins must be registered before their tracing counterparts so that annotations are
+    // added to the span before it finishes: subscribers run in registration order, and the realtime
+    // tracing plugins finish their span in `end`.
+    for (const Plugin of OpenAiRealtimeLLMObsPlugins) {
+      plugins[Plugin.id] = Plugin
+    }
+
+    for (const Plugin of OpenAiRealtimeTracingPlugins) {
+      plugins[Plugin.id] = Plugin
+    }
+
+    return plugins
   }
 }
 

package/packages/datadog-plugin-openai/src/realtime.js

@@ -0,0 +1,144 @@
+'use strict'
+
+const { MEASURED } = require('../../../ext/tags')
+const { ERROR_MESSAGE, ERROR_TYPE } = require('../../dd-trace/src/constants')
+const { storage } = require('../../datadog-core')
+const TracingPlugin = require('../../dd-trace/src/plugins/tracing')
+
+/**
+ * APM spans for the phases of one OpenAI Realtime turn.
+ *
+ * The turn is replayed as a back-dated tree once it is complete, so every span here is created with
+ * an explicit `startTime` and finished with an explicit `finishTime` rather than measuring wall
+ * clock. Nesting falls out of the synchronous scoping of the instrumentation's `traceSync` calls:
+ * the phase spans are created inside the turn root's callback, so `startSpan` picks the root up as
+ * their parent from the active store.
+ */
+class RealtimeTracingPlugin extends TracingPlugin {
+  // `component` defaults to the plugin id, which differs per phase here, so pin both explicitly to
+  // keep `component:openai` consistent with every other span the integration emits.
+  static component = 'openai'
+  static system = 'openai'
+
+  /**
+   * Whether a failed response marks this span errored. True for the model's own work and for the
+   * turn as a whole; false for the speaking windows, which describe when audio moved rather than
+   * whether the model succeeded.
+   */
+  static flagsFailure = true
+
+  /**
+   * The APM resource name for this phase. Implemented by every subclass.
+   *
+   * @param {object} ctx
+   * @throws {Error} When a subclass has not implemented it.
+   */
+  resource (ctx) {
+    throw new Error(`resource must be implemented by ${this.constructor.name}`)
+  }
+
+  /**
+   * @param {object} ctx
+   * @returns {object}
+   */
+  bindStart (ctx) {
+    this.startSpan('openai.request', {
+      service: this.config.service,
+      resource: this.resource(ctx),
+      type: 'openai',
+      kind: 'client',
+      meta: {
+        [MEASURED]: 1,
+        'openai.request.model': ctx.turn.model,
+      },
+      startTime: ctx.startTime,
+    }, ctx)
+
+    return ctx.currentStore
+  }
+
+  /**
+   * @param {object} ctx
+   */
+  end (ctx) {
+    const span = ctx.currentStore?.span
+    if (span === undefined) return
+
+    if (ctx.turn.failed && this.constructor.flagsFailure) {
+      span.setTag('error', 1)
+
+      // The provider's own account of the failure, when `response.done` carried one. Without it the
+      // span says only that a realtime call broke. The LLM Observability error event reads these
+      // same tags, so setting them here serves both.
+      const { error } = ctx.turn
+      if (error !== undefined) {
+        if (error.type !== undefined) span.setTag(ERROR_TYPE, error.type)
+        const message = error.message ?? error.code
+        if (message !== undefined) span.setTag(ERROR_MESSAGE, message)
+      }
+    }
+    span.finish(ctx.finishTime)
+  }
+}
+
+/** The whole perceived turn, and the root of this turn's trace. */
+class RealtimeTurnTracingPlugin extends RealtimeTracingPlugin {
+  static id = 'openai_realtime_turn'
+  static operation = 'turn'
+  static prefix = 'tracing:apm:openai:realtime:turn'
+
+  constructor (...args) {
+    super(...args)
+
+    // Captured at `response.created`, replayed at finalize: by then the active context belongs to
+    // the WebSocket message handler, not to the caller who opened the connection. The LLM
+    // Observability plugin composes its own store on top of whatever this sets.
+    this.addSub('dd-trace:openai:realtime:capture-context', turn => {
+      const store = storage('legacy').getStore()
+      const previous = turn.runInContext
+      turn.runInContext = previous === undefined
+        ? fn => storage('legacy').run(store, fn)
+        : fn => previous(() => storage('legacy').run(store, fn))
+    })
+  }
+
+  resource () {
+    return 'createRealtimeTurn'
+  }
+}
+
+/** The model's generation work: opens at the end of user speech, closes at `response.done`. */
+class RealtimeResponseTracingPlugin extends RealtimeTracingPlugin {
+  static id = 'openai_realtime_response'
+  static operation = 'response'
+  static prefix = 'tracing:apm:openai:realtime:response'
+
+  resource () {
+    return 'createRealtimeResponse'
+  }
+}
+
+/**
+ * A speaking window — the human's or the agent's. One plugin covers both: they differ only by
+ * resource and name, which is data, not a type.
+ */
+class RealtimeSpeechTracingPlugin extends RealtimeTracingPlugin {
+  static id = 'openai_realtime_speech'
+  static operation = 'speech'
+  static prefix = 'tracing:apm:openai:realtime:speech'
+  // A speaking window happened regardless of whether the model's response failed.
+  static flagsFailure = false
+
+  /**
+   * @param {{ phase: { operation: string } }} ctx
+   */
+  resource (ctx) {
+    return ctx.phase.operation
+  }
+}
+
+module.exports = [
+  RealtimeTurnTracingPlugin,
+  RealtimeResponseTracingPlugin,
+  RealtimeSpeechTracingPlugin,
+]

package/packages/datadog-plugin-openai-agents/src/integration.js

@@ -578,7 +578,6 @@ class OpenAIAgentsIntegration {
    *
    * @param {string | undefined | null} spanId agents-core spanId to start from
    * @param {string} ancestorId agents-core ancestor spanId
-   * @returns {boolean}
    */
   #hasUntracedPathToAncestor (spanId, ancestorId) {
     let currentId = spanId
@@ -596,7 +595,6 @@ class OpenAIAgentsIntegration {
    * mistaken for top-level, or an error would finalize the workflow span early.
    *
    * @param {object} oaiSpan
-   * @returns {boolean}
    */
   #isTopLevelSpan (oaiSpan) {
     let currentId = oaiSpan.parentId
@@ -681,7 +679,6 @@ class OpenAIAgentsIntegration {
    * Read the mutable tracer configuration so remote/runtime enablement is
    * reflected without reconstructing the plugin.
    *
-   * @returns {boolean}
    */
   #isLLMObsEnabled () {
     return this.#llmobsEnabled && !!this.#config.llmobs?.DD_LLMOBS_ENABLED
@@ -690,7 +687,6 @@ class OpenAIAgentsIntegration {
   /**
    * Resolve model provider from the model invocation's async-local context.
    *
-   * @returns {string}
    */
   #getCurrentModelProvider () {
     const baseURL = legacyStorage.getStore()?.[MODEL_BASE_URL_STORE_KEY]