dd-trace 5.100.0 → 5.101.0

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

@@ -4,6 +4,7 @@ const { trace, ROOT_CONTEXT, propagation } = require('@opentelemetry/api')
 const { storage } = require('../../../datadog-core')
 const { getAllBaggageItems, setAllBaggageItems, removeAllBaggageItems } = require('../baggage')
 
+const ActiveSpanProxy = require('./active-span-proxy')
 const SpanContext = require('./span_context')
 
 class ContextManager {
@@ -48,11 +49,19 @@ class ContextManager {
       ddContext._otelSpanContext = new SpanContext(ddContext)
     }
 
-    if (store && trace.getSpanContext(store) === ddContext._otelSpanContext) {
+    // Cache the active-span proxy next to the bridge span context. This lets
+    // `trace.getActiveSpan()` forward attribute/status/link/exception writes
+    // onto the active Datadog span rather than returning a NonRecordingSpan
+    // whose mutation methods are silent no-ops.
+    if (!ddContext._otelActiveSpan) {
+      ddContext._otelActiveSpan = new ActiveSpanProxy(activeSpan, ddContext._otelSpanContext)
+    }
+
+    if (store && trace.getSpan(store) === ddContext._otelActiveSpan) {
       return otelBaggages ? propagation.setBaggage(store, otelBaggages) : store
     }
 
-    const wrappedContext = trace.setSpanContext(baseContext, ddContext._otelSpanContext)
+    const wrappedContext = trace.setSpan(baseContext, ddContext._otelActiveSpan)
     return otelBaggages ? propagation.setBaggage(wrappedContext, otelBaggages) : wrappedContext
   }
 

package/packages/dd-trace/src/opentelemetry/span-helpers.js

@@ -1,21 +1,27 @@
 'use strict'
 
+const { performance } = require('node:perf_hooks')
+
+const { timeInputToHrTime } = require('../../../../vendor/dist/@opentelemetry/core')
+
 const { ERROR_MESSAGE, ERROR_STACK, ERROR_TYPE, IGNORE_OTEL_ERROR } = require('../constants')
 const DatadogSpanContext = require('../opentracing/span_context')
 const TraceState = require('../opentracing/propagation/tracestate')
 
 const id = require('../id')
 
+const { timeOrigin } = performance
+
 /**
- * @typedef {{ toTraceId: (get128?: boolean) => string, toSpanId: (get128?: boolean) => string }} DatadogContextLike
- * @typedef {{ _ddContext: import('../opentracing/span_context') }} OtelBridgeSpanContextLike
  * @typedef {{
- *   traceId: string,
- *   spanId: string,
+ *   _ddContext?: import('../opentracing/span_context'),
+ *   toTraceId?: (get128?: boolean) => string,
+ *   toSpanId?: (get128?: boolean) => string,
+ *   traceId?: string,
+ *   spanId?: string,
  *   traceFlags?: number,
  *   traceState?: { serialize: () => string }
- * }} OtelSpanContextLike
- * @typedef {DatadogContextLike | OtelBridgeSpanContextLike | OtelSpanContextLike} LinkContextLike
+ * }} LinkContextLike
  * @typedef {{ context: LinkContextLike, attributes?: Record<string, unknown> }} OtelLink
  * @typedef {{
  *   name?: string,
@@ -24,56 +30,119 @@ const id = require('../id')
  *   type?: string,
  *   escaped?: unknown
  * }} ExceptionLike
- * @typedef {{
- *   addEvent: (name: string, attributes: Record<string, unknown>, timeInput?: unknown) => unknown
- * }} EventTarget
+ * @typedef {number | Date | [number, number]} TimeInput
+ */
+
+/**
+ * @param {import('../opentracing/span')} ddSpan
  */
+function isWritable (ddSpan) {
+  return ddSpan._duration === undefined
+}
 
 /**
- * Normalize any Datadog/OTel span-context shape to a `DatadogSpanContext`.
+ * @param {unknown} value
+ * @returns {value is TimeInput}
+ */
+function isTimeInput (value) {
+  return typeof value === 'number' ||
+    value instanceof Date ||
+    (Array.isArray(value) && value.length === 2 &&
+      typeof value[0] === 'number' && typeof value[1] === 'number')
+}
+
+/**
+ * @param {LinkContextLike} ctx
+ * @returns {ctx is import('../opentracing/span_context')}
+ */
+function isDatadogSpanContext (ctx) {
+  return typeof ctx.toTraceId === 'function' && typeof ctx.toSpanId === 'function'
+}
+
+/**
+ * @param {unknown} link
+ * @returns {link is OtelLink}
+ */
+function isOtelLink (link) {
+  return typeof link === 'object' && link !== null && 'context' in link
+}
+
+/**
+ * The OTel-shipped `hrTimeToMilliseconds` rounds, which drops sub-millisecond precision.
+ *
+ * @param {TimeInput} [timeInput]
+ */
+function timeInputToMilliseconds (timeInput) {
+  const hrTime = timeInputToHrTime(timeInput || (performance.now() + timeOrigin))
+  return hrTime[0] * 1e3 + hrTime[1] / 1e6
+}
+
+/**
+ * Resolves the OTel `addEvent(name, attributesOrStartTime, startTime)` overloads into a
+ * `{ attributes, startTime }` pair where `startTime` is always a millisecond number, so the
+ * caller can hand the OTel inputs straight to `DatadogSpan.addEvent` without `Date`/hrTime
+ * confusion.
+ *
+ * @param {Record<string, unknown> | TimeInput | undefined} attributesOrStartTime
+ * @param {TimeInput} [startTime]
+ */
+function normalizeOtelEvent (attributesOrStartTime, startTime) {
+  let attributes
+  if (attributesOrStartTime) {
+    if (isTimeInput(attributesOrStartTime)) {
+      startTime = attributesOrStartTime
+    } else if (typeof attributesOrStartTime === 'object') {
+      attributes = attributesOrStartTime
+    }
+  }
+  return { attributes, startTime: timeInputToMilliseconds(startTime) }
+}
+
+/**
+ * Accepts the native `DatadogSpanContext` (`toTraceId`/`toSpanId`), the bridge wrapper
+ * (`_ddContext`), or a standard OTel `SpanContext` (`traceId`/`spanId` strings); returns
+ * a `DatadogSpanContext` or `undefined` when nothing usable is present.
  *
  * @param {LinkContextLike | undefined | null} context
- * @returns {import('../opentracing/span_context') | undefined}
  */
 function normalizeLinkContext (context) {
   if (!context) return
 
-  const bridgeCtx = /** @type {OtelBridgeSpanContextLike} */ (context)
-  if (bridgeCtx._ddContext) return bridgeCtx._ddContext
+  if (context._ddContext) return context._ddContext
 
-  const ddCtx = /** @type {DatadogContextLike} */ (context)
-  if (typeof ddCtx.toTraceId === 'function' && typeof ddCtx.toSpanId === 'function') {
-    return /** @type {import('../opentracing/span_context')} */ (/** @type {unknown} */ (context))
-  }
+  if (isDatadogSpanContext(context)) return context
 
-  const otelCtx = /** @type {OtelSpanContextLike} */ (context)
-  if (typeof otelCtx.traceId !== 'string' || typeof otelCtx.spanId !== 'string') return
+  if (typeof context.traceId !== 'string' || typeof context.spanId !== 'string') return
 
   let sampling
-  if (typeof otelCtx.traceFlags === 'number') {
-    sampling = { priority: otelCtx.traceFlags & 1 }
+  if (typeof context.traceFlags === 'number') {
+    sampling = { priority: context.traceFlags & 1 }
   }
 
   let tracestate
-  if (otelCtx.traceState?.serialize) {
-    tracestate = TraceState.fromString(otelCtx.traceState.serialize())
+  if (context.traceState?.serialize) {
+    tracestate = TraceState.fromString(context.traceState.serialize())
   }
 
   return new DatadogSpanContext({
-    traceId: id(otelCtx.traceId, 16),
-    spanId: id(otelCtx.spanId, 16),
+    traceId: id(context.traceId, 16),
+    spanId: id(context.spanId, 16),
     sampling,
     tracestate,
   })
 }
 
 /**
+ * Mirrors `http.response.status_code` onto `http.status_code` (DD's special tag used by APM
+ * trace metrics and client-side stats); both names end up on the span.
+ *
  * @param {import('../opentracing/span')} ddSpan
  * @param {string} key
  * @param {unknown} value
- * @returns {void}
  */
 function setOtelAttribute (ddSpan, key, value) {
+  if (!isWritable(ddSpan)) return
+
   if (key === 'http.response.status_code') {
     ddSpan.setTag('http.status_code', String(value))
   }
@@ -82,16 +151,19 @@ function setOtelAttribute (ddSpan, key, value) {
 }
 
 /**
+ * Same `http.status_code` mirror as `setOtelAttribute`; does not mutate the caller's
+ * `attributes` object.
+ *
  * @param {import('../opentracing/span')} ddSpan
  * @param {Record<string, unknown>} attributes
- * @returns {void}
  */
 function setOtelAttributes (ddSpan, attributes) {
-  if ('http.response.status_code' in attributes) {
-    attributes['http.status_code'] = String(attributes['http.response.status_code'])
-  }
+  if (!isWritable(ddSpan)) return
 
   ddSpan.addTags(attributes)
+  if ('http.response.status_code' in attributes) {
+    ddSpan.setTag('http.status_code', String(attributes['http.response.status_code']))
+  }
 }
 
 /**
@@ -100,28 +172,60 @@ function setOtelAttributes (ddSpan, attributes) {
  * @param {import('../opentracing/span')} ddSpan
  * @param {LinkContextLike | OtelLink} link
  * @param {Record<string, unknown>} [attrs]
- * @returns {void}
  */
 function addOtelLink (ddSpan, link, attrs) {
+  if (!isWritable(ddSpan) || !link) return
+
   // TODO: Drop the (context, attrs) form in v6.0.0.
-  const linkObj = link && typeof link === 'object' && 'context' in link
-    ? /** @type {OtelLink} */ (link)
-    : { context: /** @type {LinkContextLike} */ (link), attributes: attrs ?? {} }
+  const { context, attributes } = isOtelLink(link)
+    ? link
+    : { context: link, attributes: attrs ?? {} }
 
-  const ddSpanContext = normalizeLinkContext(linkObj.context)
+  const ddSpanContext = normalizeLinkContext(context)
   if (!ddSpanContext) return
 
-  ddSpan.addLink({ context: ddSpanContext, attributes: linkObj.attributes })
+  ddSpan.addLink({ context: ddSpanContext, attributes })
+}
+
+/**
+ * Forwards the array-form `addLinks` overload; non-array inputs are silently ignored to
+ * match the OTel API's lenient handling.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {Array<LinkContextLike | OtelLink>} links
+ */
+function addOtelLinks (ddSpan, links) {
+  if (!isWritable(ddSpan) || !Array.isArray(links)) return
+
+  for (const link of links) {
+    addOtelLink(ddSpan, link)
+  }
+}
+
+/**
+ * Owns the OTel `addEvent(name, attributesOrStartTime, startTime)` overload normalization so
+ * the bridge classes can delegate without touching `Date`/hrTime conversion.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} name
+ * @param {Record<string, unknown> | TimeInput | undefined} [attributesOrStartTime]
+ * @param {TimeInput} [startTime]
+ */
+function addOtelEvent (ddSpan, name, attributesOrStartTime, startTime) {
+  if (!isWritable(ddSpan)) return
+
+  const event = normalizeOtelEvent(attributesOrStartTime, startTime)
+  ddSpan.addEvent(name, event.attributes, event.startTime)
 }
 
 /**
  * @param {import('../opentracing/span')} ddSpan
- * @param {EventTarget} eventTarget
  * @param {ExceptionLike} exception
- * @param {unknown} [timeInput]
- * @returns {void}
+ * @param {TimeInput} [timeInput]
  */
-function recordException (ddSpan, eventTarget, exception, timeInput) {
+function recordException (ddSpan, exception, timeInput) {
+  if (!isWritable(ddSpan)) return
+
   ddSpan.addTags({
     [ERROR_TYPE]: exception.name,
     [ERROR_MESSAGE]: exception.message,
@@ -129,42 +233,76 @@ function recordException (ddSpan, eventTarget, exception, timeInput) {
     [IGNORE_OTEL_ERROR]: ddSpan.context()._tags[IGNORE_OTEL_ERROR] ?? true,
   })
 
-  /** @type {Record<string, unknown>} */
   const attributes = {}
   if (exception.message) attributes['exception.message'] = exception.message
   if (exception.type) attributes['exception.type'] = exception.type
   if (exception.escaped) attributes['exception.escaped'] = exception.escaped
   if (exception.stack) attributes['exception.stacktrace'] = exception.stack
 
-  eventTarget.addEvent(exception.name ?? 'Error', attributes, timeInput)
+  ddSpan.addEvent(exception.name ?? 'Error', attributes, timeInputToMilliseconds(timeInput))
 }
 
 /**
- * First-call-wins; no-op on ended spans. Only `code === 2` emits Datadog error tags.
+ * Applies OTel `setStatus({ code, message })` per spec: UNSET / missing is a no-op, OK is
+ * final, ERROR is replaceable. Only ERROR writes tags; the returned code is the one the
+ * caller must store for the next call.
  *
  * @param {import('../opentracing/span')} ddSpan
- * @param {{ ended: boolean, _hasStatus: boolean }} bridgeSpan
+ * @param {number} currentCode 0 = UNSET, 1 = OK, 2 = ERROR.
  * @param {{ code?: number, message?: string }} [status]
- * @returns {void}
+ * @returns {number} The new status code to track on the caller.
  */
-function setStatus (ddSpan, bridgeSpan, { code, message } = {}) {
-  if (bridgeSpan.ended || bridgeSpan._hasStatus || !code) return
+function applyOtelStatus (ddSpan, currentCode, status) {
+  if (!isWritable(ddSpan)) return currentCode
 
-  bridgeSpan._hasStatus = true
+  const code = status?.code
+  if (!code || currentCode === 1) return currentCode
 
   if (code === 2) {
     ddSpan.addTags({
-      [ERROR_MESSAGE]: message,
+      [ERROR_MESSAGE]: status.message,
       [IGNORE_OTEL_ERROR]: false,
     })
   }
+
+  return code
+}
+
+/**
+ * OTel `updateName` for OTel-created bridge spans: writes the DD operation name, matching
+ * the OTel SDK semantic that `updateName` updates the canonical span identifier.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} name
+ */
+function setOtelOperationName (ddSpan, name) {
+  if (!isWritable(ddSpan)) return
+
+  ddSpan.setOperationName(name)
+}
+
+/**
+ * OTel `updateName` for DD-native spans the bridge did not create: writes `resource.name`
+ * so the operation name (and the backend metric aggregation it drives) stays stable.
+ *
+ * @param {import('../opentracing/span')} ddSpan
+ * @param {string} name
+ */
+function setOtelResource (ddSpan, name) {
+  if (!isWritable(ddSpan)) return
+
+  ddSpan.setTag('resource.name', name)
 }
 
 module.exports = {
+  addOtelEvent,
   addOtelLink,
+  addOtelLinks,
+  applyOtelStatus,
   normalizeLinkContext,
   recordException,
   setOtelAttribute,
   setOtelAttributes,
-  setStatus,
+  setOtelOperationName,
+  setOtelResource,
 }

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

@@ -13,33 +13,9 @@ const { SERVICE_NAME, RESOURCE_NAME, SPAN_KIND } = require('../../../../ext/tags
 const kinds = require('../../../../ext/kinds')
 
 const id = require('../id')
+const BridgeSpanBase = require('./bridge-span-base')
 const SpanContext = require('./span_context')
-const {
-  addOtelLink,
-  recordException,
-  setOtelAttribute,
-  setOtelAttributes,
-  setStatus,
-} = require('./span-helpers')
-
-// The one built into OTel rounds so we lose sub-millisecond precision.
-function hrTimeToMilliseconds (time) {
-  return time[0] * 1e3 + time[1] / 1e6
-}
-
-function isTimeInput (startTime) {
-  if (typeof startTime === 'number') {
-    return true
-  }
-  if (startTime instanceof Date) {
-    return true
-  }
-  if (Array.isArray(startTime) && startTime.length === 2 &&
-      typeof startTime[0] === 'number' && typeof startTime[1] === 'number') {
-    return true
-  }
-  return false
-}
+const { setOtelOperationName } = require('./span-helpers')
 
 const spanKindNames = {
   [api.SpanKind.INTERNAL]: kinds.INTERNAL,
@@ -49,6 +25,15 @@ const spanKindNames = {
   [api.SpanKind.CONSUMER]: kinds.CONSUMER,
 }
 
+/**
+ * The OTel-shipped `hrTimeToMilliseconds` rounds, dropping sub-millisecond precision we want.
+ *
+ * @param {[number, number]} hrTime
+ */
+function hrTimeToMilliseconds (hrTime) {
+  return hrTime[0] * 1e3 + hrTime[1] / 1e6
+}
+
 /**
  * Several of these attributes are not yet supported by the Node.js OTel API.
  * We check for old equivalents where we can, but not all had equivalents.
@@ -128,7 +113,21 @@ function spanNameMapper (spanName, kind, attributes) {
   return spanKindNames[kind]
 }
 
-class Span {
+/**
+ * OTel-bridge span backed by a `DatadogSpan`. `Tracer` constructs these on the OTel API
+ * surface; the underlying DD span carries the lifecycle.
+ */
+class Span extends BridgeSpanBase {
+  /**
+   * @param {import('./tracer')} parentTracer
+   * @param {import('@opentelemetry/api').Context} context
+   * @param {string | undefined} spanName
+   * @param {import('./span_context')} spanContext
+   * @param {import('@opentelemetry/api').SpanKind} kind
+   * @param {Array<import('@opentelemetry/api').Link>} [links]
+   * @param {import('@opentelemetry/api').TimeInput} [timeInput]
+   * @param {import('@opentelemetry/api').Attributes} [attributes]
+   */
   constructor (
     parentTracer,
     context,
@@ -144,7 +143,7 @@ class Span {
     const hrStartTime = timeInputToHrTime(timeInput || (performance.now() + timeOrigin))
     const startTime = hrTimeToMilliseconds(hrStartTime)
 
-    this._ddSpan = new DatadogSpan(_tracer, _tracer._processor, _tracer._prioritySampler, {
+    const ddSpan = new DatadogSpan(_tracer, _tracer._processor, _tracer._prioritySampler, {
       operationName: spanNameMapper(spanName, kind, attributes),
       context: spanContext._ddContext,
       startTime,
@@ -158,6 +157,8 @@ class Span {
       links,
     }, _tracer._debug)
 
+    super(ddSpan)
+
     if (attributes) {
       this.setAttributes(attributes)
     }
@@ -165,8 +166,6 @@ class Span {
     this._parentTracer = parentTracer
     this._context = context
 
-    this._hasStatus = false
-
     // NOTE: Need to grab the value before setting it on the span because the
     // math for computing opentracing timestamps is apparently lossy...
     this.startTime = hrStartTime
@@ -200,27 +199,13 @@ class Span {
     return new SpanContext(this._ddSpan.context())
   }
 
-  setAttribute (key, value) {
-    setOtelAttribute(this._ddSpan, key, value)
-    return this
-  }
-
-  setAttributes (attributes) {
-    setOtelAttributes(this._ddSpan, attributes)
-    return this
-  }
-
-  addLink (link, attrs) {
-    addOtelLink(this._ddSpan, link, attrs)
-    return this
-  }
-
-  addLinks (links) {
-    for (const link of links) this.addLink(link)
-    return this
-  }
-
+  /**
+   * @param {string} ptrKind
+   * @param {string} ptrDir
+   * @param {string} ptrHash
+   */
   addSpanPointer (ptrKind, ptrDir, ptrHash) {
+    if (this.ended) return this
     const zeroContext = new SpanContext({
       traceId: id('0'),
       spanId: id('0'),
@@ -234,18 +219,17 @@ class Span {
     return this.addLink(zeroContext, attributes)
   }
 
-  setStatus (status) {
-    setStatus(this._ddSpan, this, status)
-    return this
-  }
-
+  /**
+   * @param {string} name
+   */
   updateName (name) {
-    if (!this.ended) {
-      this._ddSpan.setOperationName(name)
-    }
+    setOtelOperationName(this._ddSpan, name)
     return this
   }
 
+  /**
+   * @param {import('@opentelemetry/api').TimeInput} [timeInput]
+   */
   end (timeInput) {
     if (this.ended) {
       api.diag.error('You can only call end() on a span once.')
@@ -259,31 +243,9 @@ class Span {
     this._spanProcessor.onEnd(this)
   }
 
-  isRecording () {
-    return this.ended === false
-  }
-
-  addEvent (name, attributesOrStartTime, startTime) {
-    startTime = attributesOrStartTime && isTimeInput(attributesOrStartTime) ? attributesOrStartTime : startTime
-    const hrStartTime = timeInputToHrTime(startTime || (performance.now() + timeOrigin))
-    startTime = hrTimeToMilliseconds(hrStartTime)
-
-    this._ddSpan.addEvent(name, attributesOrStartTime, startTime)
-    return this
-  }
-
-  recordException (exception, timeInput) {
-    // Route through `this.addEvent` so its time-input conversion applies.
-    recordException(this._ddSpan, this, exception, timeInput)
-  }
-
   get duration () {
     return this._ddSpan._duration
   }
-
-  get ended () {
-    return this.duration !== undefined
-  }
 }
 
 module.exports = Span