fix(esbuild,webpack): bundle the OpenTelemetry API fallback when the app has no copy

The plugins marked @opentelemetry/api and @opentelemetry/api-logs external
unconditionally, so a bundle that used the OpenTelemetry bridge but was deployed
without the packages in node_modules threw at runtime on the fallback require.
Externalizing is only needed when the application owns a copy the instrumentation
must capture and share; a package the application does not declare has no
competing copy to protect.

Externalize a package only when the application's package.json declares it, and
otherwise leave it in the bundle so dd-trace's own copy is inlined and the bundle
stays self-contained. When the manifest cannot be read, keep externalizing so the
shared-copy correctness is never traded for the self-contained-bundle
optimization.

Fixes: #6882

Author: BridgeAR

docs/API.md

@@ -398,6 +398,8 @@ const tracerProvider = new tracer.TracerProvider()
 tracerProvider.register()
 ```
 
+dd-trace binds to the application's own `@opentelemetry/api` copy when it is present and falls back to the copy it bundles otherwise. If you require `@opentelemetry/api` yourself, require it before creating the `TracerProvider` so the bridge registers on the same copy your code reads. The `dd-trace/esbuild` and `dd-trace/webpack` plugins mark a package external only when your application depends on it, so its single runtime copy is shared with the bridge; keep those resolvable at runtime. A package your application does not depend on is bundled from dd-trace's own copy, so no extra runtime dependency is needed.
+
 The following attributes are available to override Datadog-specific options:
 
 * `service.name`: The service name to be used for this span. The service name from the tracer will be used if this is not provided.

packages/datadog-esbuild/index.js

@@ -13,6 +13,7 @@ const {
   matchesOptionalPeerFile,
   rewriteOptionalPeerLoads,
 } = require('../datadog-instrumentations/src/helpers/optional-peer-bundler')
+const { otelApiPackagesToExternalize } = require('../datadog-instrumentations/src/helpers/otel-api-externals')
 const { processModule, isESMFile } = require('./src/utils')
 const log = require('./src/log')
 
@@ -146,12 +147,14 @@ ${build.initialOptions.banner.js}`
     build.initialOptions.external.push('@openfeature/core')
   }
 
