dd-trace 6.19.0 → 6.20.0

package/packages/dd-trace/src/debugger/probe_sampler.js

@@ -20,28 +20,62 @@ const ddTraceGlobal = /** @type {Record<symbol, SharedArrayBuffer | object | und
   /** @type {Record<symbol, unknown>} */ (globalThis)[Symbol.for(DD_TRACE_SYMBOL)]
 )
 
+/**
+ * @typedef {object} ProbeThrottle
+ * @property {bigint} untilNs - The probe is skipped at entry until this point in time
+ * @property {boolean} timedOut - Whether the throttle was caused by an evaluation exceeding its time budget
+ * @property {string | undefined} error - A condition error not yet handed over to the worker
+ */
+
+/**
+ * @typedef {object} ProbeSamplerConfig
+ * @property {{ DD_DYNAMIC_INSTRUMENTATION_EVALUATION_TIMEOUT_MS: number }} dynamicInstrumentation
+ */
+
+let evaluationTimeoutNs = 0n
+
 module.exports = {
+  configureProbeSampler,
   installProbeSampler,
   uninstallProbeSampler,
 }
 
+/**
+ * Apply the evaluation time budget from the tracer configuration.
+ *
+ * @param {ProbeSamplerConfig} config - The tracer configuration.
+ */
+function configureProbeSampler (config) {
+  evaluationTimeoutNs = BigInt(config.dynamicInstrumentation.DD_DYNAMIC_INSTRUMENTATION_EVALUATION_TIMEOUT_MS) *
+    1_000_000n
+}
+
 /**
  * Install the runtime sampler in the debuggee context.
  *
  * @param {import('./guardrail-metrics').GuardrailMetrics} guardrailMetrics - Counters for skipped probe hits.
+ * @param {ProbeSamplerConfig} config - The tracer configuration.
  * @returns {SharedArrayBuffer} The shared sampler buffer to pass to the debugger worker.
  */
-function installProbeSampler (guardrailMetrics) {
+function installProbeSampler (guardrailMetrics, config) {
+  configureProbeSampler(config)
+
   const buffer = createProbeSamplerBuffer()
 
   const lastCaptureNsByProbeId = new Map()
   /**
-   * Probes whose condition recently failed to evaluate, keyed by probe id. The error is kept until the worker picks it
-   * up for the error result.
+   * Probes that are skipped at entry because a recent evaluation failed or exceeded its time budget. One error result
+   * is reported per throttle window, so the probe stays visible without repeatedly paying for the evaluation.
    *
-   * @type {Map<string, { throttledUntilNs: bigint, error: string | undefined }>}
+   * @type {Map<string, ProbeThrottle>}
+   */
+  const throttleByProbeId = new Map()
+  /**
+   * When the condition currently being evaluated started. V8 doesn't evaluate breakpoint conditions re-entrantly, and
+   * the conditions of probes at the same location are evaluated one after another, so one start time is enough. It is
+   * kept here rather than in the compiled condition so the condition can't shadow a variable of the paused frame.
    */
-  const conditionErrorByProbeId = new Map()
+  let conditionStartNs = 0n
   const sampledProbeIndexes = new Int32Array(buffer)
   Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_COUNT_INDEX, 0)
   Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_OVERFLOW_INDEX, 0)
