dd-trace 5.68.0 → 5.69.0

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

@@ -3,14 +3,25 @@
 const limiter = require('limiter')
 
 class RateLimiter {
+  /**
+   * @param {number} rateLimit - Allowed units per interval. Negative means unlimited, 0 disables.
+   * @param {'second'|'minute'|'hour'|'day'} [interval='second'] - Time window for the limiter.
+   */
   constructor (rateLimit, interval = 'second') {
-    this._rateLimit = Number.parseInt(rateLimit)
+    this._rateLimit = Number.parseInt(String(rateLimit))
+    // The limiter constructor accepts a token count number and an interval string
     this._limiter = new limiter.RateLimiter(this._rateLimit, interval)
     this._tokensRequested = 0
     this._prevIntervalTokens = 0
     this._prevTokensRequested = 0
   }
 
+  /**
+   * Attempts to consume a token and reports whether it was allowed.
+   * Updates internal counters used for effective rate computation.
+   *
+   * @returns {boolean}
+   */
   isAllowed () {
     const curIntervalStart = this._limiter.curIntervalStart
     const curIntervalTokens = this._limiter.tokensThisInterval
@@ -27,6 +38,12 @@ class RateLimiter {
     return allowed
   }
 
+  /**
+   * Returns the fraction of allowed requests over requested ones in the
+   * current and previous intervals combined.
+   *
+   * @returns {number}
+   */
   effectiveRate () {
     if (this._rateLimit < 0) return 1
     if (this._rateLimit === 0) return 0
@@ -38,6 +55,10 @@ class RateLimiter {
     return allowed / requested
   }
 
+  /**
+   * Internal token consumption without counter side-effects.
+   * @returns {boolean}
+   */
   _isAllowed () {
     if (this._rateLimit < 0) return true
     if (this._rateLimit === 0) return false
@@ -45,6 +66,10 @@ class RateLimiter {
     return this._limiter.tryRemoveTokens(1)
   }
 
+  /**
+   * Effective rate within the current interval only.
+   * @returns {number}
+   */
   _currentWindowRate () {
     if (this._rateLimit < 0) return 1
     if (this._rateLimit === 0) return 0

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

@@ -4,18 +4,53 @@ const { globMatch } = require('../src/util')
 const RateLimiter = require('./rate_limiter')
 const Sampler = require('./sampler')
 
+/**
+ * Typedefs for clarity when matching spans.
+ *
+ * @typedef {import('./opentracing/span')} DatadogSpan
+ * @typedef {import('./opentracing/span_context')} DatadogSpanContext
+ *
+ * @callback Locator
+ * A function that derives a string subject from a span.
+ * @param {DatadogSpan} span
+ * @returns {string|undefined}
+ *
+ * @typedef {object} RuleMatcher
+ * @property {(span: DatadogSpan) => boolean} match - Returns true if the span matches.
+ */
+
+/**
+ * Matcher that always returns true.
+ * Implements the minimal `RuleMatcher` interface.
+ * @implements {RuleMatcher}
+ */
 class AlwaysMatcher {
-  match () {
+  /**
+   * @param {DatadogSpan} span
+   * @returns {boolean}
+   */
+  match (span) {
     return true
   }
 }
 
+/**
+ * Matcher that evaluates a glob pattern against a derived subject.
+ */
 class GlobMatcher {
+  /**
+   * @param {string} pattern - Glob pattern used to match the subject.
+   * @param {Locator} locator - Function extracting the subject to match.
+   */
   constructor (pattern, locator) {
     this.pattern = pattern
     this.locator = locator
   }
 
+  /**
+   * @param {DatadogSpan} span
+   * @returns {boolean}
+   */
   match (span) {
     const subject = this.locator(span)
     if (!subject) return false
@@ -23,12 +58,23 @@ class GlobMatcher {
   }
 }
 
+/**
+ * Matcher that evaluates a regular expression against a derived subject.
+ */
 class RegExpMatcher {
+  /**
+   * @param {RegExp} pattern - Regular expression used to test the subject.
+   * @param {Locator} locator - Function extracting the subject to test.
+   */
   constructor (pattern, locator) {
     this.pattern = pattern
     this.locator = locator
   }
 
+  /**
+   * @param {DatadogSpan} span
+   * @returns {boolean}
+   */
   match (span) {
     const subject = this.locator(span)
     if (!subject) return false
@@ -36,6 +82,15 @@ class RegExpMatcher {
   }
 }
 
+/**
+ * Creates a matcher for the provided pattern and locator.
+ * Returns a glob matcher for non-trivial strings, a regexp matcher for RegExp,
+ * or an always-true matcher for wildcard or missing patterns.
+ *
+ * @param {string|RegExp|undefined} pattern
+ * @param {Locator} locator
+ * @returns {RuleMatcher}
+ */
 function matcher (pattern, locator) {
   if (pattern instanceof RegExp) {
     return new RegExpMatcher(pattern, locator)
@@ -47,14 +102,32 @@ function matcher (pattern, locator) {
   return new AlwaysMatcher()
 }
 
+/**
+ * Creates a locator that reads a specific tag from the span context.
+ *
+ * @param {string} tag
+ * @returns {Locator}
+ */
 function makeTagLocator (tag) {
   return (span) => span.context()._tags[tag]
 }
 
+/**
+ * Extracts the operation name from the span context.
+ *
+ * @param {DatadogSpan} span
+ * @returns {string|undefined}
+ */
 function nameLocator (span) {
   return span.context()._name
 }
 
+/**
+ * Extracts the service name from the span context or tracer configuration.
+ *
+ * @param {DatadogSpan} span
+ * @returns {string|undefined}
+ */
 function serviceLocator (span) {
   const { _tags: tags } = span.context()
   return tags.service ||
@@ -62,13 +135,39 @@ function serviceLocator (span) {
     span.tracer()._service
 }
 
+/**
+ * Extracts the resource name from the span context.
+ *
+ * @param {DatadogSpan} span
+ * @returns {string|undefined}
+ */
 function resourceLocator (span) {
   const { _tags: tags } = span.context()
   return tags.resource ||
     tags['resource.name']
 }
 
+/**
+ * Configuration options for a sampling rule.
+ *
+ * @typedef {object} SamplingRuleConfig
+ * @property {string|RegExp} [name] - Match on span operation name.
+ * @property {string|RegExp} [service] - Match on service name.
+ * @property {string|RegExp} [resource] - Match on resource name.
+ * @property {Record<string, string|RegExp>} [tags] - Match on specific tag values by key.
+ * @property {number} [sampleRate=1] - Deterministic sampling rate in [0, 1].
+ * @property {string} [provenance] - Optional provenance/metadata for this rule.
+ * @property {number} [maxPerSecond] - Maximum samples per second (rate limit).
+ */
+
+/**
+ * SamplingRule encapsulates matching criteria and sampling/limiting behavior
+ * to decide whether a span should be sampled.
+ */
 class SamplingRule {
+  /**
+   * @param {SamplingRuleConfig} [config]
+   */
   constructor ({ name, service, resource, tags, sampleRate = 1, provenance, maxPerSecond } = {}) {
     this.matchers = []
 
@@ -94,22 +193,45 @@ class SamplingRule {
     }
   }
 
+  /**
+   * Constructs a SamplingRule from the given configuration.
+   * @param {SamplingRuleConfig} config
+   * @returns {SamplingRule}
+   */
   static from (config) {
     return new SamplingRule(config)
   }
 
+  /**
+   * Deterministic sampling rate in [0, 1].
+   * @returns {number}
+   */
   get sampleRate () {
     return this._sampler.rate()
   }
 
+  /**
+   * Effective rate applied by the rate limiter, if configured.
+   * @returns {number|undefined}
+   */
   get effectiveRate () {
     return this._limiter && this._limiter.effectiveRate()
   }
 
+  /**
+   * Maximum samples per second if a limiter is present.
+   * @returns {number|undefined}
+   */
   get maxPerSecond () {
     return this._limiter && this._limiter._rateLimit
   }
 
+  /**
+   * Checks whether the provided span matches all configured criteria.
+   *
+   * @param {DatadogSpan} span
+   * @returns {boolean}
+   */
   match (span) {
     for (const matcher of this.matchers) {
       // Rule is a special object with a .match() property.
@@ -126,7 +248,7 @@ class SamplingRule {
   /**
    * Determines whether a span should be sampled based on the configured sampling rule.
    *
-   * @param {Span|SpanContext} span - The span or span context to evaluate.
+   * @param {DatadogSpan|DatadogSpanContext} span - The span or span context to evaluate.
    * @returns {boolean} `true` if the span should be sampled, otherwise `false`.
    */
   sample (span) {

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

@@ -3,11 +3,23 @@
 const { USER_KEEP, AUTO_KEEP } = require('../../../ext').priority
 const SamplingRule = require('./sampling_rule')
 
+/**
+ * Samples individual spans within a trace using span-level rules.
+ */
 class SpanSampler {
+  /**
+   * @param {{ spanSamplingRules?: Array<import('./sampling_rule')>|Array<Record<string, unknown>> }} [config]
+   */
   constructor ({ spanSamplingRules = [] } = {}) {
     this._rules = spanSamplingRules.map(SamplingRule.from)
   }
 
+  /**
+   * Finds the first matching span sampling rule for the given span.
+   *
+   * @param {import('./opentracing/span')} context
+   * @returns {import('./sampling_rule')|undefined}
+   */
   findRule (context) {
     for (const rule of this._rules) {
       // Rule is a special object with a .match() property.
@@ -19,6 +31,13 @@ class SpanSampler {
     }
   }
 
+  /**
+   * Applies span sampling to spans in the trace, tagging matching spans with
+   * span sampling metadata when appropriate.
+   *
+   * @param {import('./opentracing/span_context')} spanContext
+   * @returns {void}
+   */
   sample (spanContext) {
     const decision = spanContext._sampling.priority
     if (decision === USER_KEEP || decision === AUTO_KEEP) return

package/packages/dd-trace/src/standalone/product.js

@@ -3,6 +3,12 @@
 const { SAMPLING_MECHANISM_APPSEC } = require('../constants')
 const RateLimiter = require('../rate_limiter')
 
+/**
+ * Returns a rate limiter tuned for the provided product configuration.
+ *
+ * @param {{ appsec?: { enabled?: boolean }, iast?: { enabled?: boolean } } | undefined} config
+ * @returns {import('../rate_limiter')}
+ */
 function getProductRateLimiter (config) {
   if (config?.appsec?.enabled || config?.iast?.enabled) {
     return new RateLimiter(1, 'minute') // onePerMinute
@@ -11,6 +17,9 @@ function getProductRateLimiter (config) {
   return new RateLimiter(0) // dropAll
 }
 
+/**
+ * Available products and their identifiers/mechanisms.
+ */
 const PRODUCTS = {
   APM: { id: 1 << 0 },
   ASM: { id: 1 << 1, mechanism: SAMPLING_MECHANISM_APPSEC },

package/packages/dd-trace/src/standalone/tracesource.js

@@ -2,15 +2,30 @@
 
 const { TRACE_SOURCE_PROPAGATION_KEY } = require('../constants')
 
+/**
+ * Adds or updates the trace source propagation tag with the given product bit.
+ *
+ * @param {Record<string, unknown>|undefined} tags
+ * @param {{ id: number }|undefined} product
+ * @returns {Record<string, unknown>|undefined}
+ */
 function addTraceSourceTag (tags, product) {
   if (tags && product) {
-    const actual = tags[TRACE_SOURCE_PROPAGATION_KEY] ? Number.parseInt(tags[TRACE_SOURCE_PROPAGATION_KEY], 16) : 0
+    const actual = tags[TRACE_SOURCE_PROPAGATION_KEY]
+      ? Number.parseInt(String(tags[TRACE_SOURCE_PROPAGATION_KEY]), 16)
+      : 0
     tags[TRACE_SOURCE_PROPAGATION_KEY] = ((actual | product.id) >>> 0).toString(16).padStart(2, '0')
   }
 
   return tags
 }
 
+/**
+ * Returns true when the trace source propagation tag exists on the given tags object.
+ *
+ * @param {Record<string, unknown>} tags
+ * @returns {boolean}
+ */
 function hasTraceSourcePropagationTag (tags) {
   return Object.hasOwn(tags, TRACE_SOURCE_PROPAGATION_KEY)
 }

package/packages/dd-trace/src/standalone/tracesource_priority_sampler.js

@@ -8,12 +8,19 @@ const { addTraceSourceTag, hasTraceSourcePropagationTag } = require('./tracesour
 const { getProductRateLimiter } = require('./product')
 
 class TraceSourcePrioritySampler extends PrioritySampler {
+  /**
+   * @override
+   */
   configure (env, sampler, config) {
     // rules not supported
     this._env = env
     this._limiter = getProductRateLimiter(config)
   }
 
+  /**
+   * @override
+   * @returns {import('../priority_sampler').SamplingPriority|undefined}
+   */
   _getPriorityFromTags (tags, context) {
     if (Object.hasOwn(tags, MANUAL_KEEP) &&
       tags[MANUAL_KEEP] !== false &&
@@ -23,6 +30,9 @@ class TraceSourcePrioritySampler extends PrioritySampler {
     }
   }
 
+  /**
+   * @override
+   */
   _getPriorityFromAuto (span) {
     const context = this._getContext(span)
 
@@ -35,6 +45,9 @@ class TraceSourcePrioritySampler extends PrioritySampler {
     return this._isSampledByRateLimit(context) ? AUTO_KEEP : AUTO_REJECT
   }
 
+  /**
+   * @override
+   */
   setPriority (span, samplingPriority, product) {
     super.setPriority(span, samplingPriority, product)
 

package/packages/dd-trace/src/startup-log.js

@@ -13,12 +13,18 @@ let pluginManager
 let samplingRules = []
 let alreadyRan = false
 
+/**
+ * @returns {Record<string, unknown>}
+ */
 function getIntegrationsAndAnalytics () {
   return {
     integrations_loaded: Object.keys(pluginManager._pluginsByName)
   }
 }
 
+/**
+ * @param {{ agentError: { code: string, message: string } }} [options]
+ */
 function startupLog ({ agentError } = {}) {
   if (!config || !pluginManager) {
     return
@@ -34,7 +40,7 @@ function startupLog ({ agentError } = {}) {
     return
   }
 
-  const out = tracerInfo({ agentError })
+  const out = tracerInfo()
 
   if (agentError) {
     out.agent_error = agentError.message
@@ -50,6 +56,9 @@ function startupLog ({ agentError } = {}) {
   }
 }
 
+/**
+ * @returns {Record<string, unknown>}
+ */
 function tracerInfo () {
   const url = config.url || `http://${config.hostname || defaults.hostname}:${config.port}`
 
@@ -94,14 +103,23 @@ function tracerInfo () {
   return out
 }
 
+/**
+ * @param {import('./config')} aConfig
+ */
 function setStartupLogConfig (aConfig) {
   config = aConfig
 }
 
+/**
+ * @param {import('./plugin_manager')} thePluginManager
+ */
 function setStartupLogPluginManager (thePluginManager) {
   pluginManager = thePluginManager
 }
 
+/**
+ * @param {import('./sampling_rule')} theRules
+ */
 function setSamplingRules (theRules) {
   samplingRules = theRules
 }

package/packages/dd-trace/src/supported-configurations.json

@@ -5,6 +5,11 @@
     "DD_AGENT_HOST": ["A"],
     "DD_AGENTLESS_LOG_SUBMISSION_ENABLED": ["A"],
     "DD_AGENTLESS_LOG_SUBMISSION_URL": ["A"],
+    "DD_AI_GUARD_ENABLED": ["A"],
+    "DD_AI_GUARD_ENDPOINT": ["A"],
+    "DD_AI_GUARD_MAX_CONTENT_SIZE": ["A"],
+    "DD_AI_GUARD_MAX_MESSAGES_LENGTH": ["A"],
+    "DD_AI_GUARD_TIMEOUT": ["A"],
     "DD_API_KEY": ["A"],
     "DD_API_SECURITY_ENABLED": ["A"],
     "DD_API_SECURITY_SAMPLE_DELAY": ["A"],
@@ -12,6 +17,7 @@
     "DD_API_SECURITY_ENDPOINT_COLLECTION_MESSAGE_LIMIT": ["A"],
     "DD_APM_FLUSH_DEADLINE_MILLISECONDS": ["A"],
     "DD_APM_TRACING_ENABLED": ["A"],
+    "DD_APP_KEY": ["A"],
     "DD_APPSEC_AUTO_USER_INSTRUMENTATION_MODE": ["A"],
     "DD_APPSEC_COLLECT_ALL_HEADERS": ["A"],
     "DD_APPSEC_ENABLED": ["A"],

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

@@ -88,7 +88,7 @@ module.exports = {
   isFalse,
   isError,
   globMatch,
-  ddBasePath: calculateDDBasePath(__dirname),
+  ddBasePath: globalThis.__DD_ESBUILD_BASEPATH || calculateDDBasePath(__dirname),
   normalizeProfilingEnabledValue,
   normalizePluginEnvName
 }

package/version.js

@@ -1,8 +1,10 @@
 'use strict'
 
 var version = require('./package.json').version
-var ddMatches = version.match(/^(\d+)\.(\d+)\.(\d+)/)
-var nodeMatches = process.versions.node.match(/^(\d+)\.(\d+)\.(\d+)/)
+// @ts-expect-error
+var /** @type {RegExpMatchArray} */ ddMatches = version.match(/^(\d+)\.(\d+)\.(\d+)/)
+// @ts-expect-error
+var /** @type {RegExpMatchArray} */ nodeMatches = process.versions.node.match(/^(\d+)\.(\d+)\.(\d+)/)
 
 module.exports = {
   VERSION: version,