dd-trace 5.86.0 → 5.88.0

package/packages/dd-trace/src/opentelemetry/context_manager.js

@@ -2,6 +2,7 @@
 
 const { trace, ROOT_CONTEXT, propagation } = require('@opentelemetry/api')
 const { storage } = require('../../../datadog-core')
+const { getAllBaggageItems, setBaggageItem, removeAllBaggageItems } = require('../baggage')
 
 const tracer = require('../../')
 const SpanContext = require('./span_context')
@@ -19,31 +20,26 @@ class ContextManager {
 
     const storedSpan = store ? trace.getSpan(store) : null
 
+    // Convert DD baggage to OTel format
+    const baggages = getAllBaggageItems()
+    const hasBaggage = Object.keys(baggages).length > 0
+    let otelBaggages
+    if (hasBaggage) {
+      const entries = {}
+      for (const [key, value] of Object.entries(baggages)) {
+        entries[key] = { value }
+      }
+      otelBaggages = propagation.createBaggage(entries)
+    }
+
     // If stored span wraps the active DD span, prefer the stored context
     if (storedSpan && storedSpan._ddSpan === activeSpan) {
-      const baggages = JSON.parse(activeSpan.getAllBaggageItems())
-      if (Object.keys(baggages).length > 0) {
-        const entries = {}
-        for (const [key, value] of Object.entries(baggages)) {
-          entries[key] = { value }
-        }
-        const otelBaggages = propagation.createBaggage(entries)
-        return propagation.setBaggage(store, otelBaggages)
-      }
+      if (otelBaggages) return propagation.setBaggage(store, otelBaggages)
       return store
     }
 
     if (!activeSpan) {
-      const storedBaggageItems = storedSpan?._spanContext?._ddContext?._baggageItems
-      if (storedBaggageItems) {
-        const baggages = storedBaggageItems
-        const entries = {}
-        for (const [key, value] of Object.entries(baggages)) {
-          entries[key] = { value }
-        }
-        const otelBaggages = propagation.createBaggage(entries)
-        return propagation.setBaggage(baseContext, otelBaggages)
-      }
+      if (otelBaggages) return propagation.setBaggage(baseContext, otelBaggages)
       return baseContext
     }
 
@@ -53,18 +49,6 @@ class ContextManager {
       ddContext._otelSpanContext = new SpanContext(ddContext)
     }
 
-    // Convert DD baggage to OTel format
-    const baggages = JSON.parse(activeSpan.getAllBaggageItems())
-    const hasBaggage = Object.keys(baggages).length > 0
-    let otelBaggages
-    if (hasBaggage) {
-      const entries = {}
-      for (const [key, value] of Object.entries(baggages)) {
-        entries[key] = { value }
-      }
-      otelBaggages = propagation.createBaggage(entries)
-    }
-
     if (store && trace.getSpanContext(store) === ddContext._otelSpanContext) {
       return otelBaggages ? propagation.setBaggage(store, otelBaggages) : store
     }
@@ -86,22 +70,11 @@ class ContextManager {
     if (baggages) {
       baggageItems = baggages.getAllEntries()
     }
-    if (span && span._ddSpan) {
-      // does otel always override datadog?
-      span._ddSpan.removeAllBaggageItems()
-      for (const baggage of baggageItems) {
-        span._ddSpan.setBaggageItem(baggage[0], baggage[1].value)
-      }
-      return ddScope.activate(span._ddSpan, run)
-    }
-    // span instanceof NonRecordingSpan
-    const ddContext = span?._spanContext?._ddContext
-    if (ddContext && ddContext._baggageItems) {
-      ddContext._baggageItems = {}
-      for (const baggage of baggageItems) {
-        ddContext._baggageItems[baggage[0]] = baggage[1].value
-      }
+    removeAllBaggageItems()
+    for (const baggage of baggageItems) {
+      setBaggageItem(baggage[0], baggage[1].value)
     }
+    if (span && span._ddSpan) return ddScope.activate(span._ddSpan, run)
     return run()
   }
 

package/packages/dd-trace/src/opentelemetry/otlp/otlp_http_exporter_base.js

@@ -20,7 +20,7 @@ class OtlpHttpExporterBase {
    * Creates a new OtlpHttpExporterBase instance.
    *
    * @param {string} url - OTLP endpoint URL
-   * @param {string} headers - Additional HTTP headers as comma-separated key=value string
+   * @param {string|undefined} headers - Additional HTTP headers as comma-separated key=value string
    * @param {number} timeout - Request timeout in milliseconds
    * @param {string} protocol - OTLP protocol (http/protobuf or http/json)
    * @param {string} defaultPath - Default path to use if URL has no path
@@ -117,11 +117,10 @@ class OtlpHttpExporterBase {
 
   /**
    * Parses additional HTTP headers from a comma-separated string.
-   * @param {string} headersString - Comma-separated key=value pairs
+   * @param {string} [headersString=''] - Comma-separated key=value pairs
    * @returns {Record<string, string>} Parsed headers object
-   * @private
    */
-  #parseAdditionalHeaders (headersString) {
+  #parseAdditionalHeaders (headersString = '') {
     const headers = {}
     let key = ''
     let value = ''

package/packages/dd-trace/src/opentracing/propagation/text_map.js

@@ -670,10 +670,8 @@ class TextMapPropagator {
     if (!this._hasPropagationStyle('extract', 'baggage')) return
     if (!carrier?.baggage) return
     const baggages = carrier.baggage.split(',')
-    const tagAllKeys = this._config.baggageTagKeys === '*'
-    const keysToSpanTag = tagAllKeys
-      ? undefined
-      : new Set(this._config.baggageTagKeys.split(','))
+    const baggageTagKeys = new Set(this._config.baggageTagKeys)
+    const tagAllKeys = baggageTagKeys.has('*')
     for (const keyValue of baggages) {
       if (!keyValue) continue
 
@@ -707,7 +705,7 @@ class TextMapPropagator {
         return
       }
 
-      if (spanContext && (tagAllKeys || keysToSpanTag?.has(key))) {
+      if (spanContext && (tagAllKeys || baggageTagKeys.has(key))) {
         spanContext._trace.tags['baggage.' + key] = value
       }
       setBaggageItem(key, value)

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

@@ -3,7 +3,6 @@
 // TODO (new internal tracer): use DC events for lifecycle metrics and test them
 const { performance } = require('perf_hooks')
 const now = performance.now.bind(performance)
-const dateNow = Date.now
 const util = require('util')
 const { channel } = require('dc-polyfill')
 const id = require('../id')
@@ -13,12 +12,15 @@ const log = require('../log')
 const { storage } = require('../../../datadog-core')
 const telemetryMetrics = require('../telemetry/metrics')
 const { getValueFromEnvSources } = require('../config/helper')
+const { isTrue } = require('../util')
 const SpanContext = require('./span_context')
 
+const dateNow = Date.now
+
 const tracerMetrics = telemetryMetrics.manager.namespace('tracers')
 
-const DD_TRACE_EXPERIMENTAL_STATE_TRACKING = getValueFromEnvSources('DD_TRACE_EXPERIMENTAL_STATE_TRACKING')
-const DD_TRACE_EXPERIMENTAL_SPAN_COUNTS = getValueFromEnvSources('DD_TRACE_EXPERIMENTAL_SPAN_COUNTS')
+const DD_TRACE_EXPERIMENTAL_STATE_TRACKING = isTrue(getValueFromEnvSources('DD_TRACE_EXPERIMENTAL_STATE_TRACKING'))
+const DD_TRACE_EXPERIMENTAL_SPAN_COUNTS = isTrue(getValueFromEnvSources('DD_TRACE_EXPERIMENTAL_SPAN_COUNTS'))
 
 const unfinishedRegistry = createRegistry('unfinished')
 const finishedRegistry = createRegistry('finished')
@@ -251,7 +253,7 @@ class DatadogSpan {
       return
     }
 
-    if (DD_TRACE_EXPERIMENTAL_STATE_TRACKING === 'true' && !this._spanContext._tags['service.name']) {
+    if (DD_TRACE_EXPERIMENTAL_STATE_TRACKING && !this._spanContext._tags['service.name']) {
       log.error('Finishing invalid span: %s', this)
     }
 

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

@@ -63,6 +63,8 @@ const {
   getPullRequestDiff,
   getModifiedFilesFromDiff,
   getPullRequestBaseBranch,
+  getSessionRequestErrorTags,
+  DD_CI_LIBRARY_CONFIGURATION_ERROR,
   TEST_IS_TEST_FRAMEWORK_WORKER,
   TEST_IS_NEW,
   TEST_IS_RUM_ACTIVE,
@@ -120,6 +122,7 @@ module.exports = class CiPlugin extends Plugin {
     this.fileLineToProbeId = new Map()
     this.rootDir = process.cwd() // fallback in case :session:start events are not emitted
     this._testSuiteSpansByTestSuite = new Map()
+    this._pendingRequestErrorTags = []
 
     this.addSub(`ci:${this.constructor.id}:library-configuration`, (ctx) => {
       const { onDone, isParallel, frameworkVersion } = ctx
@@ -131,10 +134,15 @@ module.exports = class CiPlugin extends Plugin {
       this.tracer._exporter.getLibraryConfiguration(this.testConfiguration, (err, libraryConfig) => {
         if (err) {
           log.error('Library configuration could not be fetched. %s', err.message)
+          this._addRequestErrorTag(DD_CI_LIBRARY_CONFIGURATION_ERROR, err)
         } else {
           this.libraryConfig = libraryConfig
         }
 
+        const requestErrorTags = this.testSessionSpan
+          ? getSessionRequestErrorTags(this.testSessionSpan)
+          : Object.fromEntries(this._pendingRequestErrorTags.map(({ tag, value }) => [tag, value]))
+
         const libraryCapabilitiesTags = getLibraryCapabilitiesTags(this.constructor.id, isParallel, frameworkVersion)
         const metadataTags = {
           test: {
@@ -142,7 +150,7 @@ module.exports = class CiPlugin extends Plugin {
           },
         }
         this.tracer._exporter.addMetadataTags(metadataTags)
-        onDone({ err, libraryConfig })
+        onDone({ err, libraryConfig, requestErrorTags })
       })
     })
 
@@ -200,6 +208,10 @@ module.exports = class CiPlugin extends Plugin {
         },
         integrationName: this.constructor.id,
       })
+      for (const { tag, value } of this._pendingRequestErrorTags) {
+        this.testSessionSpan.setTag(tag, value)
+      }
+      this._pendingRequestErrorTags = []
       // TODO: add telemetry tag when we can add `is_agentless_log_submission_enabled` for agentless log submission
       this.telemetry.ciVisEvent(TELEMETRY_EVENT_CREATED, 'session')
 
@@ -209,6 +221,7 @@ module.exports = class CiPlugin extends Plugin {
           [COMPONENT]: this.constructor.id,
           ...this.testEnvironmentMetadata,
           ...testModuleSpanMetadata,
+          ...getSessionRequestErrorTags(this.testSessionSpan),
         },
         integrationName: this.constructor.id,
       })
@@ -230,7 +243,10 @@ 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]
       for (const testSuite of skippedSuites) {
-        const testSuiteMetadata = getTestSuiteCommonTags(testCommand, frameworkVersion, testSuite, this.constructor.id)
+        const testSuiteMetadata = {
+          ...getTestSuiteCommonTags(testCommand, frameworkVersion, testSuite, this.constructor.id),
+          ...getSessionRequestErrorTags(this.testSessionSpan),
+        }
         if (this.itrCorrelationId) {
           testSuiteMetadata[ITR_CORRELATION_ID] = this.itrCorrelationId
         }
@@ -261,8 +277,10 @@ module.exports = class CiPlugin extends Plugin {
       this.tracer._exporter.getKnownTests(this.testConfiguration, (err, knownTests) => {
         if (err) {
           log.error('Known tests could not be fetched. %s', err.message)
-          this.libraryConfig.isEarlyFlakeDetectionEnabled = false
-          this.libraryConfig.isKnownTestsEnabled = false
+          if (this.libraryConfig) {
+            this.libraryConfig.isEarlyFlakeDetectionEnabled = false
+            this.libraryConfig.isKnownTestsEnabled = false
+          }
         }
         onDone({ err, knownTests })
       })
@@ -279,7 +297,9 @@ module.exports = class CiPlugin extends Plugin {
       this.tracer._exporter.getTestManagementTests(this.testConfiguration, (err, testManagementTests) => {
         if (err) {
           log.error('Test management tests could not be fetched. %s', err.message)
-          this.libraryConfig.isTestManagementEnabled = false
+          if (this.libraryConfig) {
+            this.libraryConfig.isTestManagementEnabled = false
+          }
         }
         onDone({ err, testManagementTests })
       })
@@ -346,8 +366,15 @@ module.exports = class CiPlugin extends Plugin {
             span.meta = {
               ...span.meta,
               ...testSuiteTags,
+              ...getSessionRequestErrorTags(this.testSessionSpan),
             }
           }
+
+          // Jest and Vitest worker test spans are serialized in the worker and may not include
+          // request error tags; add them from the session span in the main process.
+          if ((span.name === 'jest.test' || span.name === 'vitest.test') && this.testSessionSpan) {
+            Object.assign(span.meta, getSessionRequestErrorTags(this.testSessionSpan))
+          }
         }
         this.tracer._exporter.export(trace)
       }
@@ -418,6 +445,30 @@ module.exports = class CiPlugin extends Plugin {
     }
   }
 
+  /**
+   * Adds a hidden _dd tag to the test session span when a test-optimization request fails.
+   * If the session span does not exist yet (e.g. library-configuration failed before session:start),
+   * the tag is queued and applied when the span is created.
+   * @param {string} tag - Tag name (e.g. DD_CI_LIBRARY_CONFIGURATION_ERROR)
+   * @param {Error} err - Request error
+   */
+  _addRequestErrorTag (tag, err) {
+    const value = 'true'
+    if (this.testSessionSpan) {
+      this.testSessionSpan.setTag(tag, value)
+    } else {
+      this._pendingRequestErrorTags.push({ tag, value })
+    }
+  }
+
+  /**
+   * Returns request error tags from the test session span for propagation to module, suite and test spans.
+   * @returns {Record<string, string>}
+   */
+  getSessionRequestErrorTags () {
+    return getSessionRequestErrorTags(this.testSessionSpan)
+  }
+
   configure (config, shouldGetEnvironmentData = true) {
     super.configure(config)
 
@@ -529,6 +580,7 @@ module.exports = class CiPlugin extends Plugin {
         [TEST_SESSION_ID]: testSuiteSpan.context().toTraceId(),
         [TEST_COMMAND]: testSuiteSpan.context()._tags[TEST_COMMAND],
         [TEST_MODULE]: this.constructor.id,
+        ...getSessionRequestErrorTags(this.testSessionSpan),
       }
       if (testSuiteSpan.context()._parentId) {
         suiteTags[TEST_MODULE_ID] = testSuiteSpan.context()._parentId.toString(10)

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

@@ -1,88 +1,94 @@
 'use strict'
 
 const { PEER_SERVICE_KEY, PEER_SERVICE_SOURCE_KEY } = require('../constants')
+const propagationHash = require('../propagation-hash')
 const StoragePlugin = require('./storage')
 
 class DatabasePlugin extends StoragePlugin {
   static operation = 'query'
   static peerServicePrecursors = ['db.name']
 
-  constructor (...args) {
-    super(...args)
-    this.serviceTags = {
-      dddbs: '',
-      encodedDddbs: '',
-      dde: '',
-      encodedDde: '',
-      ddps: '',
-      encodedDdps: '',
-      ddpv: '',
-      encodedDdpv: '',
-    }
-  }
-
-  encodingServiceTags (serviceTag, encodeATag, spanConfig) {
-    if (serviceTag !== spanConfig) {
-      this.serviceTags[serviceTag] = spanConfig
-      this.serviceTags[encodeATag] = encodeURIComponent(spanConfig)
-    }
-  }
-
-  createDBMPropagationCommentService (serviceName, span) {
-    this.encodingServiceTags('dddbs', 'encodedDddbs', serviceName)
-    this.encodingServiceTags('dde', 'encodedDde', this.tracer._env)
-    this.encodingServiceTags('ddps', 'encodedDdps', this.tracer._service)
-    this.encodingServiceTags('ddpv', 'encodedDdpv', this.tracer._version)
-    if (span.context()._tags['out.host']) {
-      this.encodingServiceTags('ddh', 'encodedDdh', span._spanContext._tags['out.host'])
-    }
-    if (span.context()._tags['db.name']) {
-      this.encodingServiceTags('dddb', 'encodedDddb', span._spanContext._tags['db.name'])
-    }
-
-    const { encodedDddb, encodedDddbs, encodedDde, encodedDdh, encodedDdps, encodedDdpv } = this.serviceTags
+  /**
+   * @param {string} serviceName
+   * @param {import('../../../..').Span} span
+   * @param {object} peerData
+   * @returns {string}
+   */
+  #createDBMPropagationCommentService (serviceName, span, peerData) {
+    const spanTags = span.context()._tags
+    const encodedDddb = encode(spanTags['db.name'])
+    const encodedDddbs = encode(serviceName)
+    const encodedDde = encode(this.tracer._env)
+    const encodedDdh = encode(spanTags['out.host'])
+    const encodedDdps = this.tracer._service ?? ''
+    const encodedDdpv = this.tracer._version
 
     let dbmComment = `dddb='${encodedDddb}',dddbs='${encodedDddbs}',dde='${encodedDde}',ddh='${encodedDdh}',` +
       `ddps='${encodedDdps}',ddpv='${encodedDdpv}'`
 
-    const peerData = this.getPeerService(span.context()._tags)
     if (peerData !== undefined && peerData[PEER_SERVICE_SOURCE_KEY] === PEER_SERVICE_KEY) {
-      this.encodingServiceTags('ddprs', 'encodedDdprs', peerData[PEER_SERVICE_KEY])
-
-      const { encodedDdprs } = this.serviceTags
-      dbmComment += `,ddprs='${encodedDdprs}'`
+      dbmComment += `,ddprs='${encode(peerData[PEER_SERVICE_KEY])}'`
     }
     return dbmComment
   }
 
-  getDbmServiceName (span, tracerService) {
+  /**
+   * @param {string} tracerService
+   * @param {object} peerData
+   * @returns {string}
+   */
+  #getDbmServiceName (tracerService, peerData) {
     if (this._tracerConfig.spanComputePeerService) {
-      const peerData = this.getPeerService(span.context()._tags)
       return this.getPeerServiceRemap(peerData)[PEER_SERVICE_KEY] || tracerService
     }
     return tracerService
   }
 
+  /**
+   * @param {import('../../../..').Span} span
+   * @param {string} serviceName
+   * @param {boolean} disableFullMode
+   */
   createDbmComment (span, serviceName, disableFullMode = false) {
     const mode = this.config.dbmPropagationMode
-    const dbmService = this.getDbmServiceName(span, serviceName)
 
     if (mode === 'disabled') {
       return null
     }
 
-    const servicePropagation = this.createDBMPropagationCommentService(dbmService, span)
+    const peerData = this.getPeerService(span.context()._tags)
+    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']) {
+      const hashBase64 = propagationHash.getHashBase64()
+      if (hashBase64) {
+        dbmComment += `,ddsh='${hashBase64}'`
+        // Add hash to span meta as a tag
+        span.setTag('_dd.dbm.propagation_hash', hashBase64)
+      }
+    }
 
     if (disableFullMode || mode === 'service') {
-      return servicePropagation
+      return dbmComment
     } else if (mode === 'full') {
       span.setTag('_dd.dbm_trace_injected', 'true')
       span._processor.sample(span)
       const traceparent = span._spanContext.toTraceparent()
-      return `${servicePropagation},traceparent='${traceparent}'`
+      return `${dbmComment},traceparent='${traceparent}'`
     }
   }
 
+  /**
+   * @param {import('../../../..').Span} span
+   * @param {string} query
+   * @param {string} serviceName
+   * @param {boolean} disableFullMode
+   * @returns {string}
+   */
   injectDbmQuery (span, query, serviceName, disableFullMode = false) {
     const dbmTraceComment = this.createDbmComment(span, serviceName, disableFullMode)
 
@@ -95,6 +101,10 @@ class DatabasePlugin extends StoragePlugin {
       : `/*${dbmTraceComment}*/ ${query}`
   }
 
+  /**
+   * @param {string} query
+   * @returns {string}
+   */
   maybeTruncate (query) {
     const maxLength = typeof this.config.truncate === 'number'
       ? this.config.truncate
@@ -108,4 +118,6 @@ class DatabasePlugin extends StoragePlugin {
   }
 }
 
+const encode = value => value ? encodeURIComponent(value) : ''
+
 module.exports = DatabasePlugin

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

@@ -18,6 +18,10 @@ const COMMON_PEER_SVC_SOURCE_TAGS = [
 
 // TODO: Exit span on finish when AsyncResource instances are removed.
 class OutboundPlugin extends TracingPlugin {
+  /**
+   *
+   * @type {string[]}
+   */
   static peerServicePrecursors = []
 
   constructor (...args) {
@@ -28,12 +32,15 @@ class OutboundPlugin extends TracingPlugin {
     })
   }
 
+  /**
+   * @param {{ parentStore?: { span: import('../../../..').Span } }} ctx
+   */
   bindFinish (ctx) {
     return ctx.parentStore
   }
 
-  startSpan (...args) {
-    const span = super.startSpan(...args)
+  startSpan (name, options, enterOrCtx) {
+    const span = super.startSpan(name, options, enterOrCtx)
     if (
       this._tracerConfig.codeOriginForSpans.enabled &&
       this._tracerConfig.codeOriginForSpans.experimental.exit_spans.enabled
@@ -43,6 +50,9 @@ class OutboundPlugin extends TracingPlugin {
     return span
   }
 
+  /**
+   * @param {Record<string, string>} tags
+   */
   getPeerService (tags) {
     /**
      * Compute `peer.service` and associated metadata from available tags, based
@@ -75,6 +85,9 @@ class OutboundPlugin extends TracingPlugin {
     }
   }
 
+  /**
+   * @param {Record<string, string>} peerData
+   */
   getPeerServiceRemap (peerData) {
     /**
      * If DD_TRACE_PEER_SERVICE_MAPPING is matched, we need to override the existing
@@ -92,6 +105,9 @@ class OutboundPlugin extends TracingPlugin {
     return peerData
   }
 
+  /**
+   * @param {{ currentStore?: { span: import('../../../..').Span } }} ctx
+   */
   finish (ctx) {
     const span = ctx?.currentStore?.span || this.activeSpan
     this.tagPeerService(span)
@@ -104,6 +120,9 @@ class OutboundPlugin extends TracingPlugin {
     super.finish(...arguments)
   }
 
+  /**
+   * @param {import('../../../..').Span} span
+   */
   tagPeerService (span) {
     if (this._tracerConfig.spanComputePeerService) {
       const peerData = this.getPeerService(span.context()._tags)
@@ -113,10 +132,16 @@ class OutboundPlugin extends TracingPlugin {
     }
   }
 
+  /**
+   * @param {object} ctx
+   */
   connect (ctx) {
     this.addHost(ctx)
   }
 
+  /**
+   * @param {{ hostname: string, port: number, currentStore?: { span: import('../../../..').Span } }} ctx
+   */
   addHost (ctx) {
     const { hostname, port } = ctx
 

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

@@ -16,11 +16,18 @@ class TracingPlugin extends Plugin {
   }
 
   get activeSpan () {
-    const store = storage('legacy').getStore()
+    const store = /** @type {{ span?: import('../../../..').Span }} */ (storage('legacy').getStore())
 
-    return store && store.span
+    return store?.span
   }
 
+  /**
+   * @param {object} opts
+   * @param {string} [opts.type]
+   * @param {string} [opts.id]
+   * @param {string} [opts.kind]
+   * @returns {string}
+   */
   serviceName (opts = {}) {
     const {
       type = this.constructor.type,
@@ -31,6 +38,13 @@ class TracingPlugin extends Plugin {
     return this._tracer._nomenclature.serviceName(type, kind, id, opts)
   }
 
+  /**
+   * @param {object} opts
+   * @param {string} [opts.type]
+   * @param {string} [opts.id]
+   * @param {string} [opts.kind]
+   * @returns {string}
+   */
   operationName (opts = {}) {
     const {
       type = this.constructor.type,
@@ -41,6 +55,10 @@ class TracingPlugin extends Plugin {
     return this._tracer._nomenclature.opName(type, kind, id, opts)
   }
 
+  /**
+   * @param {object} config
+   * @returns {object}
+   */
   configure (config) {
     return super.configure({
       ...config,
@@ -53,11 +71,17 @@ class TracingPlugin extends Plugin {
 
   start () {} // implemented by individual plugins
 
+  /**
+   * @param {{ currentStore?: { span: import('../../../..').Span } }} ctx
+   */
   finish (ctx) {
     const span = ctx?.currentStore?.span || this.activeSpan
     span?.finish()
   }
 
+  /**
+   * @param {{ currentStore?: { span: import('../../../..').Span }, error?: unknown }} ctxOrError
+   */
   error (ctxOrError) {
     if (ctxOrError?.currentStore) {
       ctxOrError.currentStore?.span.setTag('error', ctxOrError?.error)
@@ -84,21 +108,32 @@ class TracingPlugin extends Plugin {
     }
   }
 
+  /**
+   * @param {string} eventName
+   * @param {Function} handler
+   */
   addTraceSub (eventName, handler) {
     const prefix = this.constructor.prefix || `apm:${this.component}:${this.operation}`
     this.addSub(`${prefix}:${eventName}`, handler)
   }
 
+  /**
+   * @param {string} eventName
+   * @param {Function} transform
+   */
   addTraceBind (eventName, transform) {
     const prefix = this.constructor.prefix || `apm:${this.component}:${this.operation}`
     this.addBind(`${prefix}:${eventName}`, transform)
   }
 
+  /**
+   * @param {unknown} error
+   * @param {import('../../../..').Span} [span]
+   */
   addError (error, span = this.activeSpan) {
     if (span && !span._spanContext._tags.error) {
       // Errors may be wrapped in a context.
-      error = (error && error.error) || error
-      span.setTag('error', error || 1)
+      span.setTag('error', error?.error || error || 1)
     }
   }