@@ -52,7 +86,7 @@ function installProbeSampler (guardrailMetrics) {
 
   ddTraceGlobal[Symbol.for(PROBE_SAMPLER_SYMBOL)] = {
     /**
-     * Decide if a probe should be sampled and store sampled probe indexes for the debugger worker.
+     * Decide if a probe without a condition should be sampled and store sampled probe indexes for the debugger worker.
      *
      * @param {number} probeIndex - The worker-side probe sampling index.
      * @param {string} probeId - The probe id.
@@ -61,55 +95,46 @@ function installProbeSampler (guardrailMetrics) {
      */
     makeSampleDecision (probeIndex, probeId, nsBetweenSampling, isSnapshotProducingProbe) {
       const now = process.hrtime.bigint()
-      const lastCaptureNs = lastCaptureNsByProbeId.get(probeId)
-      if (lastCaptureNs !== undefined && now - lastCaptureNs < nsBetweenSampling) {
-        guardrailMetrics.eventSkipped(
-          SKIPPED_REASON.RATE_LIMIT_PROBE,
-          isSnapshotProducingProbe === true ? EVENT_TYPE.SNAPSHOT : EVENT_TYPE.LOG
-        )
-        return false
-      }
-
-      let shouldResetGlobalSnapshotRateWindow = false
-      if (isSnapshotProducingProbe === true) {
-        if (now - globalSnapshotSamplingRateWindowStart > oneSecondNs) {
-          shouldResetGlobalSnapshotRateWindow = true
-        } else if (snapshotsSampledWithinTheLastSecond >= MAX_SNAPSHOTS_PER_SECOND_GLOBALLY) {
-          guardrailMetrics.eventSkipped(SKIPPED_REASON.RATE_LIMIT_GLOBAL, EVENT_TYPE.SNAPSHOT)
-          return false
-        }
-      }
-
-      if (!storeSampledProbeIndex(probeIndex)) return false
-
-      if (isSnapshotProducingProbe === true) {
-        if (shouldResetGlobalSnapshotRateWindow === true) {
-          snapshotsSampledWithinTheLastSecond = 1
-          globalSnapshotSamplingRateWindowStart = now
-        } else {
-          snapshotsSampledWithinTheLastSecond++
-        }
-      }
+      if (isThrottled(probeId, now, isSnapshotProducingProbe)) return false
+      return sample(probeIndex, probeId, now, nsBetweenSampling, isSnapshotProducingProbe)
+    },
 
-      lastCaptureNsByProbeId.set(probeId, now)
+    /**
+     * Decide if a probe's condition should be evaluated, or skipped because a recent evaluation error throttled it. If
+     * it should be evaluated, this starts timing the evaluation against the evaluation time budget.
+     *
+     * @param {string} probeId - The probe id.
+     * @param {boolean} isSnapshotProducingProbe - Whether this probe produces snapshots.
+     */
+    shouldEvaluateCondition (probeId, isSnapshotProducingProbe) {
+      const now = process.hrtime.bigint()
+      if (isThrottled(probeId, now, isSnapshotProducingProbe)) return false
+      conditionStartNs = now
       return true
     },
 
     /**
-     * Decide if a probe's condition should be evaluated, or skipped because a recent evaluation error throttled it.
+     * Decide if a probe should be sampled now that its condition has been evaluated. A condition that exceeded the
+     * evaluation time budget is reported like a condition error instead, regardless of its result.
      *
+     * @param {number} probeIndex - The worker-side probe sampling index.
      * @param {string} probeId - The probe id.
+     * @param {boolean} matched - Whether the condition evaluated to `true`.
+     * @param {bigint} nsBetweenSampling - Minimum nanoseconds between samples for this probe.
+     * @param {boolean} isSnapshotProducingProbe - Whether this probe counts toward the global snapshot sample limit.
      */
-    shouldEvaluateCondition (probeId) {
-      const state = conditionErrorByProbeId.get(probeId)
-      if (state === undefined) return true
-      if (process.hrtime.bigint() < state.throttledUntilNs) return false
-      conditionErrorByProbeId.delete(probeId)
-      return true
+    conditionEvaluated (probeIndex, probeId, matched, nsBetweenSampling, isSnapshotProducingProbe) {
+      const now = process.hrtime.bigint()
+      const elapsedNs = now - conditionStartNs
+      if (elapsedNs > evaluationTimeoutNs) {
+        return recordConditionError(probeIndex, probeId, now, describeTimeout(elapsedNs), true)
+      }
+      return matched === true && sample(probeIndex, probeId, now, nsBetweenSampling, isSnapshotProducingProbe)
     },
 
     /**
-     * Record that a probe's condition threw, throttle the probe, and request a pause if the error can be reported.
+     * Record that a probe's condition threw, throttle the probe, and request a pause if the error can be reported. A
+     * condition that exceeded the evaluation time budget before throwing is reported as a timeout instead.
      *
      * Error results bypass the per-probe and global rate limits: they are rate limited by the throttle instead, which
      * allows one error result per probe per window. If the shared buffer is full, the error is dropped but the throttle
@@ -120,12 +145,12 @@ function installProbeSampler (guardrailMetrics) {
      * @param {unknown} error - The value thrown by the condition.
      */
     conditionError (probeIndex, probeId, error) {
-      const stored = storeSampledProbeIndex(probeIndex | CONDITION_ERROR_FLAG)
-      conditionErrorByProbeId.set(probeId, {
-        throttledUntilNs: process.hrtime.bigint() + CONDITION_ERROR_THROTTLE_NS,
-        error: stored ? describeError(error) : undefined,
-      })
-      return stored
+      const now = process.hrtime.bigint()
+      const elapsedNs = now - conditionStartNs
+      if (elapsedNs > evaluationTimeoutNs) {
+        return recordConditionError(probeIndex, probeId, now, describeTimeout(elapsedNs), true)
+      }
+      return recordConditionError(probeIndex, probeId, now, describeError(error), false)
     },
 
     /**
@@ -135,13 +160,28 @@ function installProbeSampler (guardrailMetrics) {
      * @returns {string | undefined} The error description, if any.
      */
     takeConditionError (probeId) {
-      const state = conditionErrorByProbeId.get(probeId)
+      const state = throttleByProbeId.get(probeId)
       if (state === undefined) return
       const { error } = state
       state.error = undefined
       return error
     },
 
+    /**
+     * Throttle a probe whose evaluation exceeded its time budget in the worker, e.g. while evaluating its template.
+     * Called by the worker after the result has been reported.
+     *
+     * @param {string} probeId - The probe id.
+     */
+    evaluationTimedOut (probeId) {
+      throttleByProbeId.set(probeId, {
+        untilNs: process.hrtime.bigint() + CONDITION_ERROR_THROTTLE_NS,
+        timedOut: true,
+        // A hit that raced this request may have recorded a condition error that its pause has yet to report
+        error: throttleByProbeId.get(probeId)?.error,
+      })
+    },
+
     /**
      * Remove cached sampling state for a probe.
      *
@@ -149,10 +189,100 @@ function installProbeSampler (guardrailMetrics) {
      */
     remove (probeId) {
       lastCaptureNsByProbeId.delete(probeId)
-      conditionErrorByProbeId.delete(probeId)
+      throttleByProbeId.delete(probeId)
     },
   }
 
+  /**
+   * Check if a probe is skipped at entry because of a recent evaluation error, recording the skip when the error was
+   * an exceeded time budget.
+   *
+   * @param {string} probeId - The probe id.
+   * @param {bigint | undefined} now - The current time, if already available.
+   * @param {boolean} isSnapshotProducingProbe - Whether this probe produces snapshots.
+   */
+  function isThrottled (probeId, now, isSnapshotProducingProbe) {
+    const state = throttleByProbeId.get(probeId)
+    if (state === undefined) return false
+    now ??= process.hrtime.bigint()
+    if (now >= state.untilNs) {
+      throttleByProbeId.delete(probeId)
+      return false
+    }
+    if (state.timedOut) {
+      guardrailMetrics.eventSkipped(
+        SKIPPED_REASON.EVALUATION_TIMEOUT,
+        isSnapshotProducingProbe === true ? EVENT_TYPE.SNAPSHOT : EVENT_TYPE.LOG
+      )
+    }
+    return true
+  }
+
+  /**
+   * Apply the per-probe and global rate limits and store the sampled probe index for the debugger worker.
+   *
+   * @param {number} probeIndex - The worker-side probe sampling index.
+   * @param {string} probeId - The probe id.
+   * @param {bigint} now - The current time.
+   * @param {bigint} nsBetweenSampling - Minimum nanoseconds between samples for this probe.
+   * @param {boolean} isSnapshotProducingProbe - Whether this probe counts toward the global snapshot sample limit.
+   */
+  function sample (probeIndex, probeId, now, nsBetweenSampling, isSnapshotProducingProbe) {
+    const lastCaptureNs = lastCaptureNsByProbeId.get(probeId)
+    if (lastCaptureNs !== undefined && now - lastCaptureNs < nsBetweenSampling) {
+      guardrailMetrics.eventSkipped(
+        SKIPPED_REASON.RATE_LIMIT_PROBE,
+        isSnapshotProducingProbe === true ? EVENT_TYPE.SNAPSHOT : EVENT_TYPE.LOG
+      )
+      return false
+    }
+
+    let shouldResetGlobalSnapshotRateWindow = false
+    if (isSnapshotProducingProbe === true) {
+      if (now - globalSnapshotSamplingRateWindowStart > oneSecondNs) {
+        shouldResetGlobalSnapshotRateWindow = true
+      } else if (snapshotsSampledWithinTheLastSecond >= MAX_SNAPSHOTS_PER_SECOND_GLOBALLY) {
+        guardrailMetrics.eventSkipped(SKIPPED_REASON.RATE_LIMIT_GLOBAL, EVENT_TYPE.SNAPSHOT)
+        return false
+      }
+    }
+
+    if (!storeSampledProbeIndex(probeIndex)) return false
+
+    if (isSnapshotProducingProbe === true) {
+      if (shouldResetGlobalSnapshotRateWindow === true) {
+        snapshotsSampledWithinTheLastSecond = 1
+        globalSnapshotSamplingRateWindowStart = now
+      } else {
+        snapshotsSampledWithinTheLastSecond++
+      }
+    }
+
+    lastCaptureNsByProbeId.set(probeId, now)
+    return true
+  }
+
+  /**
+   * Throttle a probe whose condition failed and request a pause so the error can be reported. Error results bypass the
+   * per-probe and global rate limits: they are rate limited by the throttle instead, which allows one error result per
+   * probe per window.
+   *
+   * @param {number} probeIndex - The worker-side probe sampling index.
+   * @param {string} probeId - The probe id.
+   * @param {bigint} now - The current time.
+   * @param {string} error - The error description.
+   * @param {boolean} timedOut - Whether the error is an exceeded time budget.
+   */
+  function recordConditionError (probeIndex, probeId, now, error, timedOut) {
+    const stored = storeSampledProbeIndex(probeIndex | CONDITION_ERROR_FLAG)
+    throttleByProbeId.set(probeId, {
+      untilNs: now + CONDITION_ERROR_THROTTLE_NS,
+      timedOut,
+      error: stored ? error : undefined,
+    })
+    return stored
+  }
+
   /**
    * Hand a sampled probe index over to the worker for the upcoming pause.
    *
@@ -224,6 +354,16 @@ function getErrorStringProperty (error, property) {
   }
 }
 
+/**
+ * Describe a condition evaluation that exceeded its time budget.
+ *
+ * @param {bigint} elapsedNs - The time the evaluation took.
+ */
+function describeTimeout (elapsedNs) {
+  return `Condition evaluation exceeded its time budget of ${evaluationTimeoutNs / 1_000_000n}ms ` +
+    `(took ${(Number(elapsedNs) / 1_000_000).toFixed(1)}ms)`
+}
+
 /**
  * Create the shared buffer used to hand sampled probe indexes from breakpoint conditions to the debugger worker.
  *

package/packages/dd-trace/src/debugger/redaction.js

@@ -0,0 +1,139 @@
+'use strict'
+
+// Used by both the main thread, which renders log template values, and the devtools client worker, which captures
+// snapshots and compiles probe expressions, so that both redact the same identifiers.
+
+// What a redacted value is rendered as in a log message.
+const REDACTED_PLACEHOLDER = '{redacted}'
+
+const DEFAULT_REDACTED_IDENTIFIERS = [
+  '2fa',
+  '_csrf',
+  '_csrf_token',
+  '_session',
+  '_xsrf',
+  'access_token',
+  'aiohttp_session',
+  'api_key',
+  'apisecret',
+  'apisignature',
+  'applicationkey',
+  'appkey',
+  'auth',
+  'authtoken',
+  'authorization',
+  'cc_number',
+  'certificatepin',
+  'cipher',
+  'client_secret',
+  'clientid',
+  'connect.sid',
+  'connectionstring',
+  'cookie',
+  'credentials',
+  'creditcard',
+  'csrf',
+  'csrf_token',
+  'cvv',
+  'databaseurl',
+  'db_url',
+  'encryption_key',
+  'encryptionkeyid',
+  'geo_location',
+  'gpg_key',
+  'ip_address',
+  'jti',
+  'jwt',
+  'license_key',
+  'masterkey',
+  'mysql_pwd',
+  'nonce',
+  'oauth',
+  'oauthtoken',
+  'otp',
+  'passhash',
+  'passwd',
+  'password',
+  'passwordb',
+  'pem_file',
+  'pgp_key',
+  'PHPSESSID',
+  'pin',
+  'pincode',
+  'pkcs8',
+  'private_key',
+  'publickey',
+  'pwd',
+  'recaptcha_key',
+  'refresh_token',
+  'routingnumber',
+  'salt',
+  'secret',
+  'secretKey',
+  'secrettoken',
+  'securitycode',
+  'security_answer',
+  'security_question',
+  'serviceaccountcredentials',
+  'session',
+  'sessionid',
+  'sessionkey',
+  'set_cookie',
+  'signature',
+  'signaturekey',
+  'ssh_key',
+  'ssn',
+  'symfony',
+  'token',
+  'transactionid',
+  'twilio_token',
+  'user_session',
+  'voterid',
+  'x-auth-token',
+  'x_api_key',
+  'x_csrftoken',
+  'x_forwarded_for',
+  'x_real_ip',
+  'XSRF-TOKEN',
+]
+
+module.exports = {
+  createIsRedactedIdentifier,
+  REDACTED_PLACEHOLDER,
+}
+
+/**
+ * Create a predicate for whether the value of an identifier must be redacted, based on the default list of redacted
+ * identifiers and the user's configuration.
+ *
+ * @param {object} config - The `dynamicInstrumentation` config.
+ * @param {string[]} config.DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS - Identifiers to redact in addition to the
+ *   defaults.
+ * @param {string[]} config.DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS - Identifiers to never redact.
+ * @returns {(name: string, isSymbol?: boolean) => boolean} Whether the identifier must be redacted. If `isSymbol` is
+ *   `true`, `name` is a `Symbol(...)` description.
+ */
+function createIsRedactedIdentifier ({
+  DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS: redactedIdentifiers,
+  DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS: excludedIdentifiers,
+}) {
+  const excluded = new Set(excludedIdentifiers.map((name) => normalizeName(name)))
+  const redacted = new Set()
+  for (const name of [...DEFAULT_REDACTED_IDENTIFIERS, ...redactedIdentifiers]) {
+    const normalized = normalizeName(name)
+    if (!excluded.has(normalized)) redacted.add(normalized)
+  }
+
+  return function isRedactedIdentifier (name, isSymbol) {
+    return redacted.has(normalizeName(name, isSymbol))
+  }
+}
+
+/**
+ * @param {string} name - The identifier name.
+ * @param {boolean} [isSymbol] - Whether the name is a `Symbol(...)` description.
+ */
+function normalizeName (name, isSymbol) {
+  if (isSymbol) name = name.slice(7, -1) // Remove `Symbol(` and `)`
+  return name.toLowerCase().replaceAll(/[-_@$.]/g, '')
+}

package/packages/dd-trace/src/knuth-hash.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const UINT64_MODULO = 2n ** 64n
+
+// Knuth's factor for the sampling algorithm shared across Datadog tracers.
+const SAMPLING_KNUTH_FACTOR = 1_111_111_111_111_111_111n
+
+/**
+ * Hashes the lower 64 bits of a trace ID for deterministic trace sampling.
+ *
+ * @param {bigint} traceId
+ */
+function knuthHash (traceId) {
+  return (traceId * SAMPLING_KNUTH_FACTOR) % UINT64_MODULO
+}
+
+module.exports = knuthHash

package/packages/dd-trace/src/llmobs/constants/tags.js

@@ -54,11 +54,13 @@ module.exports = {
   DEFAULT_MODEL: 'custom',
 
   INPUT_DOCUMENTS: '_ml_obs.meta.input.documents',
+  EXPERIMENT_INPUT: '_ml_obs.meta.input',
   INPUT_MESSAGES: '_ml_obs.meta.input.messages',
   INPUT_VALUE: '_ml_obs.meta.input.value',
   INPUT_PROMPT: '_ml_obs.meta.input.prompt',
 
   OUTPUT_DOCUMENTS: '_ml_obs.meta.output.documents',
+  EXPERIMENT_OUTPUT: '_ml_obs.meta.output',
   OUTPUT_MESSAGES: '_ml_obs.meta.output.messages',
   OUTPUT_VALUE: '_ml_obs.meta.output.value',
 

package/packages/dd-trace/src/llmobs/experiments/client.js

@@ -5,8 +5,23 @@
 
 const { Dataset, DatasetRecord } = require('./dataset')
 const { ExperimentResult } = require('./result')
+const { RemoteEvaluatorError } = require('./remote-evaluator')
 
 const API_BASE_PATH = '/api/v2/llm-obs/v1'
+const EVALUATOR_INFERENCE_API_BASE_PATH = '/api/unstable/llm-obs/v1'
+
+class ExperimentsRequestError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} statusCode
+   * @param {object} responseBody
+   */
+  constructor (message, statusCode, responseBody) {
+    super(message)
+    this.statusCode = statusCode
+    this.responseBody = responseBody
+  }
+}
 
 // Control-plane host for a Datadog site, e.g.
 //   datadoghq.com        -> api.datadoghq.com
@@ -151,7 +166,15 @@ class ExperimentsClient {
 
     const text = await response.text()
     if (!response.ok) {
-      throw new Error(`${method} ${path} failed: HTTP ${response.status} ${text}`)
+      let responseBody = {}
+      try {
+        responseBody = text ? JSON.parse(text) : {}
+      } catch {}
+      throw new ExperimentsRequestError(
+        `${method} ${path} failed: HTTP ${response.status} ${text}`,
+        response.status,
+        responseBody
+      )
     }
     return text ? JSON.parse(text) : {}
   }
@@ -247,6 +270,41 @@ class ExperimentsClient {
     return experimentFromResource(this, response?.data ?? null)
   }
 
+  /**
+   * @param {string} evalName
+   * @param {object} context
+   */
+  evaluatorInfer (evalName, context) {
+    const encodedName = encodeURIComponent(evalName)
+    const path = `${EVALUATOR_INFERENCE_API_BASE_PATH}/evaluators/${encodedName}/infer`
+    return this.jsonApiRequest('POST', path, 'evaluator_inference', { context }).then(response => {
+      const attributes = response?.data?.attributes ?? {}
+      return {
+        value: attributes.value,
+        reasoning: attributes.reasoning,
+        assessment: attributes.assessment,
+        status: attributes.status,
+      }
+    }).catch(err => {
+      const attributes = err.responseBody?.data?.attributes ?? {}
+      const backendError = attributes.error
+      if (backendError !== null && typeof backendError === 'object' && !Array.isArray(backendError)) {
+        const fallback = err.statusCode === undefined ? err.message : `HTTP ${err.statusCode}`
+        throw new RemoteEvaluatorError(
+          `Remote evaluator '${evalName}' failed: ${backendError.message ?? fallback}`,
+          { status: attributes.status, backendError }
+        )
+      }
+
+      const apiError = Array.isArray(err.responseBody?.errors) ? err.responseBody.errors[0] : undefined
+      const detail = apiError !== null && typeof apiError === 'object'
+        ? apiError.detail ?? apiError.title
+        : undefined
+      const fallback = err.statusCode === undefined ? err.message : `HTTP ${err.statusCode}`
+      throw new Error(`Failed to call evaluator '${evalName}': ${detail ?? fallback}`)
+    })
+  }
+
   postExperimentEvents (experimentId, attributes) {
     return this.jsonApiRequest(
       'POST',
@@ -278,4 +336,10 @@ class ExperimentsClient {
   }
 }
 
-module.exports = { ExperimentsClient, apiHost, appHost, API_BASE_PATH }
+module.exports = {
+  ExperimentsClient,
+  apiHost,
+  appHost,
+  API_BASE_PATH,
+  EVALUATOR_INFERENCE_API_BASE_PATH,
+}