dd-trace 5.116.0 → 5.118.0

package/packages/datadog-instrumentations/src/vitest-util.js

@@ -39,12 +39,6 @@ function findExportByName (pkg, name) {
   }
 }
 
-function getChannelPromise (channelToPublishTo, frameworkVersion, payload) {
-  return new Promise(resolve => {
-    channelToPublishTo.publish({ ...payload, onDone: resolve, frameworkVersion })
-  })
-}
-
 function getTestRunnerExport (testPackage) {
   return findExportByName(testPackage, 'VitestTestRunner') || findExportByName(testPackage, 'TestRunner')
 }
@@ -239,7 +233,6 @@ module.exports = {
   workerReportLogsCh,
   codeCoverageReportCh,
   findExportByName,
-  getChannelPromise,
   getTestRunnerExport,
   getTypeTasks,
   getTestName,

package/packages/datadog-instrumentations/src/vitest-worker.js

@@ -9,6 +9,7 @@ const {
   recordAttemptToFixExecution,
   logAttemptToFixTestExecution,
 } = require('../../dd-trace/src/plugins/util/test')
+const { getChannelPromise } = require('./helpers/channel')
 const { addHook } = require('./helpers/instrument')
 const {
   testStartCh,
@@ -661,11 +662,6 @@ addHook({
     testSuiteStartCh.runStores(testSuiteCtx, () => {})
     const startTestsResponse = await startTests.apply(this, arguments)
 
-    let onFinish = null
-    const onFinishPromise = new Promise(resolve => {
-      onFinish = resolve
-    })
-
     const testTasks = getTypeTasks(startTestsResponse[0].tasks)
     const testEventPromises = []
 
@@ -811,9 +807,10 @@ addHook({
       testSuiteErrorCh.runStores(testSuiteCtx, () => {})
     }
 
-    testSuiteFinishCh.publish({ status: testSuiteResult.state, onFinish, ...testSuiteCtx.currentStore })
-
-    await onFinishPromise
+    await getChannelPromise(testSuiteFinishCh, {
+      status: testSuiteResult.state,
+      ...testSuiteCtx.currentStore,
+    })
 
     return startTestsResponse
   })

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

@@ -72,6 +72,7 @@ class CucumberPlugin extends CiPlugin {
       isEarlyFlakeDetectionFaulty,
       isTestManagementTestsEnabled,
       isParallel,
+      onDone,
     }) => {
       this._exportPendingWorkerTraces()
       const {
@@ -127,7 +128,7 @@ class CucumberPlugin extends CiPlugin {
       })
 
       this.libraryConfig = null
-      this.tracer._exporter.flush()
+      this.tracer._exporter.flush(onDone)
     })
 
     this.addSub('ci:cucumber:test-suite:start', ({

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

@@ -390,6 +390,7 @@ class MochaPlugin extends CiPlugin {
       isEarlyFlakeDetectionFaulty,
       isTestManagementEnabled,
       isParallel,
+      onDone,
     }) => {
       this._exportPendingWorkerTraces()
       if (this.testSessionSpan) {
@@ -456,7 +457,7 @@ class MochaPlugin extends CiPlugin {
         })
       }
       this.libraryConfig = null
-      this.tracer._exporter.flush()
+      this.tracer._exporter.flush(onDone)
     })
 
     this.addBind('ci:mocha:global:run', (ctx) => {

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

@@ -0,0 +1,74 @@
+'use strict'
+
+const { storage } = require('../../datadog-core')
+const Plugin = require('../../dd-trace/src/plugins/plugin')
+const { MODEL_BASE_URL_STORE_KEY, OpenAIAgentsIntegration } = require('./integration')
+const { DDOpenAIAgentsProcessor } = require('./processor')
+
+const legacyStorage = storage('legacy')
+
+/**
+ * Drives the openai-agents integration through agents-core's
+ * `TracingProcessor` interface. The instrumentation hook publishes the
+ * loaded `@openai/agents` module on a channel; this plugin subscribes
+ * during its constructor (which runs synchronously between `loadChannel`'s
+ * publish and the addHook callback) and registers the processor.
+ *
+ * The integration's `enabled` flag follows this plugin's configure()
+ * lifecycle. Each loaded version of the agents package replaces all processors
+ * via setTraceProcessors() on module load, so the plugin re-registers a
+ * fresh DDOpenAIAgentsProcessor for each module version that fires the channel.
+ */
+class OpenaiAgentsPlugin extends Plugin {
+  static id = 'openai-agents'
+
+  #integration
+
+  constructor (tracer, tracerConfig) {
+    super(tracer, tracerConfig)
+    this.#integration = new OpenAIAgentsIntegration({
+      tracer: this.tracer,
+      config: tracerConfig,
+    })
+
+    // Register a new processor each time @openai/agents fires the channel.
+    // Each module version calls setTraceProcessors() on load (which replaces
+    // all processors), so we must re-register after every new version loads.
+    // The instrumentation's patchedMods WeakSet ensures each module instance
+    // fires the channel exactly once, so no duplicates accumulate.
+    this.addSub('apm:openai-agents:agents-core:loaded', ({ mod }) => {
+      const processor = new DDOpenAIAgentsProcessor(() => this.#integration)
+      if (typeof mod?.addTraceProcessor === 'function') {
+        mod.addTraceProcessor(processor)
+      } else {
+        mod.getGlobalTraceProvider().registerProcessor(processor)
+      }
+    })
+
+    // Activate the current agent's dd-trace span in legacyStorage for the
+    // duration of model response calls and stream iterator advancement. This
+    // makes the openai plugin's shimmer see the correct parent when it creates its
+    // openai.request span, so all spans land in the same trace.
+    this.addBind('apm:openai-agents:model:start', ({ agentsCoreSpanId, baseURL }) => {
+      const store = legacyStorage.getStore()
+      if (!this.#integration.enabled || !agentsCoreSpanId) return store
+      const ddSpan = this.#integration.getDDSpan(agentsCoreSpanId)
+      if (!ddSpan) return store
+      return { ...store, [MODEL_BASE_URL_STORE_KEY]: baseURL, span: ddSpan }
+    })
+
+    this.addBind('apm:openai-agents:tool:start', ({ agentsCoreSpan }) => {
+      const store = legacyStorage.getStore()
+      if (!this.#integration.enabled || !agentsCoreSpan) return store
+      const ddSpan = this.#integration.getOrStartToolSpan(agentsCoreSpan)
+      return ddSpan ? { ...store, span: ddSpan } : store
+    })
+  }
+
+  configure (config) {
+    super.configure(config)
+    this.#integration.configure(config)
+  }
+}
+
+module.exports = OpenaiAgentsPlugin

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

@@ -0,0 +1,503 @@
+'use strict'
+
+const { storage } = require('../../datadog-core')
+const { storage: llmobsStorage } = require('../../dd-trace/src/llmobs/storage')
+const LLMObsTagger = require('../../dd-trace/src/llmobs/tagger')
+const { getOpenAIModelProvider } = require('../../dd-trace/src/llmobs/plugins/openai/utils')
+const {
+  extractInputMessages,
+  extractOutputMessages,
+  extractGenerationOutputMessages,
+  extractMetrics,
+  extractMetadata,
+} = require('../../dd-trace/src/llmobs/plugins/openai-agents/utils')
+const { AGENTS_ERROR_TYPE, applyError, deriveSpanName } = require('./util')
+
+const COMPONENT = 'openai-agents'
+const DEFAULT_MODEL_PROVIDER = 'openai'
+const MODEL_BASE_URL_STORE_KEY = Symbol('openai-agents.model-base-url')
+const legacyStorage = storage('legacy')
+
+const KIND_TO_SPAN_KIND = {
+  agent: 'internal',
+  tool: 'internal',
+  task: 'internal',
+  llm: 'client',
+}
+
+/**
+ * @typedef {{
+ *   spanId: string,
+ *   traceId: string,
+ *   currentTopLevelAgentSpanId?: string,
+ *   currentTopLevelAgentName?: string,
+ *   inputOaiSpan?: object,
+ *   inputMessages?: Array<{ role: string, content: string }>,
+ *   outputOaiSpan?: object,
+ *   metadata?: Record<string, unknown>,
+ *   groupId?: string,
+ *   llmobsParentStore?: object,
+ * }} LLMObsTraceInfo
+ */
+
+/**
+ * Owns tracer/tagger refs, maps agents-core span ids → dd-trace spans, and
+ * reconstructs workflow-level input/output from the first and last response
+ * spans of the top-level agent.
+ */
+class OpenAIAgentsIntegration {
+  #tracer
+  #config
+  #enabled = false
+  #service
+  /**
+   * LLMObs is gated independently of APM tracing: when DD_LLMOBS_ENABLED is
+   * false we keep emitting APM spans for the agent workflow but skip all
+   * LLMObs tagging and the work that feeds it.
+   * @type {LLMObsTagger}
+   */
+  #tagger
+  /** @type {Map<string, import('../../dd-trace/src/opentracing/span')>} */
+  #oaiToDdSpan = new Map()
+  /** @type {Map<string, LLMObsTraceInfo>} */
+  #traceInfo = new Map()
+
+  constructor ({ tracer, config } = {}) {
+    this.#tracer = tracer
+    this.#config = config ?? { llmobs: {} }
+    this.#tagger = new LLMObsTagger(this.#config, true)
+  }
+
+  get enabled () {
+    return this.#enabled
+  }
+
+  /**
+   * Apply plugin lifecycle configuration.
+   *
+   * @param {{ enabled?: boolean, service?: string }} [config]
+   */
+  configure (config) {
+    this.#enabled = !!config?.enabled
+    this.#service = config?.service
+  }
+
+  /**
+   * @param {string} spanId agents-core spanId
+   * @returns {import('../../dd-trace/src/opentracing/span') | undefined}
+   */
+  getDDSpan (spanId) {
+    return this.#oaiToDdSpan.get(spanId)
+  }
+
+  /**
+   * Ensure a function span is available synchronously at Tool.invoke. Newer
+   * agents-core versions dispatch processor callbacks after an async exporter
+   * callback, which can otherwise happen after user tool code has started.
+   *
+   * @param {object} oaiSpan
+   * @returns {import('../../dd-trace/src/opentracing/span') | undefined}
+   */
+  getOrStartToolSpan (oaiSpan) {
+    if (!oaiSpan?.spanId) return
+    const existingSpan = this.#oaiToDdSpan.get(oaiSpan.spanId)
+    if (existingSpan) return existingSpan
+    this.startSpan(oaiSpan, 'tool')
+    return this.#oaiToDdSpan.get(oaiSpan.spanId)
+  }
+
+  clearState () {
+    // Finish any dd-trace spans still in-flight so we don't leak open traces
+    // when agents-core's TracingProcessor.shutdown() runs (e.g., process
+    // exiting mid-run).
+    for (const ddSpan of this.#oaiToDdSpan.values()) {
+      ddSpan.finish()
+    }
+    this.#oaiToDdSpan.clear()
+    this.#traceInfo.clear()
+  }
+
+  // ── Trace lifecycle ─────────────────────────────────────────────────────────
+
+  startTrace (oaiTrace) {
+    const traceId = oaiTrace.traceId
+    if (!traceId) return
+
+    const name = oaiTrace.name || 'Agent workflow'
+    const parentSpan = legacyStorage.getStore()?.span
+    const ddSpan = this.#tracer.startSpan(name, {
+      childOf: parentSpan,
+      tags: this.#getSpanTags('internal'),
+    })
+
+    const llmobsParentStore = this.#isLLMObsEnabled() ? llmobsStorage.getStore() : undefined
+    this.#oaiToDdSpan.set(traceId, ddSpan)
+    this.#traceInfo.set(traceId, {
+      spanId: ddSpan.context().toSpanId(),
+      traceId,
+      groupId: oaiTrace.groupId || undefined,
+      metadata: oaiTrace.metadata,
+      llmobsParentStore,
+    })
+
+    this.#tagger.registerLLMObsSpan(ddSpan, {
+      kind: 'workflow',
+      name,
+      integration: COMPONENT,
+      parent: llmobsParentStore?.span,
+      sessionId: oaiTrace.groupId || undefined,
+    })
+    if (LLMObsTagger.tagMap.has(ddSpan)) {
+      llmobsStorage.enterWith({ ...llmobsParentStore, span: ddSpan })
+    }
+  }
+
+  endTrace (oaiTrace) {
+    this.#completeWorkflowSpan(oaiTrace.traceId)
+  }
+
+  /**
+   * Finish the workflow dd-trace span and clear its bookkeeping. Used by both
+   * agents-core's normal `Trace.end()` path and the orphan-recovery path
+   * (when `withTrace` skips its end callback because the body threw). When
+   * `rootAgentSpan` is provided, its `error` field is reflected onto the
+   * workflow span before finishing.
+   *
+   * @param {string | undefined} traceId
+   * @param {object} [rootAgentSpan] - parentless oai-span that ended in error.
+   */
+  #completeWorkflowSpan (traceId, rootAgentSpan) {
+    if (!traceId) return
+    const ddSpan = this.#oaiToDdSpan.get(traceId)
+    if (!ddSpan) return
+    const info = this.#traceInfo.get(traceId)
+
+    if (rootAgentSpan?.error) {
+      ddSpan.setTag('error', true)
+      ddSpan.setTag('error.type', AGENTS_ERROR_TYPE)
+      if (rootAgentSpan.error.message) {
+        ddSpan.setTag('error.message', rootAgentSpan.error.message)
+      }
+    }
+
+    if (this.#isLLMObsEnabled()) this.#setTraceAttributes(ddSpan, traceId)
+    ddSpan.finish()
+    if (info && LLMObsTagger.tagMap.has(ddSpan)) {
+      llmobsStorage.enterWith(info.llmobsParentStore)
+    }
+    this.#oaiToDdSpan.delete(traceId)
+    this.#traceInfo.delete(traceId)
+  }
+
+  // ── Span lifecycle ──────────────────────────────────────────────────────────
+
+  startSpan (oaiSpan, llmobsKind) {
+    const spanId = oaiSpan.spanId
+    if (!spanId || this.#oaiToDdSpan.has(spanId)) return
+
+    const parentSpan = this.#resolveParent(oaiSpan)
+    const spanName = deriveSpanName(oaiSpan)
+
+    const ddSpan = this.#tracer.startSpan(spanName, {
+      childOf: parentSpan,
+      tags: this.#getSpanTags(KIND_TO_SPAN_KIND[llmobsKind] ?? 'internal'),
+    })
+
+    this.#oaiToDdSpan.set(spanId, ddSpan)
+
+    if (this.#isLLMObsEnabled()) {
+      const llmobsOptions = {
+        kind: llmobsKind,
+        name: spanName,
+        integration: COMPONENT,
+        parent: parentSpan,
+      }
+
+      if (oaiSpan.spanData?.type === 'response' || oaiSpan.spanData?.type === 'generation') {
+        // Model name only arrives with the response; tagged in
+        // `#setResponseAttributes` once known. Model provider is resolved from
+        // the agents-openai client's baseURL captured at getResponse time.
+        llmobsOptions.modelProvider = this.#getCurrentModelProvider()
+      }
+
+      this.#tagger.registerLLMObsSpan(ddSpan, llmobsOptions)
+      this.#updateTraceInfoInput(oaiSpan, spanName)
+    }
+  }
+
+  endSpan (oaiSpan) {
+    const spanId = oaiSpan.spanId
+    const ddSpan = this.#oaiToDdSpan.get(spanId)
+    if (!ddSpan) return
+
+    applyError(ddSpan, oaiSpan)
+
+    if (oaiSpan.spanData?.type === 'handoff') {
+      const spanName = deriveSpanName(oaiSpan)
+      ddSpan.setOperationName(spanName)
+      if (this.#isLLMObsEnabled()) this.#tagger.setName(ddSpan, spanName)
+    }
+
+    if (this.#isLLMObsEnabled()) {
+      const spanData = oaiSpan.spanData
+      switch (spanData?.type) {
+        case 'response':
+          this.#setResponseAttributes(ddSpan, oaiSpan)
+          this.#updateTraceInfoOutput(oaiSpan)
+          break
+        case 'generation':
+          this.#setGenerationAttributes(ddSpan, oaiSpan)
+          this.#updateTraceInfoOutput(oaiSpan)
+          break
+        case 'function':
+          this.#tagger.tagTextIO(ddSpan, spanData.input ?? '', spanData.output ?? '')
+          break
+        case 'handoff':
+          this.#tagger.tagTextIO(ddSpan, spanData.from_agent ?? '', spanData.to_agent ?? '')
+          break
+        case 'agent':
+          this.#setAgentAttributes(ddSpan, oaiSpan)
+          break
+        case 'custom':
+          if (spanData.data && typeof spanData.data === 'object') {
+            this.#tagger.tagMetadata(ddSpan, spanData.data)
+          }
+          break
+      }
+    }
+
+    ddSpan.finish()
+    // agents-core's withTrace skips Trace.end() when its callback throws, so an
+    // errored parentless span is our last chance to finalize the workflow.
+    if (oaiSpan.parentId == null && oaiSpan.error) {
+      this.#completeWorkflowSpan(oaiSpan.traceId, oaiSpan)
+    }
+    this.#oaiToDdSpan.delete(spanId)
+  }
+
+  // ── Per-type attribute setters ──────────────────────────────────────────────
+
+  #setResponseAttributes (ddSpan, oaiSpan) {
+    const response = oaiSpan.spanData?._response
+    const input = oaiSpan.spanData?._input
+    if (response?.model) {
+      this.#tagger.tagModelName(ddSpan, response.model)
+    }
+
+    // Override the LLMObs span name to `{parent_agent_name} (LLM)` only when
+    // the response is a direct child of the top-level agent (Python parity:
+    // see `_llmobs_set_response_attributes` in dd-trace-py). For bare
+    // `withResponseSpan` calls outside a `Runner.run()` flow the default
+    // name (`openai_agents.response`) stays.
+    const parentAgentName = this.#llmSpanParentAgentName(oaiSpan)
+    if (parentAgentName) {
+      this.#tagger.setName(ddSpan, `${parentAgentName} (LLM)`)
+    }
+
+    // Always tag LLM I/O so the LLMObs event shape is consistent across
+    // happy/error paths. The extract* helpers emit placeholder messages
+    // when their source is absent.
+    const inputMessages = extractInputMessages(input, response?.instructions)
+    this.#tagger.tagLLMIO(ddSpan, inputMessages, extractOutputMessages(response))
+
+    // Cache messages for the workflow span's trace-level input (Python
+    // parity: last message of the first response under the top-level agent).
+    // Avoids re-running extractInputMessages in #setTraceAttributes.
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (info && info.inputOaiSpan === oaiSpan) {
+      info.inputMessages = inputMessages
+    }
+
+    if (response) {
+      const metrics = extractMetrics(response)
+      if (metrics) this.#tagger.tagMetrics(ddSpan, metrics)
+
+      const metadata = extractMetadata(response)
+      if (metadata) this.#tagger.tagMetadata(ddSpan, metadata)
+    }
+  }
+
+  /**
+   * Tag a Chat Completions generation span from agents-core's public span data.
+   *
+   * @param {import('../../dd-trace/src/opentracing/span')} ddSpan
+   * @param {object} oaiSpan
+   */
+  #setGenerationAttributes (ddSpan, oaiSpan) {
+    const spanData = oaiSpan.spanData
+    if (spanData?.model) {
+      this.#tagger.tagModelName(ddSpan, spanData.model)
+    }
+
+    const parentAgentName = this.#llmSpanParentAgentName(oaiSpan)
+    if (parentAgentName) {
+      this.#tagger.setName(ddSpan, `${parentAgentName} (LLM)`)
+    }
+
+    const inputMessages = extractInputMessages(spanData?.input)
+    this.#tagger.tagLLMIO(ddSpan, inputMessages, extractGenerationOutputMessages(spanData?.output))
+
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (info && info.inputOaiSpan === oaiSpan) {
+      info.inputMessages = inputMessages
+    }
+
+    const metrics = extractMetrics({
+      usage: spanData?.usage ?? spanData?.output?.at(-1)?.usage,
+    })
+    if (metrics) this.#tagger.tagMetrics(ddSpan, metrics)
+    if (spanData?.model_config) this.#tagger.tagMetadata(ddSpan, spanData.model_config)
+  }
+
+  /**
+   * If this response span's parent is the top-level agent span of the trace,
+   * return that agent's dd-trace span name. Used to set the LLMObs span name
+   * to `${agentName} (LLM)` (Python parity).
+   *
+   * @param {object} oaiSpan
+   * @returns {string | undefined}
+   */
+  #llmSpanParentAgentName (oaiSpan) {
+    const traceInfo = this.#traceInfo.get(oaiSpan.traceId)
+    if (!traceInfo?.currentTopLevelAgentSpanId) return
+    if (oaiSpan.parentId !== traceInfo.currentTopLevelAgentSpanId) return
+    return traceInfo.currentTopLevelAgentName
+  }
+
+  #setAgentAttributes (ddSpan, oaiSpan) {
+    const spanData = oaiSpan.spanData
+    let metadata
+    if (Array.isArray(spanData?.handoffs) && spanData.handoffs.length > 0) {
+      metadata = { handoffs: spanData.handoffs }
+    }
+    if (Array.isArray(spanData?.tools) && spanData.tools.length > 0) {
+      metadata ??= {}
+      metadata.tools = spanData.tools
+    }
+    if (spanData?.output_type) {
+      metadata ??= {}
+      metadata.output_type = spanData.output_type
+    }
+    if (metadata) this.#tagger.tagMetadata(ddSpan, metadata)
+  }
+
+  #setTraceAttributes (ddSpan, traceId) {
+    const info = this.#traceInfo.get(traceId)
+    if (!info) return
+
+    // Workflow-level input is the last input message of the first response
+    // span under the top-level agent; output is `response.output_text` of
+    // the last response span. Matches dd-trace-py's
+    // `OaiSpanAdapter.llmobs_trace_input` / `response_output_text`. The
+    // input messages were cached during #setResponseAttributes.
+    const lastInputMessage = info.inputMessages?.at(-1)
+    const inputValue = typeof lastInputMessage?.content === 'string' ? lastInputMessage.content : ''
+    const outputSpanData = info.outputOaiSpan?.spanData
+    let outputValue = outputSpanData?._response?.output_text ?? ''
+    if (outputSpanData?.type === 'generation') {
+      const outputMessages = extractGenerationOutputMessages(outputSpanData.output)
+      outputValue = outputMessages.at(-1)?.content ?? ''
+    }
+
+    this.#tagger.tagTextIO(ddSpan, inputValue, outputValue)
+
+    if (info.metadata && Object.keys(info.metadata).length > 0) {
+      this.#tagger.tagMetadata(ddSpan, info.metadata)
+    }
+  }
+
+  // ── Trace-info reconstruction (Python parity) ───────────────────────────────
+
+  #updateTraceInfoInput (oaiSpan, spanName) {
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (!info) return
+
+    const parentId = oaiSpan.parentId
+    const type = oaiSpan.spanData?.type
+
+    // Identify the first top-level agent span under the root trace and
+    // stash its display name so `${agentName} (LLM)` doesn't have to read
+    // the dd-trace span context's private fields later.
+    if (type === 'agent' && parentId == null) {
+      info.currentTopLevelAgentSpanId = oaiSpan.spanId
+      info.currentTopLevelAgentName = spanName
+    }
+
+    // Capture the first response span whose parent is the top-level agent
+    // as the workflow-level input source.
+    if (
+      (type === 'response' || type === 'generation') &&
+      parentId &&
+      !info.inputOaiSpan &&
+      parentId === info.currentTopLevelAgentSpanId
+    ) {
+      info.inputOaiSpan = oaiSpan
+    }
+  }
+
+  #updateTraceInfoOutput (oaiSpan) {
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (!info) return
+
+    if (
+      oaiSpan.parentId &&
+      info.currentTopLevelAgentSpanId &&
+      oaiSpan.parentId === info.currentTopLevelAgentSpanId
+    ) {
+      info.outputOaiSpan = oaiSpan
+    }
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────────
+
+  #resolveParent (oaiSpan) {
+    const parentId = oaiSpan.parentId
+    const traceId = oaiSpan.traceId
+    if (parentId) {
+      const parent = this.#oaiToDdSpan.get(parentId)
+      if (parent) return parent
+    }
+    if (traceId) {
+      const root = this.#oaiToDdSpan.get(traceId)
+      if (root) return root
+    }
+  }
+
+  /**
+   * Read the mutable tracer configuration so remote/runtime enablement is
+   * reflected without reconstructing the plugin.
+   *
+   * @returns {boolean}
+   */
+  #isLLMObsEnabled () {
+    return !!this.#config.llmobs?.DD_LLMOBS_ENABLED
+  }
+
+  /**
+   * Resolve model provider from the model invocation's async-local context.
+   *
+   * @returns {string}
+   */
+  #getCurrentModelProvider () {
+    const baseURL = legacyStorage.getStore()?.[MODEL_BASE_URL_STORE_KEY]
+    return baseURL ? getOpenAIModelProvider(baseURL) : DEFAULT_MODEL_PROVIDER
+  }
+
+  /**
+   * Build common APM tags without overriding the tracer's global service when
+   * the integration has no explicit service configuration.
+   *
+   * @param {string} spanKind
+   * @returns {Record<string, string>}
+   */
+  #getSpanTags (spanKind) {
+    const tags = {
+      component: COMPONENT,
+      'span.kind': spanKind,
+    }
+    if (this.#service) tags.service = this.#service
+    return tags
+  }
+}
+
+module.exports = { MODEL_BASE_URL_STORE_KEY, OpenAIAgentsIntegration }