-  // The OpenTelemetry API packages are optional peers the application owns. The bridge captures
-  // the application's copy through the `@opentelemetry/api` instrumentation, which only fires on a
-  // runtime require. Bundling them would inline a second copy that the instrumentation never sees,
-  // so the bridge would register its provider on the wrong copy and silently downgrade every span
-  // to a no-op (issue #6882). Mark them external so the require survives for interception.
-  for (const otelApiPackage of ['@opentelemetry/api', '@opentelemetry/api-logs']) {
+  // Keep an OpenTelemetry API package external only when the application declares its own copy: the
+  // bridge captures that copy through the `@opentelemetry/api` instrumentation, which fires on a
+  // runtime require, so bundling it would inline a second copy the instrumentation never sees and the
+  // bridge would register on the wrong one, downgrading every span to a no-op (issue #6882). A
+  // package the application does not declare is left to bundle, so dd-trace's own fallback copy is
+  // inlined and the bundle stays self-contained.
+  const workingDir = build.initialOptions.absWorkingDir || process.cwd()
+  for (const otelApiPackage of otelApiPackagesToExternalize(workingDir)) {
     build.initialOptions.external ??= []
     build.initialOptions.external.push(otelApiPackage)
     externalModules.add(otelApiPackage)

packages/datadog-esbuild/test/plugin.spec.js

@@ -1,6 +1,9 @@
 'use strict'
 
 const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
 const { describe, it } = require('mocha')
 
 const ddPlugin = require('../index')
@@ -24,6 +27,8 @@ function setupExternal (initialOptions = {}) {
 
 describe('datadog-esbuild plugin', () => {
   describe('OpenTelemetry API externalization', () => {
+    // The repo's own package.json declares both packages, so a build run from the repo root
+    // externalizes both (they are the application's declared copies).
     it('marks both OpenTelemetry API peers external so the bundle shares the application copy', () => {
       const external = setupExternal()
 
@@ -38,6 +43,29 @@ describe('datadog-esbuild plugin', () => {
       assert.ok(external.includes('@opentelemetry/api'), 'should externalize @opentelemetry/api')
       assert.ok(external.includes('@opentelemetry/api-logs'), 'should externalize @opentelemetry/api-logs')
     })
+
+    it('bundles a package the application does not depend on so the bundle stays self-contained', () => {
+      const workingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dd-esbuild-otel-'))
+      fs.writeFileSync(path.join(workingDir, 'package.json'), JSON.stringify({ name: 'app', dependencies: {} }))
+
+      const external = setupExternal({ absWorkingDir: workingDir }) ?? []
+
+      assert.ok(!external.includes('@opentelemetry/api'), 'should bundle @opentelemetry/api')
+      assert.ok(!external.includes('@opentelemetry/api-logs'), 'should bundle @opentelemetry/api-logs')
+    })
+
+    it('externalizes only the package the application declares', () => {
+      const workingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dd-esbuild-otel-'))
+      fs.writeFileSync(
+        path.join(workingDir, 'package.json'),
+        JSON.stringify({ name: 'app', dependencies: { '@opentelemetry/api': '^1.9.0' } })
+      )
+
+      const external = setupExternal({ absWorkingDir: workingDir }) ?? []
+
+      assert.ok(external.includes('@opentelemetry/api'), 'should externalize the declared copy')
+      assert.ok(!external.includes('@opentelemetry/api-logs'), 'should bundle the undeclared copy')
+    })
   })
 
   describe('optional peer bundling', () => {

packages/datadog-instrumentations/src/helpers/otel-api-externals.js

@@ -0,0 +1,50 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const OTEL_API_PACKAGES = ['@opentelemetry/api', '@opentelemetry/api-logs']
+
+/**
+ * Decide which OpenTelemetry API packages a bundle must keep external.
+ *
+ * The bridge captures the application's own copy through require interception, which only fires on a
+ * runtime require. Bundling a copy the application also owns would inline a second copy the
+ * interception never sees, so the bridge would register its provider on the wrong copy and silently
+ * downgrade every span to a no-op (issue #6882). A package the application does not declare has no
+ * competing copy, so it is left to bundle: dd-trace's own fallback copy is inlined and the bundle
+ * stays self-contained, needing no `@opentelemetry/api` in `node_modules` at runtime.
+ *
+ * @param {string} workingDir Directory whose `package.json` lists the application's dependencies.
+ * @returns {string[]} The subset of `OTEL_API_PACKAGES` to mark external.
+ */
+function otelApiPackagesToExternalize (workingDir) {
+  const declared = readDeclaredDependencies(workingDir)
+  // A missing or unreadable manifest is inconclusive, so err toward external: sharing the
+  // application's copy is the correctness-preserving default and only costs the self-contained-bundle
+  // optimization when the application in fact owns no copy.
+  if (!declared) return OTEL_API_PACKAGES
+  return OTEL_API_PACKAGES.filter(name => declared.has(name))
+}
+
+/**
+ * @param {string} workingDir
+ * @returns {Set<string> | undefined} All declared dependency names, or `undefined` when the manifest
+ *   cannot be read.
+ */
+function readDeclaredDependencies (workingDir) {
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(workingDir, 'package.json'), 'utf8'))
+  } catch {
+    return
+  }
+  return new Set([
+    ...Object.keys(manifest.dependencies ?? {}),
+    ...Object.keys(manifest.devDependencies ?? {}),
+    ...Object.keys(manifest.optionalDependencies ?? {}),
+    ...Object.keys(manifest.peerDependencies ?? {}),
+  ])
+}
+
+module.exports = { OTEL_API_PACKAGES, otelApiPackagesToExternalize }

packages/datadog-instrumentations/test/otel-api-externals.spec.js

@@ -0,0 +1,52 @@
+'use strict'
+
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const { describe, it, beforeEach } = require('mocha')
+
+const { OTEL_API_PACKAGES, otelApiPackagesToExternalize } = require('../src/helpers/otel-api-externals')
+
+describe('otel-api-externals', () => {
+  let workingDir
+
+  beforeEach(() => {
+    workingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dd-otel-externals-'))
+  })
+
+  /**
+   * @param {object} manifest
+   */
+  function writeManifest (manifest) {
+    fs.writeFileSync(path.join(workingDir, 'package.json'), JSON.stringify(manifest))
+  }
+
+  it('externalizes only the packages the application declares', () => {
+    writeManifest({ name: 'app', dependencies: { '@opentelemetry/api': '^1.9.0' } })
+
+    assert.deepStrictEqual(otelApiPackagesToExternalize(workingDir), ['@opentelemetry/api'])
+  })
+
+  it('bundles every package the application does not declare', () => {
+    writeManifest({ name: 'app', dependencies: { express: '^4.0.0' } })
+
+    assert.deepStrictEqual(otelApiPackagesToExternalize(workingDir), [])
+  })
+
+  it('detects the packages across every dependency field', () => {
+    writeManifest({
+      name: 'app',
+      devDependencies: { '@opentelemetry/api': '^1.9.0' },
+      peerDependencies: { '@opentelemetry/api-logs': '<1.0.0' },
+    })
+
+    assert.deepStrictEqual(otelApiPackagesToExternalize(workingDir), OTEL_API_PACKAGES)
+  })
+
+  it('errs toward external when the manifest cannot be read', () => {
+    // No package.json written: sharing the application copy is the correctness-preserving default.
+    assert.deepStrictEqual(otelApiPackagesToExternalize(workingDir), OTEL_API_PACKAGES)
+  })
+})

packages/datadog-webpack/index.js

@@ -7,6 +7,7 @@ const instrumentations = require('../datadog-instrumentations/src/helpers/instru
 const extractPackageAndModulePath = require('../datadog-instrumentations/src/helpers/extract-package-and-module-path')
 const hooks = require('../datadog-instrumentations/src/helpers/hooks')
 const { matchesOptionalPeerFile } = require('../datadog-instrumentations/src/helpers/optional-peer-bundler')
+const { otelApiPackagesToExternalize } = require('../datadog-instrumentations/src/helpers/otel-api-externals')
 const { isESMFile } = require('../datadog-esbuild/src/utils')
 const log = require('./src/log')
 
@@ -81,20 +82,25 @@ class DatadogWebpackPlugin {
       }
     })
 
-    // The OpenTelemetry API packages are optional peers the application owns. The bridge captures
-    // the application's copy through the @opentelemetry/api instrumentation, which only fires on a
-    // runtime require. Bundling them would inline a second copy the instrumentation never sees, so
-    // the bridge would register its provider on the wrong copy and silently downgrade every span to
-    // a no-op (issue #6882). Mark them external so the require survives for interception. The
-    // `commonjs` type forces a CommonJS require regardless of the user's externalsType.
-    const externals = Array.isArray(compiler.options.externals)
-      ? compiler.options.externals
-      : [compiler.options.externals].filter(Boolean)
-    externals.push({
-      '@opentelemetry/api': 'commonjs @opentelemetry/api',
-      '@opentelemetry/api-logs': 'commonjs @opentelemetry/api-logs',
-    })
-    compiler.options.externals = externals
+    // Keep an OpenTelemetry API package external only when the application declares its own copy: the
+    // bridge captures that copy through the @opentelemetry/api instrumentation, which fires on a
+    // runtime require, so bundling it would inline a second copy the instrumentation never sees and
+    // the bridge would register on the wrong one, downgrading every span to a no-op (issue #6882). A
+    // package the application does not declare is left to bundle, so dd-trace's own fallback copy is
+    // inlined and the bundle stays self-contained. The `commonjs` type forces a CommonJS require
+    // regardless of the user's externalsType.
+    const workingDir = compiler.options.context || process.cwd()
+    const otelApiExternals = {}
+    for (const otelApiPackage of otelApiPackagesToExternalize(workingDir)) {
+      otelApiExternals[otelApiPackage] = `commonjs ${otelApiPackage}`
+    }
+    if (otelApiExternals['@opentelemetry/api'] || otelApiExternals['@opentelemetry/api-logs']) {
+      const externals = Array.isArray(compiler.options.externals)
+        ? compiler.options.externals
+        : [compiler.options.externals].filter(Boolean)
+      externals.push(otelApiExternals)
+      compiler.options.externals = externals
+    }
 
     const gitMetadata = getGitMetadata()
     if (gitMetadata.repositoryURL || gitMetadata.commitSHA) {

packages/datadog-webpack/test/plugin.spec.js

@@ -1,6 +1,9 @@
 'use strict'
 
 const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
 const { describe, it } = require('mocha')
 
 const DatadogWebpackPlugin = require('../index')
@@ -50,9 +53,9 @@ describe('DatadogWebpackPlugin', () => {
       assert.equal(tapped[0], 'DatadogWebpackPlugin')
     })
 
-    function applyToExternals (externals) {
+    function applyToExternals (externals, context) {
       const compiler = {
-        options: { optimization: {}, externals },
+        options: { optimization: {}, externals, context },
         hooks: {
           environment: { tap: () => {} },
           thisCompilation: { tap: () => {} },
@@ -63,6 +66,17 @@ describe('DatadogWebpackPlugin', () => {
       return compiler.options.externals
     }
 
+    function manifestDir (manifest) {
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dd-webpack-otel-'))
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(manifest))
+      return dir
+    }
+
+    function otelExternalEntry (externals) {
+      if (!Array.isArray(externals)) return undefined
+      return externals.find(entry => entry && typeof entry === 'object' && '@opentelemetry/api' in entry)
+    }
+
     it('externalizes both OpenTelemetry API peers as a commonjs require', () => {
       const externals = applyToExternals()
 
@@ -85,6 +99,22 @@ describe('DatadogWebpackPlugin', () => {
       assert.ok(externals.includes('pg'), 'should preserve the user external')
       assert.ok('@opentelemetry/api' in externals.at(-1), 'should externalize @opentelemetry/api')
     })
+
+    it('bundles a package the application does not depend on so the bundle stays self-contained', () => {
+      const context = manifestDir({ name: 'app', dependencies: {} })
+
+      const externals = applyToExternals(undefined, context)
+
+      assert.strictEqual(otelExternalEntry(externals), undefined)
+    })
+
+    it('externalizes only the package the application declares', () => {
+      const context = manifestDir({ name: 'app', dependencies: { '@opentelemetry/api': '^1.9.0' } })
+
+      const entry = otelExternalEntry(applyToExternals(undefined, context))
+
+      assert.deepStrictEqual(entry, { '@opentelemetry/api': 'commonjs @opentelemetry/api' })
+    })
   })
 
   describe('optional peer bundling', () => {