dd-trace 5.68.0 → 5.69.0

package/packages/dd-trace/src/payload-tagging/index.js

@@ -14,8 +14,8 @@ const { tagsFromObject } = require('./tagging')
 /**
  * Given an identified value, attempt to parse it as JSON if relevant
  *
- * @param {any} value
- * @returns {any} the parsed object if parsing was successful, the input if not
+ * @param {unknown} value
+ * @returns {unknown} the parsed object if parsing was successful, the input if not
  */
 function maybeJSONParseValue (value) {
   if (typeof value !== 'string' || value[0] !== '{') {
@@ -32,8 +32,8 @@ function maybeJSONParseValue (value) {
 /**
  * Apply expansion to all expansion JSONPath queries
  *
- * @param {Object} object
- * @param {[String]} expansionRules list of JSONPath queries
+ * @param {Record<string, unknown>} object
+ * @param {string[]} expansionRules list of JSONPath queries
  */
 function expand (object, expansionRules) {
   for (const rule of expansionRules) {
@@ -46,8 +46,8 @@ function expand (object, expansionRules) {
 /**
  * Apply redaction to all redaction JSONPath queries
  *
- * @param {Object} object
- * @param {[String]} redactionRules
+ * @param {Record<string, unknown>} object
+ * @param {string[]} redactionRules
  */
 function redact (object, redactionRules) {
   for (const rule of redactionRules) {
@@ -65,15 +65,10 @@ function redact (object, redactionRules) {
  *    as there are leaf values in the object
  * This function performs side-effects on a _copy_ of the input object.
  *
- * @param {Object} config sdk configuration for the service
- * @param {[String]} config.expand expansion rules for the service
- * @param {[String]} config.request redaction rules for the request
- * @param {[String]} config.response redaction rules for the response
- * @param {Object} object the input object to generate tags from
- * @param {Object} opts tag generation options
- * @param {String} opts.prefix prefix for all generated tags
- * @param {number} opts.maxDepth maximum depth to traverse the object
- * @returns
+ * @param {{ expand: string[], request: string[], response: string[] }} config sdk configuration for the service
+ * @param {Record<string, unknown>} object the input object to generate tags from
+ * @param {{ prefix: string, maxDepth: number }} opts tag generation options
+ * @returns {Record<string, string|boolean>} Tags map
  */
 function computeTags (config, object, opts) {
   const payload = rfdc(object)
@@ -84,10 +79,26 @@ function computeTags (config, object, opts) {
   return tagsFromObject(payload, opts)
 }
 
+/**
+ * Compute request tags with the request prefix.
+ *
+ * @param {{ expand: string[], request: string[], response: string[] }} config
+ * @param {Record<string, unknown>} object
+ * @param {{ maxDepth: number }} opts
+ * @returns {Record<string, string|boolean>}
+ */
 function tagsFromRequest (config, object, opts) {
   return computeTags(config, object, { ...opts, prefix: PAYLOAD_TAG_REQUEST_PREFIX })
 }
 
+/**
+ * Compute response tags with the response prefix.
+ *
+ * @param {{ expand: string[], request: string[], response: string[] }} config
+ * @param {Record<string, unknown>} object
+ * @param {{ maxDepth: number }} opts
+ * @returns {Record<string, string|boolean>}
+ */
 function tagsFromResponse (config, object, opts) {
   return computeTags(config, object, { ...opts, prefix: PAYLOAD_TAG_RESPONSE_PREFIX })
 }

package/packages/dd-trace/src/payload-tagging/tagging.js

@@ -8,24 +8,33 @@ const redactedKeys = new Set([
 const truncated = 'truncated'
 const redacted = 'redacted'
 
+/**
+ * Escapes dots in keys to preserve hierarchy in flattened tag names.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
 function escapeKey (key) {
   return key.replaceAll('.', String.raw`\.`)
 }
 
 /**
-   * Compute normalized payload tags from any given object.
-   *
-   * @param {object} object
-   * @param {import('./mask').Mask} mask
-   * @param {number} maxDepth
-   * @param {string} prefix
-   * @returns
-   */
+ * Compute normalized payload tags from any given object.
+ *
+ * - Limits total tag count to `PAYLOAD_TAGGING_MAX_TAGS - 1` plus the `_dd.payload_tags_incomplete` flag
+ * - Truncates values at max depth and for large scalars
+ * - Redacts known sensitive keys
+ *
+ * @param {unknown} object - Input to flatten into tags
+ * @param {{ maxDepth: number, prefix: string }} opts - Traversal options
+ * @returns {Record<string, string|boolean>} Map of tag names to values
+ */
 function tagsFromObject (object, opts) {
   const { maxDepth, prefix } = opts
 
   let tagCount = 0
   let abort = false
+  /** @type {Record<string, string|boolean>} */
   const result = {}
 
   function tagRec (prefix, object, depth = 0) {

package/packages/dd-trace/src/pkg.js

@@ -20,8 +20,10 @@ function findPkg () {
 
   const filePath = findUp('package.json', root, directory)
 
+  if (filePath === undefined) return {}
+
   try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+    return require(filePath)
   } catch {
     return {}
   }

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

@@ -11,6 +11,9 @@ class CompositePlugin extends Plugin {
     }
   }
 
+  /**
+   * @override
+   */
   configure (config) {
     super.configure(config)
     for (const name in this.constructor.plugins) {

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

@@ -6,6 +6,24 @@ const dc = require('dc-polyfill')
 const logger = require('../log')
 const { storage } = require('../../../datadog-core')
 
+/**
+ * Base class for all Datadog plugins.
+ *
+ * Subclasses MUST define a static field `id` with the integration identifier
+ * used across channels, span names, tags and telemetry.
+ *
+ * Example:
+ * ```js
+ * class MyPlugin extends Plugin {
+ *   static id = 'myframework'
+ * }
+ * ```
+ *
+ * Notes about the tracer instance:
+ * - In some contexts the tracer may be wrapped and available as `{ _tracer: Tracer }`.
+ *   Use the `tracer` getter which normalizes access.
+ */
+
 class Subscription {
   constructor (event, handler) {
     this._channel = dc.channel(event)
@@ -50,6 +68,12 @@ class StoreBinding {
 }
 
 module.exports = class Plugin {
+  /**
+   * Create a new plugin instance.
+   *
+   * @param {object} tracer Tracer instance or wrapper containing it under `_tracer`.
+   * @param {object} tracerConfig Global tracer configuration object.
+   */
   constructor (tracer, tracerConfig) {
     this._subscriptions = []
     this._bindings = []
@@ -59,10 +83,22 @@ module.exports = class Plugin {
     this._tracerConfig = tracerConfig // global tracer configuration
   }
 
+  /**
+   * Normalized tracer access. Returns the underlying tracer even if wrapped.
+   *
+   * @returns {object}
+   */
   get tracer () {
     return this._tracer?._tracer || this._tracer
   }
 
+  /**
+   * Enter a context with the provided span bound in storage.
+   *
+   * @param {object} span The span to bind as current.
+   * @param {object=} store Optional existing store to extend; if omitted, uses current store.
+   * @returns {void}
+   */
   enter (span, store) {
     store = store || storage('legacy').getStore()
     storage('legacy').enterWith({ ...store, span })
@@ -74,8 +110,19 @@ module.exports = class Plugin {
     storage('legacy').enterWith({ noop: true })
   }
 
+  /**
+   * 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.
+   * @returns {void}
+   */
   addSub (channelName, handler) {
     const plugin = this
+    /**
+     * @this {unknown}
+     * @returns {unknown}
+     */
     const wrappedHandler = function () {
       try {
         return handler.apply(this, arguments)
@@ -88,10 +135,23 @@ module.exports = class Plugin {
     this._subscriptions.push(new Subscription(channelName, wrappedHandler))
   }
 
+  /**
+   * Bind the tracer store to a diagnostic channel with a transform function.
+   *
+   * @param {string} channelName Diagnostic channel name.
+   * @param {(data: unknown) => object} transform Transform to compute the bound store.
+   * @returns {void}
+   */
   addBind (channelName, transform) {
     this._bindings.push(new StoreBinding(channelName, transform))
   }
 
+  /**
+   * Attach an error to the current active span (if any).
+   *
+   * @param {unknown} error Error object or sentinel value.
+   * @returns {void}
+   */
   addError (error) {
     const store = storage('legacy').getStore()
 
@@ -102,6 +162,13 @@ module.exports = class Plugin {
     }
   }
 
+  /**
+   * Enable or disable the plugin and (re)apply its configuration.
+   *
+   * @param {boolean|object} config Either a boolean to enable/disable or a configuration object
+   *                                containing at least `{ enabled: boolean }`.
+   * @returns {void}
+   */
   configure (config) {
     if (typeof config === 'boolean') {
       config = { enabled: config }

package/packages/dd-trace/src/plugins/util/git.js

@@ -116,7 +116,7 @@ function isShallowRepository () {
 
 function getGitVersion () {
   const gitVersionString = sanitizedExec('git', ['version'])
-  const gitVersionMatches = gitVersionString.match(/git version (\d+)\.(\d+)\.(\d+)/)
+  const gitVersionMatches = /** @type {RegExpMatchArray} */ (gitVersionString.match(/git version (\d+)\.(\d+)\.(\d+)/))
   try {
     return {
       major: Number.parseInt(gitVersionMatches[1]),

package/packages/dd-trace/src/plugins/util/test.js

@@ -49,6 +49,13 @@ const { SAMPLING_RULE_DECISION } = require('../../constants')
 const { AUTO_KEEP } = require('../../../../../ext/priority')
 const { version: ddTraceVersion } = require('../../../../../package.json')
 
+/**
+ * JSDoc types for test environment metadata helpers.
+ *
+ * @typedef {{ service?: string, isServiceUserProvided?: boolean }} TestEnvironmentConfig
+ * @typedef {Record<string, string|number|undefined>} TestEnvironmentMetadata
+ */
+
 // session tags
 const TEST_SESSION_NAME = 'test_session.name'
 
@@ -331,6 +338,10 @@ function validateUrl (url) {
   }
 }
 
+/**
+ * @param {TestEnvironmentMetadata} metadata
+ * @returns {TestEnvironmentMetadata}
+ */
 function removeInvalidMetadata (metadata) {
   return Object.keys(metadata).reduce((filteredTags, tag) => {
     if (tag === GIT_REPOSITORY_URL && !validateGitRepositoryUrl(metadata[GIT_REPOSITORY_URL])) {
@@ -444,6 +455,13 @@ function checkShaDiscrepancies (ciMetadata, userProvidedGitMetadata) {
   )
 }
 
+/**
+ * Build environment metadata for tests by merging CI, Git, runtime/OS and user-provided metadata.
+ *
+ * @param {string=} testFramework
+ * @param {TestEnvironmentConfig=} config
+ * @returns {TestEnvironmentMetadata}
+ */
 function getTestEnvironmentMetadata (testFramework, config, shouldSkipGitMetadataExtraction = false) {
   const ciMetadata = getCIMetadata()
   const userProvidedGitMetadata = getUserProviderGitMetadata()
@@ -479,6 +497,7 @@ function getTestEnvironmentMetadata (testFramework, config, shouldSkipGitMetadat
     })
   }
 
+  /** @type {TestEnvironmentMetadata} */
   const runtimeAndOSMetadata = getRuntimeAndOSMetadata()
 
   const metadata = {

package/packages/dd-trace/src/priority_sampler.js

@@ -46,8 +46,9 @@ const defaultSampler = new Sampler(AUTO_KEEP)
  * @class PrioritySampler
  * @typedef {import('./opentracing/span')} DatadogSpan
  * @typedef {import('./opentracing/span_context')} DatadogSpanContext
- * @typedef {import('./standalone/product')} PRODUCTS
+ * @typedef {{ id: number, mechanism?: number }} Product
  * @typedef {2|-1|1|0} SamplingPriority Empirically defined sampling priorities.
+ * @typedef {import('./sampling_rule')|Record<string, unknown>} SamplingRuleLike
  */
 class PrioritySampler {
   /**
@@ -55,12 +56,12 @@ class PrioritySampler {
    *
    * @typedef {Object} SamplingConfig
    * @property {number} [sampleRate] - The default sample rate for traces.
-   * @property {string} [provenance] - The provenance of the sampling rule (e.g., "customer", "dynamic").
+   * @property {string} [provenance] - Optional rule provenance ("customer" or "dynamic").
    * @property {number} [rateLimit=100] - The maximum number of traces to sample per second.
-   * @property {Array<SamplingRule>} [rules=[]] - An array of sampling rules to apply.
+   * @property {Array<import('./sampling_rule')>|Array<Record<string, unknown>>} [rules=[]] - Sampling rules or configs.
    *
    * @param {string} env - The environment name (e.g., "production", "staging").
-   * @param {SamplingConfig} config - The configuration object for sampling.
+   * @param {SamplingConfig} [config] - The configuration object for sampling.
    */
   constructor (env, config) {
     this.configure(env, config)
@@ -69,22 +70,22 @@ class PrioritySampler {
 
   /**
    *
-   * @param env {string}
-   * @param opts {SamplingConfig}
+   * @param {string} env
+   * @param {SamplingConfig} config
    */
-  configure (env, opts = {}) {
-    const { sampleRate, provenance, rateLimit = 100, rules } = opts
+  configure (env, config = {}) {
+    const { sampleRate, provenance, rateLimit = 100, rules } = config
     this._env = env
     this._rules = this.#normalizeRules(rules || [], sampleRate, rateLimit, provenance)
     this._limiter = new RateLimiter(rateLimit)
 
-    log.trace(env, opts)
+    log.trace(env, config)
     setSamplingRules(this._rules)
   }
 
   /**
-   * @param span {DatadogSpan}
-   * @returns {boolean}
+   * @param {DatadogSpan} span
+   * @returns {boolean} True if the trace should be sampled based on priority.
    */
   isSampled (span) {
     const priority = this._getPriorityFromAuto(span)
@@ -93,9 +94,10 @@ class PrioritySampler {
   }
 
   /**
+   * Assigns a sampling priority to a span if not already set.
    *
-   * @param span {DatadogSpan}
-   * @param auto {boolean}
+   * @param {DatadogSpan} span
+   * @param {boolean} [auto=true] - Whether to use automatic sampling if no manual tags are present.
    * @returns {void}
    */
   sample (span, auto = true) {
@@ -125,8 +127,9 @@ class PrioritySampler {
   }
 
   /**
+   * Updates agent-provided sampling rates keyed by `service:,env:`.
    *
-   * @param rates {Record<string, number>}
+   * @param {Record<string, number>} rates
    * @returns {void}
    */
   update (rates) {
@@ -145,8 +148,9 @@ class PrioritySampler {
   }
 
   /**
+   * Validates that a sampling priority value is one of the allowed constants.
    *
-   * @param samplingPriority {SamplingPriority}
+   * @param {SamplingPriority|undefined} samplingPriority
    * @returns {boolean}
    */
   validate (samplingPriority) {
@@ -162,10 +166,11 @@ class PrioritySampler {
   }
 
   /**
+   * Explicitly sets the priority and mechanism for the span's trace.
    *
-   * @param span {DatadogSpan}
-   * @param samplingPriority {SamplingPriority}
-   * @param product {import('./standalone/product')}
+   * @param {DatadogSpan} span
+   * @param {SamplingPriority} samplingPriority
+   * @param {Product} [product]
    */
   setPriority (span, samplingPriority, product) {
     if (!span || !this.validate(samplingPriority)) return
@@ -189,17 +194,21 @@ class PrioritySampler {
   }
 
   /**
+   * Returns the span context, accepting either a span or a span context.
    *
-   * @param span {DatadogSpan}
+   * @param {DatadogSpan|DatadogSpanContext} span
    * @returns {DatadogSpanContext}
    */
   _getContext (span) {
-    return typeof span.context === 'function' ? span.context() : span
+    return typeof /** @type {DatadogSpan} */ (span).context === 'function'
+      ? /** @type {DatadogSpan} */ (span).context()
+      : /** @type {DatadogSpanContext} */ (span)
   }
 
   /**
+   * Computes priority using rules and agent rates when no manual tag is present.
    *
-   * @param span {DatadogSpan}
+   * @param {DatadogSpan} span
    * @returns {SamplingPriority}
    */
   _getPriorityFromAuto (span) {
@@ -212,11 +221,12 @@ class PrioritySampler {
   }
 
   /**
-   *
-   * @param tags {Record<string, symbol | unknown>}
+   * Computes priority from manual sampling tags if present.
    * Included for compatibility with {@link import('./standalone/tracesource_priority_sampler')._getPriorityFromTags}
-   * @param _context {DatadogSpanContext}
-   * @returns {SamplingPriority}
+   *
+   * @param {Record<string, unknown>} tags
+   * @param {DatadogSpanContext} _context
+   * @returns {SamplingPriority|undefined}
    */
   _getPriorityFromTags (tags, _context) {
     if (Object.hasOwn(tags, MANUAL_KEEP) && tags[MANUAL_KEEP] !== false) {
@@ -224,19 +234,23 @@ class PrioritySampler {
     } else if (Object.hasOwn(tags, MANUAL_DROP) && tags[MANUAL_DROP] !== false) {
       return USER_REJECT
     }
-    const priority = Number.parseInt(tags[SAMPLING_PRIORITY], 10)
-
-    if (priority === 1 || priority === 2) {
-      return USER_KEEP
-    } else if (priority === 0 || priority === -1) {
-      return USER_REJECT
+    const rawPriority = tags[SAMPLING_PRIORITY]
+    if (rawPriority !== undefined) {
+      const priority = Number.parseInt(String(rawPriority), 10)
+
+      if (priority === 1 || priority === 2) {
+        return USER_KEEP
+      } else if (priority === 0 || priority === -1) {
+        return USER_REJECT
+      }
     }
   }
 
   /**
+   * Applies a matching rule and rate limit to compute the sampling priority.
    *
-   * @param context {DatadogSpanContext}
-   * @param rule {SamplingRule}
+   * @param {DatadogSpanContext} context
+   * @param {import('./sampling_rule')} rule
    * @returns {SamplingPriority}
    */
   #getPriorityByRule (context, rule) {
@@ -251,12 +265,14 @@ class PrioritySampler {
   }
 
   /**
+   * Checks if the rate limiter allows sampling for the current window and
+   * records the effective rate on the trace.
    *
-   * @param context {DatadogSpanContext}
+   * @param {DatadogSpanContext} context
    * @returns {boolean}
-   * @private
    */
   _isSampledByRateLimit (context) {
+    // TODO: Change underscored properties to private ones.
     const allowed = this._limiter.isAllowed()
 
     context._trace[SAMPLING_LIMIT_DECISION] = this._limiter.effectiveRate()
@@ -265,12 +281,14 @@ class PrioritySampler {
   }
 
   /**
+   * Computes priority using agent-provided sampling rates.
    *
-   * @param context {DatadogSpanContext}
+   * @param {DatadogSpanContext} context
    * @returns {SamplingPriority}
    */
   #getPriorityByAgent (context) {
     const key = `service:${context._tags[SERVICE_NAME]},env:${this._env}`
+    // TODO: Change underscored properties to private ones.
     const sampler = this._samplers[key] || this._samplers[DEFAULT_KEY]
 
     context._trace[SAMPLING_AGENT_DECISION] = sampler.rate()
@@ -281,8 +299,9 @@ class PrioritySampler {
   }
 
   /**
+   * Tags the trace with a decision maker when priority is keep, or removes it otherwise.
    *
-   * @param span {DatadogSpan}
+   * @param {DatadogSpan} span
    * @returns {void}
    */
   #addDecisionMaker (span) {
@@ -301,11 +320,13 @@ class PrioritySampler {
   }
 
   /**
-   * @param {Record<string, unknown>[] | Record<string, unknown>} rules - The sampling rules to normalize.
-   * @param {number} sampleRate
+   * Normalizes rule inputs to SamplingRule instances, applying defaults.
+   *
+   * @param {Array<SamplingRuleLike>|SamplingRuleLike} rules - Rules to normalize.
+   * @param {number|undefined} sampleRate
    * @param {number} rateLimit
-   * @param {string} provenance
-   * @returns {SamplingRule[]}
+   * @param {string|undefined} provenance
+   * @returns {Array<import('./sampling_rule')>}
    */
   #normalizeRules (rules, sampleRate, rateLimit, provenance) {
     rules = Array.isArray(rules) ? rules.flat() : [rules]
@@ -314,7 +335,7 @@ class PrioritySampler {
 
     const result = []
     for (const rule of rules) {
-      const sampleRate = Number.parseFloat(rule.sampleRate)
+      const sampleRate = Number.parseFloat(String(rule.sampleRate))
       // TODO(BridgeAR): Debug logging invalid rules fails our tests.
       // Should we definitely not know about these?
       if (!Number.isNaN(sampleRate)) {
@@ -325,11 +346,13 @@ class PrioritySampler {
   }
 
   /**
+   * Finds the first matching rule for the given span.
    *
-   * @param span {DatadogSpan}
-   * @returns {SamplingRule|undefined}
+   * @param {DatadogSpan} span
+   * @returns {import('./sampling_rule')|undefined}
    */
   #findRule (span) {
+    // TODO: Change underscored properties to private ones.
     for (const rule of this._rules) {
       // Rule is a special object with a .match() property.
       // It has nothing to do with a regular expression.
@@ -339,9 +362,10 @@ class PrioritySampler {
   }
 
   /**
+   * Convenience helper to keep a trace with an optional product mechanism.
    *
-   * @param span {DatadogSpan}
-   * @param product {import('./standalone/product')}
+   * @param {DatadogSpan} span
+   * @param {Product} [product]
    */
   static keepTrace (span, product) {
     span?._prioritySampler?.setPriority(span, USER_KEEP, product)

package/packages/dd-trace/src/proxy.js

@@ -88,6 +88,9 @@ class Tracer extends NoopProxy {
     }
   }
 
+  /**
+   * @override
+   */
   init (options) {
     if (this._initialized) return this
 
@@ -241,6 +244,9 @@ class Tracer extends NoopProxy {
         this.dataStreamsCheckpointer = this._tracer.dataStreamsCheckpointer
         lazyProxy(this, 'appsec', config, () => require('./appsec/sdk'), this._tracer, config)
         lazyProxy(this, 'llmobs', config, () => require('./llmobs/sdk'), this._tracer, this._modules.llmobs, config)
+        if (config.experimental?.aiguard?.enabled) {
+          lazyProxy(this, 'aiguard', config, () => require('./aiguard/sdk'), this._tracer, config)
+        }
         this._tracingInitialized = true
       }
       if (config.iast.enabled) {
@@ -261,6 +267,9 @@ class Tracer extends NoopProxy {
     }
   }
 
+  /**
+   * @override
+   */
   profilerStarted () {
     if (!this._profilerStarted) {
       // injection hardening: this is only ever invoked from tests.
@@ -269,11 +278,17 @@ class Tracer extends NoopProxy {
     return this._profilerStarted
   }
 
+  /**
+   * @override
+   */
   use () {
     this._pluginManager.configurePlugin(...arguments)
     return this
   }
 
+  /**
+   * @override
+   */
   get TracerProvider () {
     return require('./opentelemetry/tracer_provider')
   }