dd-trace 6.16.0 → 6.18.0

package/packages/dd-trace/src/debugger/guardrail-metrics.js

@@ -0,0 +1,167 @@
+'use strict'
+
+/**
+ * Guardrail telemetry counters shared between the main thread and the debugger worker thread.
+ *
+ * Guardrail decisions are made in two places: the probe sampler that runs inside the V8 breakpoint condition on the
+ * main thread (rate limits) and the debugger worker (capture limits, queue overflow). Neither should pay for a message
+ * or a telemetry API call per skipped, dropped or incomplete event, so both increment counters in a shared buffer using
+ * atomics, and the main thread periodically drains the counters into instrumentation telemetry metrics.
+ *
+ * The metric names, tags and reason codes are defined by the "Debugger Observability for GA" specification and are
+ * shared with the other tracers. All metrics are counts in the `live_debugger` telemetry namespace.
+ */
+
+const TELEMETRY_NAMESPACE = 'live_debugger'
+
+const EVENT_TYPE = Object.freeze({
+  SNAPSHOT: 0,
+  LOG: 1,
+  DIAGNOSTIC: 2,
+})
+const EVENT_TYPE_NAMES = ['snapshot', 'log', 'diagnostic']
+
+/** Attempts stopped before event creation (`events.skipped`) */
+const SKIPPED_REASON = Object.freeze({
+  RATE_LIMIT_GLOBAL: 0,
+  RATE_LIMIT_PROBE: 1,
+  EVALUATION_TIMEOUT: 2,
+})
+const SKIPPED_REASON_NAMES = ['rateLimitGlobal', 'rateLimitProbe', 'evaluationTimeout']
+
+/** Complete events dropped before transport (`events.dropped`) */
+const DROPPED_REASON = Object.freeze({
+  QUEUE_FULL: 0,
+  // The spec allows either trimming oversized payloads or dropping them whole. This tracer trims, and reports
+  // `capture.incomplete{payloadTooLarge}` instead, so this reason exists for spec parity but is never emitted.
+  PAYLOAD_TOO_LARGE: 1,
+})
+const DROPPED_REASON_NAMES = ['queueFull', 'payloadTooLarge']
+
+/**
+ * Capture enforced limits (`capture.incomplete`). These are bit flags so that the reasons hit while producing a single
+ * event can be accumulated in a bitmask and reported once per event per reason.
+ */
+const INCOMPLETE_REASON = Object.freeze({
+  RUNTIME_ERROR: 1 << 0,
+  TIMEOUT: 1 << 1,
+  DEPTH: 1 << 2,
+  FIELD_COUNT: 1 << 3,
+  COLLECTION_SIZE: 1 << 4,
+  STRING_LENGTH: 1 << 5,
+  PAYLOAD_TOO_LARGE: 1 << 6,
+  OTHER: 1 << 7,
+})
+const INCOMPLETE_REASON_NAMES = [
+  'runtimeError', 'timeout', 'depth', 'fieldCount', 'collectionSize', 'stringLength', 'payloadTooLarge', 'other',
+]
+
+const EVENT_TYPE_COUNT = EVENT_TYPE_NAMES.length
+const SKIPPED_OFFSET = 0
+const DROPPED_OFFSET = SKIPPED_OFFSET + SKIPPED_REASON_NAMES.length * EVENT_TYPE_COUNT
+const INCOMPLETE_OFFSET = DROPPED_OFFSET + DROPPED_REASON_NAMES.length * EVENT_TYPE_COUNT
+const SLOT_COUNT = INCOMPLETE_OFFSET + INCOMPLETE_REASON_NAMES.length * EVENT_TYPE_COUNT
+
+/**
+ * @typedef {object} MetricSlot
+ * @property {string} metric - The telemetry metric name
+ * @property {string[]} tags - The telemetry tags, sorted
+ */
+
+/** @type {MetricSlot[]} */
+const SLOTS = []
+addSlots('events.skipped', SKIPPED_REASON_NAMES)
+addSlots('events.dropped', DROPPED_REASON_NAMES)
+addSlots('capture.incomplete', INCOMPLETE_REASON_NAMES)
+
+class GuardrailMetrics {
+  /** @type {Int32Array} */
+  #counters
+
+  /**
+   * @param {SharedArrayBuffer} buffer - A buffer created with {@link GuardrailMetrics.createBuffer}
+   */
+  constructor (buffer) {
+    this.#counters = new Int32Array(buffer)
+  }
+
+  /**
+   * Create the shared buffer backing the counters.
+   *
+   * @returns {SharedArrayBuffer}
+   */
+  static createBuffer () {
+    return new SharedArrayBuffer(SLOT_COUNT * Int32Array.BYTES_PER_ELEMENT)
+  }
+
+  /**
+   * Record an attempt that was stopped before an event was created.
+   *
+   * @param {number} reason - One of {@link SKIPPED_REASON}
+   * @param {number} eventType - One of {@link EVENT_TYPE}
+   */
+  eventSkipped (reason, eventType) {
+    Atomics.add(this.#counters, SKIPPED_OFFSET + reason * EVENT_TYPE_COUNT + eventType, 1)
+  }
+
+  /**
+   * Record a complete event that was dropped before transport.
+   *
+   * @param {number} reason - One of {@link DROPPED_REASON}
+   * @param {number} eventType - One of {@link EVENT_TYPE}
+   * @param {number} [count] - The number of dropped events
+   */
+  eventDropped (reason, eventType, count = 1) {
+    Atomics.add(this.#counters, DROPPED_OFFSET + reason * EVENT_TYPE_COUNT + eventType, count)
+  }
+
+  /**
+   * Record the capture limits enforced while producing a single event, once per reason.
+   *
+   * @param {number} reasons - A bitmask of {@link INCOMPLETE_REASON} flags
+   * @param {number} eventType - One of {@link EVENT_TYPE}
+   */
+  captureIncomplete (reasons, eventType) {
+    for (let bit = 0; reasons !== 0; bit++, reasons >>>= 1) {
+      if ((reasons & 1) === 1) {
+        Atomics.add(this.#counters, INCOMPLETE_OFFSET + bit * EVENT_TYPE_COUNT + eventType, 1)
+      }
+    }
+  }
+
+  /**
+   * Reset all counters and report the ones that were non-zero.
+   *
+   * @param {(metric: string, tags: string[], count: number) => void} report - Called once per non-zero counter
+   */
+  drain (report) {
+    for (let i = 0; i < SLOT_COUNT; i++) {
+      const count = Atomics.exchange(this.#counters, i, 0)
+      if (count !== 0) {
+        const { metric, tags } = SLOTS[i]
+        report(metric, tags, count)
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} metric
+ * @param {string[]} reasonNames
+ */
+function addSlots (metric, reasonNames) {
+  for (const reason of reasonNames) {
+    for (const eventType of EVENT_TYPE_NAMES) {
+      SLOTS.push({ metric, tags: [`event_type:${eventType}`, `reason:${reason}`] })
+    }
+  }
+}
+
+module.exports = {
+  DROPPED_REASON,
+  EVENT_TYPE,
+  GuardrailMetrics,
+  INCOMPLETE_REASON,
+  SKIPPED_REASON,
+  TELEMETRY_NAMESPACE,
+}

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

@@ -4,15 +4,19 @@ const { readFile } = require('fs')
 const { types } = require('util')
 const { join } = require('path')
 const { Worker, MessageChannel, threadId: parentThreadId } = require('worker_threads')
+const dc = require('dc-polyfill')
 const log = require('../log')
 const { fetchAgentInfo } = require('../agent/info')
+const telemetryMetrics = require('../telemetry/metrics')
 const getDebuggerConfig = require('./config')
 const {
   DEBUGGER_DIAGNOSTICS_V1,
   DEBUGGER_INPUT_DIRECT,
   DEBUGGER_INPUT_V2,
+  GUARDRAIL_METRICS_FLUSH_INTERVAL_MS,
   INSPECT_SEGMENT_GLOBAL_PROPERTY,
 } = require('./constants')
+const { GuardrailMetrics, TELEMETRY_NAMESPACE } = require('./guardrail-metrics')
 const { installProbeSampler, uninstallProbeSampler } = require('./probe_sampler')
 
 /**
@@ -23,12 +27,20 @@ const { installProbeSampler, uninstallProbeSampler } = require('./probe_sampler'
  * @typedef {import('../remote_config')} RemoteConfig
  */
 
+// Published by telemetry right before it sends its final metrics on process exit. The flush interval timer is unref'ed
+// and the worker does not keep the process alive, so without this hook everything counted since the last tick would
+// be lost when the application exits on its own.
+const TELEMETRY_APP_CLOSING_CHANNEL = 'datadog:telemetry:app-closing'
+
 let worker = null
 let configChannel = null
 let ackId = 0
 let rcAckCallbacks = null
 let rc = null
 let inputPath = null
+/** @type {GuardrailMetrics | null} */
+let guardrailMetrics = null
+let guardrailMetricsTimer = null
 
 // eslint-disable-next-line eslint-rules/eslint-process-env
 const { NODE_OPTIONS, ...env } = process.env
@@ -43,7 +55,6 @@ module.exports = {
 /**
  * Check if the Debugger worker is currently running
  *
- * @returns {boolean} True if the worker is started, false otherwise
  */
 function isStarted () {
   return worker !== null
@@ -77,9 +88,15 @@ function start (config, rcInstance) {
   debuggerGlobals.utilTypes = types
   debuggerGlobals[INSPECT_SEGMENT_GLOBAL_PROPERTY] = require('./inspect-segment')
 
-  const probeSamplerBuffer = installProbeSampler()
+  const guardrailMetricsBuffer = GuardrailMetrics.createBuffer()
+  guardrailMetrics = new GuardrailMetrics(guardrailMetricsBuffer)
+  guardrailMetricsTimer = setInterval(flushGuardrailMetrics, GUARDRAIL_METRICS_FLUSH_INTERVAL_MS)
+  guardrailMetricsTimer.unref?.()
+  dc.subscribe(TELEMETRY_APP_CLOSING_CHANNEL, flushGuardrailMetrics)
+
+  const probeSamplerBuffer = installProbeSampler(guardrailMetrics)
 
-  readProbeFile(config.dynamicInstrumentation.probeFile, (probes) => {
+  readProbeFile(config.dynamicInstrumentation.DD_DYNAMIC_INSTRUMENTATION_PROBE_FILE, (probes) => {
     const action = 'apply'
     for (const probe of probes) {
       probeChannel.port2.postMessage({ action, probe })
@@ -125,6 +142,7 @@ function start (config, rcInstance) {
           logPort: logChannel.port1,
           configPort: configChannel.port1,
           probeSamplerBuffer,
+          guardrailMetricsBuffer,
         },
         transferList: [probeChannel.port1, logChannel.port1, configChannel.port1],
       }
@@ -137,6 +155,11 @@ function start (config, rcInstance) {
       )
     })
 
+    const threadPausedMetric = telemetryMetrics.manager.namespace(TELEMETRY_NAMESPACE)
+      .distribution('execution.pause.duration')
+    worker.on('message', (/** @type {{ type: string, durationMs: number }} */ { type, durationMs }) => {
+      if (type === 'thread-paused') threadPausedMetric.track(durationMs)
+    })
     worker.on('error', (err) => log.error('[debugger] worker thread error', err))
     worker.on('messageerror', (err) => log.error('[debugger] received "messageerror" from worker', err))
 
@@ -211,6 +234,20 @@ function cleanup (error) {
   configChannel = null
   inputPath = null
 
+  if (guardrailMetricsTimer !== null) {
+    clearInterval(guardrailMetricsTimer)
+    guardrailMetricsTimer = null
+  }
+  if (guardrailMetrics !== null) {
+    dc.unsubscribe(TELEMETRY_APP_CLOSING_CHANNEL, flushGuardrailMetrics)
+    // Report what the worker counted up until it was stopped. Known limitation: `Worker#terminate()` interrupts the
+    // worker asynchronously, so anything it counts between this drain and its actual termination is lost. That only
+    // concerns events still sitting in the worker's upload buffer, which die with the worker anyway, so it isn't worth
+    // deferring the drain until the worker has exited.
+    flushGuardrailMetrics()
+    guardrailMetrics = null
+  }
+
   // Call any pending ack callbacks
   // Pass error for unexpected exits, or undefined for graceful shutdown
   if (rcAckCallbacks) {
@@ -223,6 +260,17 @@ function cleanup (error) {
   }
 }
 
+/**
+ * Convert the guardrail counters accumulated by the probe sampler and the worker into telemetry metrics.
+ */
+function flushGuardrailMetrics () {
+  if (guardrailMetrics === null) return
+  const namespace = telemetryMetrics.manager.namespace(TELEMETRY_NAMESPACE)
+  guardrailMetrics.drain((metric, tags, count) => {
+    namespace.count(metric, tags).inc(count)
+  })
+}
+
 /**
  * Detect which debugger endpoint is available on the agent
  *

package/packages/dd-trace/src/debugger/inspect-segment.js

@@ -34,7 +34,6 @@ module.exports = inspectSegment
  * truncates objects before inspecting them.
  *
  * @param {unknown} value
- * @returns {string}
  */
 function inspectSegment (value) {
   if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
@@ -99,7 +98,6 @@ function inspectSegment (value) {
  *
  * @param {Collection} value
  * @param {boolean} isMap
- * @returns {string}
  */
 function inspectCollection (value, isMap) {
   if (NODE_MAJOR !== 18) return inspect(value, segmentInspectOptions)
@@ -137,7 +135,6 @@ function inspectCollection (value, isMap) {
  * Determine whether inspecting a value could invoke a proxy trap or toStringTag getter.
  *
  * @param {unknown} value
- * @returns {boolean}
  */
 function inspectionCanRunUserCode (value) {
   const type = typeof value

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

@@ -1,7 +1,13 @@
 'use strict'
 
+const { types } = require('node:util')
+
 const { MAX_SNAPSHOTS_PER_SECOND_GLOBALLY } = require('./devtools_client/defaults')
+const { MAX_MESSAGE_LENGTH } = require('./constants')
+const { EVENT_TYPE, SKIPPED_REASON } = require('./guardrail-metrics')
 const {
+  CONDITION_ERROR_FLAG,
+  CONDITION_ERROR_THROTTLE_NS,
   DD_TRACE_SYMBOL,
   MAX_SAMPLED_PROBES_PER_PAUSE,
   PROBE_SAMPLER_SYMBOL,
@@ -22,12 +28,20 @@ module.exports = {
 /**
  * Install the runtime sampler in the debuggee context.
  *
+ * @param {import('./guardrail-metrics').GuardrailMetrics} guardrailMetrics - Counters for skipped probe hits.
  * @returns {SharedArrayBuffer} The shared sampler buffer to pass to the debugger worker.
  */
-function installProbeSampler () {
+function installProbeSampler (guardrailMetrics) {
   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.
+   *
+   * @type {Map<string, { throttledUntilNs: bigint, error: string | undefined }>}
+   */
+  const conditionErrorByProbeId = new Map()
   const sampledProbeIndexes = new Int32Array(buffer)
   Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_COUNT_INDEX, 0)
   Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_OVERFLOW_INDEX, 0)
@@ -44,27 +58,29 @@ function installProbeSampler () {
      * @param {string} probeId - The probe id.
      * @param {bigint} nsBetweenSampling - Minimum nanoseconds between samples for this probe.
      * @param {boolean} isSnapshotProducingProbe - Whether this probe counts toward the global snapshot sample limit.
-     * @returns {boolean} Whether this probe should make the breakpoint condition pause.
      */
     makeSampleDecision (probeIndex, probeId, nsBetweenSampling, isSnapshotProducingProbe) {
       const now = process.hrtime.bigint()
       const lastCaptureNs = lastCaptureNsByProbeId.get(probeId)
-      if (lastCaptureNs !== undefined && now - lastCaptureNs < nsBetweenSampling) return false
+      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
         }
       }
 
-      const sampledProbeCount = Atomics.add(sampledProbeIndexes, SAMPLED_PROBE_COUNT_INDEX, 1)
-      if (sampledProbeCount >= MAX_SAMPLED_PROBES_PER_PAUSE) {
-        Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_OVERFLOW_INDEX, 1)
-        return false
-      }
+      if (!storeSampledProbeIndex(probeIndex)) return false
 
       if (isSnapshotProducingProbe === true) {
         if (shouldResetGlobalSnapshotRateWindow === true) {
@@ -76,10 +92,56 @@ function installProbeSampler () {
       }
 
       lastCaptureNsByProbeId.set(probeId, now)
-      Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_INDEXES_START + sampledProbeCount, probeIndex)
       return true
     },
 
+    /**
+     * Decide if a probe's condition should be evaluated, or skipped because a recent evaluation error throttled it.
+     *
+     * @param {string} probeId - The probe id.
+     */
+    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
+    },
+
+    /**
+     * Record that a probe's condition threw, throttle the probe, and request a pause if 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. If the shared buffer is full, the error is dropped but the throttle
+     * is retained.
+     *
+     * @param {number} probeIndex - The worker-side probe sampling index.
+     * @param {string} probeId - The probe id.
+     * @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
+    },
+
+    /**
+     * Hand over the recorded condition error for a probe to the worker. Called by the worker on the paused thread.
+     *
+     * @param {string} probeId - The probe id.
+     * @returns {string | undefined} The error description, if any.
+     */
+    takeConditionError (probeId) {
+      const state = conditionErrorByProbeId.get(probeId)
+      if (state === undefined) return
+      const { error } = state
+      state.error = undefined
+      return error
+    },
+
     /**
      * Remove cached sampling state for a probe.
      *
@@ -87,9 +149,25 @@ function installProbeSampler () {
      */
     remove (probeId) {
       lastCaptureNsByProbeId.delete(probeId)
+      conditionErrorByProbeId.delete(probeId)
     },
   }
 
+  /**
+   * Hand a sampled probe index over to the worker for the upcoming pause.
+   *
+   * @param {number} value - The probe sampling index, possibly with flags set.
+   */
+  function storeSampledProbeIndex (value) {
+    const sampledProbeCount = Atomics.add(sampledProbeIndexes, SAMPLED_PROBE_COUNT_INDEX, 1)
+    if (sampledProbeCount >= MAX_SAMPLED_PROBES_PER_PAUSE) {
+      Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_OVERFLOW_INDEX, 1)
+      return false
+    }
+    Atomics.store(sampledProbeIndexes, SAMPLED_PROBE_INDEXES_START + sampledProbeCount, value)
+    return true
+  }
+
   return buffer
 }
 
@@ -100,6 +178,52 @@ function uninstallProbeSampler () {
   delete ddTraceGlobal[Symbol.for(PROBE_SAMPLER_SYMBOL)]
 }
 
+/**
+ * Describe a value thrown by a probe condition without invoking user code. Conditions can throw anything, including
+ * errors with accessors and proxies whose traps have side effects.
+ *
+ * @param {unknown} error - The thrown value.
+ */
+function describeError (error) {
+  if (typeof error === 'string') return truncateErrorDescription(error)
+  if (error === null || (typeof error !== 'object' && typeof error !== 'function')) {
+    return 'Unknown evaluation error'
+  }
+
+  const name = getErrorStringProperty(error, 'name')
+  const message = getErrorStringProperty(error, 'message')
+  if (name === undefined) return truncateErrorDescription(message ?? 'Unknown evaluation error')
+  if (message === undefined) return truncateErrorDescription(name)
+
+  return truncateErrorDescription(`${name}: ${message}`)
+}
+
+/**
+ * Bound an error description before retaining or transferring it.
+ *
+ * @param {string} description - The description to bound.
+ */
+function truncateErrorDescription (description) {
+  return description.length > MAX_MESSAGE_LENGTH
+    ? `${description.slice(0, MAX_MESSAGE_LENGTH)}…`
+    : description
+}
+
+/**
+ * Read a string-valued error property without invoking accessors or proxy traps.
+ *
+ * @param {object} error - The thrown object to inspect.
+ * @param {'name' | 'message'} property - The property to find.
+ */
+function getErrorStringProperty (error, property) {
+  while (error !== null) {
+    if (types.isProxy(error)) return
+    const descriptor = Object.getOwnPropertyDescriptor(error, property)
+    if (descriptor !== undefined) return typeof descriptor.value === 'string' ? descriptor.value : undefined
+    error = Object.getPrototypeOf(error)
+  }
+}
+
 /**
  * Create the shared buffer used to hand sampled probe indexes from breakpoint conditions to the debugger worker.
  *

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

@@ -3,13 +3,43 @@
 const DD_TRACE_SYMBOL = 'dd-trace'
 const PROBE_SAMPLER_SYMBOL = 'dd-trace.debugger.probeSampler'
 
-// Shared sampler contract used by the main debugger bootstrap and the devtools worker.
+// Shared sampler contract used by the main debugger bootstrap and the devtools worker. The debuggee hands sampled
+// probes to the worker through a shared Int32Array, drained by the worker on every pause:
+//
+//            +----------+----------+----------+----------+- - - -+------------+
+//   slot     |    0     |    1     |    2     |    3     |       | 2+MAX-1    |
+//   holds    |  count   | overflow | value    | value    |  ...  | value      |
+//            +----------+----------+----------+----------+- - - -+------------+
+//             ^COUNT     ^OVERFLOW  ^INDEXES_START
 const MAX_SAMPLED_PROBES_PER_PAUSE = 256
 const SAMPLED_PROBE_COUNT_INDEX = 0
 const SAMPLED_PROBE_OVERFLOW_INDEX = 1
 const SAMPLED_PROBE_INDEXES_START = 2
 
+// Each value above is a probe sampling index, with this flag set in bit 30 when the pause is for reporting a
+// condition evaluation error instead of a probe result. Bit 31 stays unused because the array is signed:
+//
+//            +--------+------------+--------------------------------------------+
+//   bit      |   31   |     30     |                   29..0                    |
+//   means    | unused | CONDITION_ |                samplingIndex               |
+//            | (sign) | ERROR_FLAG |                                            |
+//            +--------+------------+--------------------------------------------+
+//
+//   0x0000_0007  probe #7 matched            -> worker captures as usual
+//   0x4000_0007  probe #7's condition threw  -> worker takes the recorded error, captures nothing
+//
+//   write: probeIndex | CONDITION_ERROR_FLAG
+//   read:  value & ~CONDITION_ERROR_FLAG  -> the sampling index
+//          value &  CONDITION_ERROR_FLAG  -> non-zero when the condition threw
+const CONDITION_ERROR_FLAG = 1 << 30
+
+// A probe whose condition failed to evaluate is not evaluated again for this long. One error result is reported per
+// window, so a probe with a broken condition stays visible without repeatedly paying for the failing evaluation.
+const CONDITION_ERROR_THROTTLE_NS = 5n * 60n * 1_000_000_000n // 5 minutes
+
 module.exports = {
+  CONDITION_ERROR_FLAG,
+  CONDITION_ERROR_THROTTLE_NS,
   DD_TRACE_SYMBOL,
   MAX_SAMPLED_PROBES_PER_PAUSE,
   PROBE_SAMPLER_SYMBOL,