dd-trace 5.104.0 → 5.105.0

package/packages/dd-trace/src/opentracing/span.js

@@ -10,7 +10,10 @@ const tagger = require('../tagger')
 const runtimeMetrics = require('../runtime_metrics')
 const log = require('../log')
 const { storage } = require('../../../datadog-core')
+const { resolveServiceSource } = require('../service-naming/source-resolver')
 const telemetryMetrics = require('../telemetry/metrics')
+const { MANUAL_DROP, MANUAL_KEEP, SAMPLING_PRIORITY } = require('../../../../ext/tags')
+const { DD_MAJOR } = require('../../../../version')
 const SpanContext = require('./span_context')
 
 const dateNow = Date.now
@@ -103,7 +106,7 @@ class DatadogSpan {
 
     this._spanContext = this._createContext(parent, fields)
     this._spanContext._name = operationName
-    this._spanContext._tags = tags
+    Object.assign(this._spanContext.getTags(), tags)
     this._spanContext._hostname = hostname
 
     this._spanContext._trace.started.push(this)
@@ -145,7 +148,7 @@ class DatadogSpan {
 
   toString () {
     const spanContext = this.context()
-    const resourceName = spanContext._tags['resource.name'] || ''
+    const resourceName = spanContext.getTag('resource.name') || ''
     const resource = resourceName.length > 100
       ? `${resourceName.slice(0, 97)}...`
       : resourceName
@@ -153,7 +156,7 @@ class DatadogSpan {
       traceId: spanContext._traceId,
       spanId: spanContext._spanId,
       parentId: spanContext._parentId,
-      service: spanContext._tags['service.name'],
+      service: spanContext.getTag('service.name'),
       name: spanContext._name,
       resource,
     })
@@ -199,12 +202,52 @@ class DatadogSpan {
   }
 
   setTag (key, value) {
-    this._addTags({ [key]: value })
+    this._spanContext.setTag(key, value)
+
+    if (isSamplingPriorityTag(key) && this._spanContext._sampling.priority === undefined) {
+      this._prioritySampler.sample(this, false)
+    }
+
+    if (tagsUpdateCh.hasSubscribers) {
+      tagsUpdateCh.publish(this)
+    }
+
     return this
   }
 
   addTags (keyValueMap) {
-    this._addTags(keyValueMap)
+    // v6 hot path: `Object.assign` straight onto the live tag map. The
+    // string and array shapes never appeared in the public TypeScript
+    // surface, and no internal v6 caller passes one (see MIGRATING.md).
+    // v5 still accepts both via `tagger.add` for `config.tags` /
+    // `options.tags` callers that pass `'key:val,key:val'` strings.
+    const tags = this._spanContext.getTags()
+    let mayChangeSamplingPriority
+
+    if (keyValueMap !== null && typeof keyValueMap === 'object' && !Array.isArray(keyValueMap)) {
+      Object.assign(tags, keyValueMap)
+      mayChangeSamplingPriority =
+        MANUAL_KEEP in keyValueMap ||
+        MANUAL_DROP in keyValueMap ||
+        SAMPLING_PRIORITY in keyValueMap
+    } else {
+      /* istanbul ignore if: v5 fallback, master ships 6.0.0-pre */
+      if (DD_MAJOR < 6 && (typeof keyValueMap === 'string' || Array.isArray(keyValueMap))) {
+        tagger.add(tags, keyValueMap)
+        mayChangeSamplingPriority = true
+      } else {
+        return this
+      }
+    }
+
+    if (mayChangeSamplingPriority && this._spanContext._sampling.priority === undefined) {
+      this._prioritySampler.sample(this, false)
+    }
+
+    if (tagsUpdateCh.hasSubscribers) {
+      tagsUpdateCh.publish(this)
+    }
+
     return this
   }
 
@@ -215,8 +258,9 @@ class DatadogSpan {
   logEvent () {}
 
   addLink (link, attrs) {
-    // TODO: Remove this once we remove addLink(context, attrs) in v6.0.0
-    if (link instanceof SpanContext) {
+    // v5 still accepts the legacy `addLink(spanContext, attrs)` shape; v6 only takes
+    // `addLink({ context, attributes })`.
+    if (DD_MAJOR < 6 && link instanceof SpanContext) {
       link = { context: link, attributes: attrs ?? {} }
     }
 
@@ -267,12 +311,14 @@ class DatadogSpan {
       return
     }
 
-    if (this.#parentTracer._config.DD_TRACE_EXPERIMENTAL_STATE_TRACKING && !this._spanContext._tags['service.name']) {
+    if (this.#parentTracer._config.DD_TRACE_EXPERIMENTAL_STATE_TRACKING && !this._spanContext.getTag('service.name')) {
       log.error('Finishing invalid span: %s', this)
     }
 
     getIntegrationCounter('spans_finished', this._integrationName).inc()
-    this._spanContext._tags['_dd.integration'] = this._integrationName
+    this._spanContext.setTag('_dd.integration', this._integrationName)
+
+    resolveServiceSource(this, this.#parentTracer._service)
 
     if (this.#parentTracer._config.DD_TRACE_EXPERIMENTAL_SPAN_COUNTS && finishedRegistry) {
       runtimeMetrics.decrement('runtime.node.spans.unfinished')
@@ -404,16 +450,6 @@ class DatadogSpan {
 
     return startTime + now() - ticks
   }
-
-  _addTags (keyValuePairs) {
-    tagger.add(this._spanContext._tags, keyValuePairs)
-
-    this._prioritySampler.sample(this, false)
-
-    if (tagsUpdateCh.hasSubscribers) {
-      tagsUpdateCh.publish(this)
-    }
-  }
 }
 
 function createRegistry (type) {
@@ -423,4 +459,8 @@ function createRegistry (type) {
   })
 }
 
+function isSamplingPriorityTag (key) {
+  return key === MANUAL_KEEP || key === MANUAL_DROP || key === SAMPLING_PRIORITY
+}
+
 module.exports = DatadogSpan

package/packages/dd-trace/src/opentracing/span_context.js

@@ -71,6 +71,55 @@ class DatadogSpanContext {
     const version = (this._traceparent && this._traceparent.version) || '00'
     return `${version}-${traceId}-${spanId}-${flags}`
   }
+
+  /**
+   * Set a tag value.
+   * @param {string} key - Tag key
+   * @param {unknown} value - Tag value
+   */
+  setTag (key, value) {
+    this._tags[key] = value
+  }
+
+  /**
+   * Get a tag value.
+   * @param {string} key - Tag key
+   * @returns {unknown} Tag value or undefined
+   */
+  getTag (key) {
+    return this._tags[key]
+  }
+
+  /**
+   * Check if a tag exists.
+   * @param {string} key - Tag key
+   * @returns {boolean}
+   */
+  hasTag (key) { return Object.hasOwn(this._tags, key) }
+
+  /**
+   * Delete a tag.
+   * @param {string} key - Tag key
+   */
+  deleteTag (key) { delete this._tags[key] }
+
+  /**
+   * Get the live internal tags map. The returned reference is mutable;
+   * callers may assign or delete keys directly (e.g.
+   * `Object.assign(getTags(), tags)` in span.js). Subclasses may have
+   * additional sync side effects on the individual `setTag` / `deleteTag`
+   * setters; mutating the returned map bypasses those.
+   *
+   * @returns {object}
+   */
+  getTags () {
+    return this._tags
+  }
+
+  /**
+   * Clear all tags.
+   */
+  clearTags () { this._tags = Object.create(null) }
 }
 
 module.exports = DatadogSpanContext

package/packages/dd-trace/src/plugins/ci_plugin.js

@@ -52,7 +52,6 @@ const {
   TEST_ITR_SKIPPING_ENABLED,
   ITR_CORRELATION_ID,
   TEST_SOURCE_FILE,
-  TEST_LEVEL_EVENT_TYPES,
   TEST_SUITE,
   getFileAndLineNumberFromError,
   DI_ERROR_DEBUG_INFO_CAPTURED,
@@ -128,7 +127,6 @@ function getTestSuiteLevelVisibilityTags (testSuiteSpan, testFramework) {
   const suiteTags = {
     [TEST_SUITE_ID]: testSuiteSpanContext.toSpanId(),
     [TEST_SESSION_ID]: testSuiteSpanContext.toTraceId(),
-    [TEST_COMMAND]: testSuiteSpanContext._tags[TEST_COMMAND],
     [TEST_MODULE]: testFramework,
   }
 
@@ -174,7 +172,7 @@ module.exports = class CiPlugin extends Plugin {
           },
         }
         this.tracer._exporter.addMetadataTags(metadataTags)
-        onDone({ err, libraryConfig, requestErrorTags })
+        onDone({ err, libraryConfig, repositoryRoot: this.repositoryRoot, requestErrorTags })
       })
     })
 
@@ -186,15 +184,22 @@ module.exports = class CiPlugin extends Plugin {
       if (!this.tracer._exporter?.getSkippableSuites) {
         return onDone({ err: new Error('Test optimization was not initialized correctly') })
       }
-      this.tracer._exporter.getSkippableSuites(this.testConfiguration, (err, skippableSuites, itrCorrelationId) => {
-        if (err) {
-          log.error('Skippable suites could not be fetched. %s', err.message)
-          this._addRequestErrorTag(DD_CI_LIBRARY_CONFIGURATION_ERROR_SKIPPABLE_TESTS, err)
-        } else {
-          this.itrCorrelationId = itrCorrelationId
+      this.tracer._exporter.getSkippableSuites(
+        {
+          ...this.testConfiguration,
+          isCoverageReportUploadEnabled: this.libraryConfig?.isCoverageReportUploadEnabled,
+        },
+        (err, skippableSuites, itrCorrelationId, skippableSuitesCoverage) => {
+          if (err) {
+            log.error('Skippable suites could not be fetched. %s', err.message)
+            this._addRequestErrorTag(DD_CI_LIBRARY_CONFIGURATION_ERROR_SKIPPABLE_TESTS, err)
+          } else {
+            this.itrCorrelationId = itrCorrelationId
+            this.skippableSuitesCoverage = skippableSuitesCoverage
+          }
+          onDone({ err, skippableSuites, itrCorrelationId, skippableSuitesCoverage })
         }
-        onDone({ err, skippableSuites, itrCorrelationId })
-      })
+      )
     })
 
     this.addSub(`ci:${this.constructor.id}:session:start`, ({ command, frameworkVersion, rootDir }) => {
@@ -213,12 +218,7 @@ module.exports = class CiPlugin extends Plugin {
         this.testEnvironmentMetadata
       )
 
-      const metadataTags = {}
-      for (const testLevel of TEST_LEVEL_EVENT_TYPES) {
-        metadataTags[testLevel] = {
-          [TEST_SESSION_NAME]: testSessionName,
-        }
-      }
+      const metadataTags = { '*': { [TEST_COMMAND]: command, [TEST_SESSION_NAME]: testSessionName } }
       // tracer might not be initialized correctly
       if (this.tracer._exporter.addMetadataTags) {
         this.tracer._exporter.addMetadataTags(metadataTags)
@@ -255,7 +255,7 @@ module.exports = class CiPlugin extends Plugin {
     })
 
     this.addSub(`ci:${this.constructor.id}:itr:skipped-suites`, ({ skippedSuites, frameworkVersion }) => {
-      const testCommand = this.testSessionSpan.context()._tags[TEST_COMMAND]
+      const testCommand = this.command
       for (const testSuite of skippedSuites) {
         const testSuiteMetadata = {
           ...getTestSuiteCommonTags(testCommand, frameworkVersion, testSuite, this.constructor.id),
@@ -615,7 +615,7 @@ module.exports = class CiPlugin extends Plugin {
       const suiteTags = {
         [TEST_SUITE_ID]: testSuiteSpan.context().toSpanId(),
         [TEST_SESSION_ID]: testSuiteSpan.context().toTraceId(),
-        [TEST_COMMAND]: testSuiteSpan.context()._tags[TEST_COMMAND],
+        [TEST_COMMAND]: testSuiteSpan.context().getTag(TEST_COMMAND),
         [TEST_MODULE]: this.constructor.id,
         ...getSessionRequestErrorTags(this.testSessionSpan),
       }
@@ -808,7 +808,7 @@ module.exports = class CiPlugin extends Plugin {
   }
 
   getTestTelemetryTags (testSpan) {
-    const activeSpanTags = testSpan.context()._tags
+    const activeSpanTags = testSpan.context().getTags()
     return {
       hasCodeOwners: !!activeSpanTags[TEST_CODE_OWNERS] || undefined,
       isNew: activeSpanTags[TEST_IS_NEW] === 'true' || undefined,

package/packages/dd-trace/src/plugins/database.js

@@ -49,7 +49,7 @@ class DatabasePlugin extends StoragePlugin {
    * @returns {string}
    */
   #createDBMPropagationCommentService (serviceName, span, peerData) {
-    const spanTags = span.context()._tags
+    const spanTags = span.context().getTags()
     const dddb = spanTags['db.name']
     const ddh = spanTags['out.host']
     const cacheKey = `${dddb ?? ''}\0${ddh ?? ''}\0${serviceName ?? ''}`
@@ -91,23 +91,24 @@ class DatabasePlugin extends StoragePlugin {
       return null
     }
 
-    const peerData = this.getPeerService(span.context()._tags)
+    const peerData = this.getPeerService(span.context().getTags())
     const dbmService = this.#getDbmServiceName(serviceName, peerData)
     const servicePropagation = this.#createDBMPropagationCommentService(dbmService, span, peerData)
 
     let dbmComment = servicePropagation
 
-    // Add propagation hash if both process tags and SQL base hash injection are enabled
-    if (propagationHash.isEnabled() && this.config['dbm.injectSqlBaseHash']) {
+    // Add propagation hash if process tags are enabled and either SQL base hash injection is enabled
+    // or dynamic_service mode implicitly enables it
+    if (propagationHash.isEnabled() && (this.config['dbm.injectSqlBaseHash'] || mode === 'dynamic_service')) {
       const hashBase64 = propagationHash.getHashBase64()
       if (hashBase64) {
         dbmComment += `,ddsh='${hashBase64}'`
         // Add hash to span meta as a tag
-        span.setTag('_dd.dbm.propagation_hash', hashBase64)
+        span.setTag('_dd.propagated_hash', hashBase64)
       }
     }
 
-    if (disableFullMode || mode === 'service') {
+    if (disableFullMode || mode === 'service' || mode === 'dynamic_service') {
       return dbmComment
     } else if (mode === 'full') {
       span.setTag('_dd.dbm_trace_injected', 'true')

package/packages/dd-trace/src/plugins/index.js

@@ -4,6 +4,7 @@ const plugins = {
   get '@anthropic-ai/sdk' () { return require('../../../datadog-plugin-anthropic/src') },
   get '@apollo/gateway' () { return require('../../../datadog-plugin-apollo/src') },
   get '@aws-sdk/smithy-client' () { return require('../../../datadog-plugin-aws-sdk/src') },
+  get '@azure/cosmos' () { return require('../../../datadog-plugin-azure-cosmos/src') },
   get '@azure/event-hubs' () { return require('../../../datadog-plugin-azure-event-hubs/src') },
   get '@azure/functions' () { return require('../../../datadog-plugin-azure-functions/src') },
   get '@modelcontextprotocol/sdk' () { return require('../../../datadog-plugin-modelcontextprotocol-sdk/src') },
@@ -30,6 +31,7 @@ const plugins = {
   get '@prisma/client' () { return require('../../../datadog-plugin-prisma/src') },
   get './runtime/library.js' () { return require('../../../datadog-plugin-prisma/src') },
   get '@redis/client' () { return require('../../../datadog-plugin-redis/src') },
+  get '@smithy/core' () { return require('../../../datadog-plugin-aws-sdk/src') },
   get '@smithy/smithy-client' () { return require('../../../datadog-plugin-aws-sdk/src') },
   get '@vitest/runner' () { return require('../../../datadog-plugin-vitest/src') },
   get '@langchain/langgraph' () { return require('../../../datadog-plugin-langgraph/src') },
@@ -90,6 +92,8 @@ const plugins = {
   get mongoose () { return require('../../../datadog-plugin-mongoose/src') },
   get mysql () { return require('../../../datadog-plugin-mysql/src') },
   get mysql2 () { return require('../../../datadog-plugin-mysql2/src') },
+  get '@nats-io/nats-core' () { return require('../../../datadog-plugin-nats/src') },
+  get '@nats-io/transport-node' () { return require('../../../datadog-plugin-nats/src') },
   get net () { return require('../../../datadog-plugin-net/src') },
   get next () { return require('../../../datadog-plugin-next/src') },
   get 'node:dns' () { return require('../../../datadog-plugin-dns/src') },

package/packages/dd-trace/src/plugins/log_injection.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const { LOG } = require('../../../../ext/formats')
+const { storage } = require('../../../datadog-core')
+
+const legacyStorage = storage('legacy')
+
+/**
+ * Runs the tracer's log injector and returns the populated log holder, or
+ * `undefined` when the propagator emitted no `dd` field (no span, no
+ * service / version / env). Hot-path callers gate on the return.
+ *
+ * @param {object} tracer
+ * @returns {{ dd: object } | undefined}
+ */
+function buildLogHolder (tracer) {
+  const logHolder = {}
+  tracer.inject(legacyStorage.getStore()?.span, LOG, logHolder)
+  return logHolder.dd ? logHolder : undefined
+}
+
+/**
+ * @param {object} message Caller-owned log record; never mutated.
+ * @param {{ dd: object }} logHolder Holds the dd fields injected by the tracer.
+ */
+function messageProxy (message, logHolder) {
+  return new Proxy(message, {
+    get (target, key) {
+      if (shouldOverride(target, key)) return logHolder.dd
+      return target[key]
+    },
+    set (target, key, value) {
+      return Reflect.set(target, key, value)
+    },
+    ownKeys (target) {
+      const ownKeys = Reflect.ownKeys(target)
+      if (!Object.hasOwn(target, 'dd') && Reflect.isExtensible(target)) {
+        ownKeys.push('dd')
+      }
+      return ownKeys
+    },
+    getOwnPropertyDescriptor (target, p) {
+      return Reflect.getOwnPropertyDescriptor(shouldOverride(target, p) ? logHolder : target, p)
+    },
+  })
+}
+
+/**
+ * @param {object} target
+ * @param {string | symbol} p
+ */
+function shouldOverride (target, p) {
+  return p === 'dd' && !Object.hasOwn(target, p) && Reflect.isExtensible(target)
+}
+
+module.exports = { buildLogHolder, messageProxy }

package/packages/dd-trace/src/plugins/log_plugin.js

@@ -1,55 +1,8 @@
 'use strict'
 
-const { LOG } = require('../../../../ext/formats')
-const { storage } = require('../../../datadog-core')
 const Plugin = require('./plugin')
 
-const legacyStorage = storage('legacy')
-
-function messageProxy (message, holder) {
-  return new Proxy(message, {
-    get (target, key) {
-      if (shouldOverride(target, key)) {
-        return holder.dd
-      }
-
-      return target[key]
-    },
-    set (target, key, value) {
-      return Reflect.set(target, key, value)
-    },
-    ownKeys (target) {
-      const ownKeys = Reflect.ownKeys(target)
-      if (!Object.hasOwn(target, 'dd') && Reflect.isExtensible(target)) {
-        ownKeys.push('dd')
-      }
-      return ownKeys
-    },
-    getOwnPropertyDescriptor (target, p) {
-      return Reflect.getOwnPropertyDescriptor(shouldOverride(target, p) ? holder : target, p)
-    },
-  })
-}
-
-function shouldOverride (target, p) {
-  return p === 'dd' && !Object.hasOwn(target, p) && Reflect.isExtensible(target)
-}
-
-module.exports = class LogPlugin extends Plugin {
-  constructor (...args) {
-    super(...args)
-
-    this.addSub(`apm:${this.constructor.id}:log`, (arg) => {
-      const span = legacyStorage.getStore()?.span
-
-      // NOTE: This needs to run whether or not there is a span
-      // so service, version, and env will always get injected.
-      const holder = {}
-      this.tracer.inject(span, LOG, holder)
-      arg.message = messageProxy(arg.message, holder)
-    })
-  }
-
+class LogPlugin extends Plugin {
   configure (config) {
     return super.configure({
       ...config,
@@ -57,3 +10,5 @@ module.exports = class LogPlugin extends Plugin {
     })
   }
 }
+
+module.exports = LogPlugin

package/packages/dd-trace/src/plugins/outbound.js

@@ -125,7 +125,7 @@ class OutboundPlugin extends TracingPlugin {
    */
   tagPeerService (span) {
     if (this._tracerConfig.spanComputePeerService) {
-      const peerData = this.getPeerService(span.context()._tags)
+      const peerData = this.getPeerService(span.context().getTags())
       if (peerData !== undefined) {
         span.addTags(this.getPeerServiceRemap(peerData))
       }

package/packages/dd-trace/src/plugins/plugin.js

@@ -6,6 +6,8 @@ const dc = require('dc-polyfill')
 const logger = require('../log')
 const { storage } = require('../../../datadog-core')
 
+const legacyStorage = storage('legacy')
+
 /**
  * Base class for all Datadog plugins.
  *
@@ -28,8 +30,7 @@ class Subscription {
   constructor (event, handler) {
     this._channel = dc.channel(event)
     this._handler = (message, name) => {
-      const store = storage('legacy').getStore()
-      if (!store || !store.noop) {
+      if (!legacyStorage.getHandle()?.noop) {
         handler(message, name)
       }
     }
@@ -50,20 +51,20 @@ class StoreBinding {
   constructor (event, transform) {
     this._channel = dc.channel(event)
     this._transform = data => {
-      const store = storage('legacy').getStore()
+      const handle = legacyStorage.getHandle()
 
-      return !store || !store.noop || (data && Object.hasOwn(data, 'currentStore'))
+      return !handle?.noop || (data && Object.hasOwn(data, 'currentStore'))
         ? transform(data)
-        : store
+        : legacyStorage.getStore()
     }
   }
 
   enable () {
-    this._channel.bindStore(storage('legacy'), this._transform)
+    this._channel.bindStore(legacyStorage, this._transform)
   }
 
   disable () {
-    this._channel.unbindStore(storage('legacy'))
+    this._channel.unbindStore(legacyStorage)
   }
 }
 
@@ -102,24 +103,21 @@ module.exports = class Plugin {
    * @returns {void}
    */
   enter (span, store) {
-    store = store || storage('legacy').getStore()
-    storage('legacy').enterWith({ ...store, span })
+    store = store || legacyStorage.getStore()
+    legacyStorage.enterWith({ ...store, span })
   }
 
   /**
    * Subscribe to a diagnostic channel with automatic error handling and enable/disable lifecycle.
    *
    * @param {string} channelName Diagnostic channel name.
-   * @param {(...args: unknown[]) => unknown} handler Handler invoked on messages.
+   * @param {(message: unknown, name: string) => unknown} handler Handler invoked on messages.
    * @returns {void}
    */
   addSub (channelName, handler) {
-    /**
-     * @type {typeof handler}
-     */
-    const wrappedHandler = (...args) => {
+    const wrappedHandler = (message, name) => {
       try {
-        return handler.apply(this, args)
+        return handler.call(this, message, name)
       } catch (error) {
         logger.error('Error in plugin handler:', error)
         logger.info('Disabling plugin: %s', this.constructor.name)
@@ -147,12 +145,12 @@ module.exports = class Plugin {
    * @returns {void}
    */
   addError (error) {
-    const store = storage('legacy').getStore()
+    const store = legacyStorage.getStore()
 
     if (!store || !store.span) return
 
     const span = /** @type {import('../opentracing/span')} */ (store.span)
-    if (!span._spanContext._tags.error) {
+    if (!span.context().getTag('error')) {
       span.setTag('error', error || 1)
     }
   }

package/packages/dd-trace/src/plugins/tracing.js

@@ -3,6 +3,7 @@
 const { storage } = require('../../../datadog-core')
 const analyticsSampler = require('../analytics_sampler')
 const { COMPONENT, SVC_SRC_KEY } = require('../constants')
+const { INTEGRATION_SERVICE } = require('../service-naming/source-resolver')
 const Plugin = require('./plugin')
 
 const legacyStorage = storage('legacy')
@@ -99,13 +100,11 @@ class TracingPlugin extends Plugin {
       const bindName = `bind${event.charAt(0).toUpperCase()}${event.slice(1)}`
 
       if (this[event]) {
-        this.addTraceSub(event, message => {
-          this[event](message)
-        })
+        this.addTraceSub(event, this[event].bind(this))
       }
 
       if (this[bindName]) {
-        this.addTraceBind(event, message => this[bindName](message))
+        this.addTraceBind(event, this[bindName].bind(this))
       }
     }
   }
@@ -128,12 +127,49 @@ class TracingPlugin extends Plugin {
     this.addBind(`${prefix}:${eventName}`, transform)
   }
 
+  /**
+   * Record the integration's intended `service.name` on a span without writing the tag.
+   *
+   * Use this when the plugin has already set `service.name` directly on the span (e.g. via
+   * the `tracer.startSpan` tags object) and only needs to stamp the marker so
+   * `Span#finish` can later detect user overrides and re-attribute the source.
+   *
+   * Prefer {@link TracingPlugin#setServiceName} when the tag itself also needs to be written.
+   *
+   * No-op when there is nothing meaningful to record
+   *
+   * @param {import('../opentracing/span')} span Internal DatadogSpan instance.
+   * @param {string|undefined} name Service name the integration is claiming.
+   */
+  stampIntegrationService (span, name) {
+    if (name === undefined) return
+    span[INTEGRATION_SERVICE] = name
+  }
+
+  /**
+   * Set `service.name` on a span on behalf of this integration and stamp the marker.
+   *
+   * Use this for late-binding cases where the service is not known at startSpan time
+   * (e.g. web framework config applied after the span is already open).
+   *
+   * For spans started via {@link TracingPlugin#startSpan}, pass `service` as an option
+   * instead — it sets the tag and stamps the marker in one step.
+   *
+   * @param {import('../opentracing/span')} span Internal DatadogSpan instance.
+   * @param {string} name Service name the integration is claiming.
+   */
+  setServiceName (span, name) {
+    // eslint-disable-next-line eslint-rules/eslint-prefer-set-service-name -- this is the implementation
+    span._spanContext.setTag('service.name', name)
+    this.stampIntegrationService(span, name)
+  }
+
   /**
    * @param {unknown} error
    * @param {import('../../../..').Span} [span]
    */
   addError (error, span = this.activeSpan) {
-    if (span && !span._spanContext._tags.error) {
+    if (span && !span.context().getTag('error')) {
       // Errors may be wrapped in a context.
       span.setTag('error', error?.error || error || 1)
     }
@@ -224,6 +260,8 @@ class TracingPlugin extends Plugin {
       links: childOf?._links,
     })
 
+    this.stampIntegrationService(span, serviceName)
+
     analyticsSampler.sample(span, config.measured)
 
     // TODO: Remove this after migration to TracingChannel is done.