dd-trace 6.15.0 → 6.17.0

package/packages/dd-trace/src/debugger/devtools_client/snapshot/processor.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { INCOMPLETE_REASON } = require('../../guardrail-metrics')
 const { LARGE_OBJECT_SKIP_THRESHOLD } = require('./constants')
 const { collectionSizeSym, largeCollectionSkipThresholdSym, fieldCountSym, timeBudgetSym } = require('./symbols')
 const { normalizeName, REDACTED_IDENTIFIERS } = require('./redaction')
@@ -15,15 +16,24 @@ module.exports = {
  * @typedef {import('inspector').Runtime.RemoteObject & { properties?: object[] }} RemoteObjectWithProperties
  */
 
+/**
+ * Accumulates which capture limits were enforced while processing a single event, so they can be reported once per
+ * event instead of once per affected node.
+ *
+ * @typedef {object} IncompleteCapture
+ * @property {number} reasons - Bitmask of {@link INCOMPLETE_REASON} flags
+ */
+
 /**
  * Process a RemoteObject into the snapshot format.
  *
  * @param {RemoteObjectWithProperties} remoteObject
  * @param {number} maxLength - Maximum string length
+ * @param {IncompleteCapture} incomplete - Receives the capture limits enforced on the object
  * @returns {object} The processed value in snapshot format
  */
-function processRemoteObject (remoteObject, maxLength) {
-  return getPropertyValueRaw({ value: remoteObject }, maxLength)
+function processRemoteObject (remoteObject, maxLength, incomplete) {
+  return getPropertyValueRaw({ value: remoteObject }, maxLength, incomplete)
 }
 
 // Matches classes in source code, no matter how it's written:
@@ -33,7 +43,15 @@ function processRemoteObject (remoteObject, maxLength) {
 // - Anonymous, with odd whitespace: class\n{}
 const CLASS_REGEX = /^class\s([^{]*)/
 
-function processProperties (props, maxLength) {
+/**
+ * Process the collected properties of an object into the snapshot format.
+ *
+ * @param {object[]} props - The collected property descriptors
+ * @param {number} maxLength - Maximum string length
+ * @param {IncompleteCapture} incomplete - Receives the capture limits enforced on the properties
+ * @returns {Record<string, object>} The processed properties in snapshot format
+ */
+function processProperties (props, maxLength, incomplete) {
   const result = {}
 
   for (const prop of props) {
@@ -42,20 +60,26 @@ function processProperties (props, maxLength) {
     if (name.includes('.')) {
       name = name.replaceAll('.', '_')
     }
-    result[name] = getPropertyValue(prop, maxLength)
+    result[name] = getPropertyValue(prop, maxLength, incomplete)
   }
 
   return result
 }
 
+// Capture limits enforced while processing a value that ends up redacted never make it into the snapshot, so they are
+// not recorded as incomplete capture reasons either
+const discardedIncomplete = { reasons: 0 }
+
 // TODO: Improve performance of redaction algorithm.
 // This algorithm is probably slower than if we embedded the redaction logic inside the functions below.
 // That way we didn't have to traverse objects that will just be redacted anyway.
-function getPropertyValue (prop, maxLength) {
-  return redact(prop, getPropertyValueRaw(prop, maxLength))
+function getPropertyValue (prop, maxLength, incomplete) {
+  return shouldRedactProperty(prop)
+    ? notCapturedRedacted(getPropertyValueRaw(prop, maxLength, discardedIncomplete).type)
+    : getPropertyValueRaw(prop, maxLength, incomplete)
 }
 
-function getPropertyValueRaw (prop, maxLength) {
+function getPropertyValueRaw (prop, maxLength, incomplete) {
   // Special case for getters and setters which does not have a value property
   if (prop.get) {
     const hasGet = prop.get.type !== 'undefined'
@@ -69,15 +93,15 @@ function getPropertyValueRaw (prop, maxLength) {
 
   switch (prop.value?.type) {
     case 'object':
-      return getObjectValue(prop.value, maxLength)
+      return getObjectValue(prop.value, maxLength, incomplete)
     case 'string':
-      return toString(prop.value.value, maxLength)
+      return toString(prop.value.value, maxLength, incomplete)
     case 'number':
       return { type: 'number', value: prop.value.description } // use `description` to get it as string
     case 'boolean':
       return { type: 'boolean', value: prop.value.value === true ? 'true' : 'false' }
     case 'function':
-      return toFunctionOrClass(prop.value, maxLength)
+      return toFunctionOrClass(prop.value, maxLength, incomplete)
     case undefined: // TODO: Add test for when a prop has no value. I think it's if it's defined after the breakpoint?
     case 'undefined':
       return { type: 'undefined' }
@@ -88,18 +112,19 @@ function getPropertyValueRaw (prop, maxLength) {
     default:
       // As of this writing, the Chrome DevTools Protocol doesn't allow any other types than the ones listed above, but
       // in the future new ones might be added.
+      incomplete.reasons |= INCOMPLETE_REASON.OTHER
       return { type: prop.value.type, notCapturedReason: 'Unsupported property type' }
   }
 }
 
-function getObjectValue (obj, maxLength) {
+function getObjectValue (obj, maxLength, incomplete) {
   const timeBudgetReached = obj[timeBudgetSym] === true
 
   switch (obj.subtype) {
     case undefined:
-      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'array':
-      return toArray(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toArray(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'null':
       return { type: 'null', isNull: true }
     // case 'node': // TODO: What does this subtype represent?
@@ -113,28 +138,28 @@ function getObjectValue (obj, maxLength) {
       return { type: obj.className, value }
     }
     case 'map':
-      return toMap(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toMap(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'set':
-      return toSet(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toSet(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'error':
       // TODO: Convert stack trace to array to avoid string truncation or disable truncation in this case?
-      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'proxy':
       // Use `description` instead of `className` as the `type` to get type of target object (`Proxy(Error)` vs `proxy`)
-      return toObject(obj.description, obj.properties, maxLength, timeBudgetReached)
+      return toObject(obj.description, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'promise':
-      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'typedarray':
-      return toArray(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toArray(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'generator':
       // Use `subtype` instead of `className` to make it obvious it's a generator
-      return toObject(obj.subtype, obj.properties, maxLength, timeBudgetReached)
+      return toObject(obj.subtype, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'arraybuffer':
-      return toArrayBuffer(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toArrayBuffer(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'weakmap':
-      return toMap(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toMap(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     case 'weakset':
-      return toSet(obj.className, obj.properties, maxLength, timeBudgetReached)
+      return toSet(obj.className, obj.properties, maxLength, timeBudgetReached, incomplete)
     // case 'iterator': // TODO: I've not been able to trigger this subtype
     // case 'dataview': // TODO: Looks like the internal ArrayBuffer is only accessible via the `buffer` getter
     // case 'webassemblymemory': // TODO: Looks like the internal ArrayBuffer is only accessible via the `buffer` getter
@@ -142,31 +167,34 @@ function getObjectValue (obj, maxLength) {
     default:
       // As of this writing, the Chrome DevTools Protocol doesn't allow any other subtypes than the ones listed above,
       // but in the future new ones might be added.
+      incomplete.reasons |= INCOMPLETE_REASON.OTHER
       return { type: obj.subtype, notCapturedReason: 'Unsupported object type' }
   }
 }
 
-function toFunctionOrClass (value, maxLength) {
+function toFunctionOrClass (value, maxLength, incomplete) {
   const classMatch = value.description.match(CLASS_REGEX)
 
   if (classMatch === null) {
     // This is a function
     const timeBudgetReached = value[timeBudgetSym] === true
     // TODO: Would it make sense to detect if it's an arrow function or not?
-    return toObject(value.className, value.properties, maxLength, timeBudgetReached)
+    return toObject(value.className, value.properties, maxLength, timeBudgetReached, incomplete)
   }
   // This is a class
   const className = classMatch[1].trim()
   return { type: className ? `class ${className}` : 'class' }
 }
 
-function toString (str, maxLength) {
+function toString (str, maxLength, incomplete) {
   const size = str.length
 
   if (size <= maxLength) {
     return { type: 'string', value: str }
   }
 
+  incomplete.reasons |= INCOMPLETE_REASON.STRING_LENGTH
+
   return {
     type: 'string',
     value: str.slice(0, maxLength),
@@ -175,16 +203,17 @@ function toString (str, maxLength) {
   }
 }
 
-function toObject (type, props, maxLength, timeBudgetReached) {
-  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
-  if (props === undefined) return notCapturedDepth(type)
+function toObject (type, props, maxLength, timeBudgetReached, incomplete) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type, incomplete)
+  if (props === undefined) return notCapturedDepth(type, incomplete)
 
   const result = {
     type,
-    fields: processProperties(props, maxLength),
+    fields: processProperties(props, maxLength, incomplete),
   }
 
   if (props[fieldCountSym] !== undefined) {
+    incomplete.reasons |= INCOMPLETE_REASON.FIELD_COUNT
     result.notCapturedReason = 'fieldCount'
     result.size = props[fieldCountSym]
   }
@@ -192,27 +221,29 @@ function toObject (type, props, maxLength, timeBudgetReached) {
   return result
 }
 
-function toArray (type, elements, maxLength, timeBudgetReached) {
-  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
-  if (elements === undefined) return notCapturedDepth(type)
+function toArray (type, elements, maxLength, timeBudgetReached, incomplete) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type, incomplete)
+  if (elements === undefined) return notCapturedDepth(type, incomplete)
 
   const result = {
     type,
     elements: elements.map((element) => {
-      return getPropertyValue(element, maxLength)
+      return getPropertyValue(element, maxLength, incomplete)
     }),
   }
 
-  setNotCaptureReasonOnCollection(result, elements)
-  setNotCaptureReasonOnTooLargeCollection(result, elements)
+  setNotCaptureReasonOnCollection(result, elements, incomplete)
+  setNotCaptureReasonOnTooLargeCollection(result, elements, incomplete)
 
   return result
 }
 
-function toMap (type, pairs, maxLength, timeBudgetReached) {
-  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
-  if (pairs === undefined) return notCapturedDepth(type)
-  if (pairs.length > 0 && pairs.every(({ value }) => value[timeBudgetSym] === true)) return notCapturedTimeBudget(type)
+function toMap (type, pairs, maxLength, timeBudgetReached, incomplete) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type, incomplete)
+  if (pairs === undefined) return notCapturedDepth(type, incomplete)
+  if (pairs.length > 0 && pairs.every(({ value }) => value[timeBudgetSym] === true)) {
+    return notCapturedTimeBudget(type, incomplete)
+  }
 
   const result = {
     type,
@@ -227,32 +258,34 @@ function toMap (type, pairs, maxLength, timeBudgetReached) {
       // second containing the value of this entry of the Map.
 
       if (value[timeBudgetSym] === true) {
+        incomplete.reasons |= INCOMPLETE_REASON.TIMEOUT
         return [{ notCapturedReason: 'timeout' }, { notCapturedReason: 'timeout' }]
       }
       if (value.properties === undefined) {
+        incomplete.reasons |= INCOMPLETE_REASON.OTHER
         return [{ notCapturedReason: 'unknown' }, { notCapturedReason: 'unknown' }]
       }
 
       const shouldRedact = shouldRedactMapValue(value.properties[0])
-      const key = getPropertyValue(value.properties[0], maxLength)
+      const key = getPropertyValue(value.properties[0], maxLength, incomplete)
       const val = shouldRedact
         ? notCapturedRedacted(value.properties[1].value.type)
-        : getPropertyValue(value.properties[1], maxLength)
+        : getPropertyValue(value.properties[1], maxLength, incomplete)
       return [key, val]
     }),
   }
 
-  setNotCaptureReasonOnCollection(result, pairs)
-  setNotCaptureReasonOnTooLargeCollection(result, pairs)
+  setNotCaptureReasonOnCollection(result, pairs, incomplete)
+  setNotCaptureReasonOnTooLargeCollection(result, pairs, incomplete)
 
   return result
 }
 
-function toSet (type, values, maxLength, timeBudgetReached) {
-  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
-  if (values === undefined) return notCapturedDepth(type)
+function toSet (type, values, maxLength, timeBudgetReached, incomplete) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type, incomplete)
+  if (values === undefined) return notCapturedDepth(type, incomplete)
   if (values.length > 0 && values.every(({ value }) => value[timeBudgetSym] === true)) {
-    return notCapturedTimeBudget(type)
+    return notCapturedTimeBudget(type, incomplete)
   }
 
   const result = {
@@ -267,33 +300,42 @@ function toSet (type, values, maxLength, timeBudgetReached) {
       // children, of which there will always be exactly one, which contain the
       // actual value in this entry of the Set.
 
-      if (value[timeBudgetSym] === true) return { notCapturedReason: 'timeout' }
-      if (value.properties === undefined) return { notCapturedReason: 'unknown' }
+      if (value[timeBudgetSym] === true) {
+        incomplete.reasons |= INCOMPLETE_REASON.TIMEOUT
+        return { notCapturedReason: 'timeout' }
+      }
+      if (value.properties === undefined) {
+        incomplete.reasons |= INCOMPLETE_REASON.OTHER
+        return { notCapturedReason: 'unknown' }
+      }
 
-      return getPropertyValue(value.properties[0], maxLength)
+      return getPropertyValue(value.properties[0], maxLength, incomplete)
     }),
   }
 
-  setNotCaptureReasonOnCollection(result, values)
-  setNotCaptureReasonOnTooLargeCollection(result, values)
+  setNotCaptureReasonOnCollection(result, values, incomplete)
+  setNotCaptureReasonOnTooLargeCollection(result, values, incomplete)
 
   return result
 }
 
-function toArrayBuffer (type, bytes, maxLength, timeBudgetReached) {
-  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
-  if (bytes === undefined) return notCapturedDepth(type)
+function toArrayBuffer (type, bytes, maxLength, timeBudgetReached, incomplete) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type, incomplete)
+  if (bytes === undefined) return notCapturedDepth(type, incomplete)
 
   const size = bytes.length
 
-  return size > maxLength
-    ? {
-        type,
-        value: arrayBufferToString(bytes, maxLength),
-        truncated: true,
-        size: bytes.length,
-      }
-    : { type, value: arrayBufferToString(bytes, size) }
+  if (size > maxLength) {
+    incomplete.reasons |= INCOMPLETE_REASON.STRING_LENGTH
+    return {
+      type,
+      value: arrayBufferToString(bytes, maxLength),
+      truncated: true,
+      size: bytes.length,
+    }
+  }
+
+  return { type, value: arrayBufferToString(bytes, size) }
 }
 
 function arrayBufferToString (bytes, size) {
@@ -304,9 +346,8 @@ function arrayBufferToString (bytes, size) {
   return buf.toString()
 }
 
-function redact (prop, obj) {
-  const name = getNormalizedNameFromProp(prop)
-  return REDACTED_IDENTIFIERS.has(name) ? notCapturedRedacted(obj.type) : obj
+function shouldRedactProperty (prop) {
+  return REDACTED_IDENTIFIERS.has(getNormalizedNameFromProp(prop))
 }
 
 function shouldRedactMapValue (key) {
@@ -323,15 +364,19 @@ function getNormalizedNameFromProp (prop) {
   return normalizeName(prop.name, prop.symbol !== undefined)
 }
 
-function setNotCaptureReasonOnCollection (result, collection) {
+function setNotCaptureReasonOnCollection (result, collection, incomplete) {
   if (collection[collectionSizeSym] !== undefined) {
+    incomplete.reasons |= INCOMPLETE_REASON.COLLECTION_SIZE
     result.notCapturedReason = 'collectionSize'
     result.size = collection[collectionSizeSym]
   }
 }
 
-function setNotCaptureReasonOnTooLargeCollection (result, collection) {
+function setNotCaptureReasonOnTooLargeCollection (result, collection, incomplete) {
   if (collection[largeCollectionSkipThresholdSym] !== undefined) {
+    // The collection was skipped entirely because it exceeded the skip threshold, which is a different limit than the
+    // `maxCollectionSize` limit that `collectionSize` represents
+    incomplete.reasons |= INCOMPLETE_REASON.OTHER
     result.notCapturedReason = `Large collection with too many elements (skip threshold: ${
       LARGE_OBJECT_SKIP_THRESHOLD
     })`
@@ -339,7 +384,8 @@ function setNotCaptureReasonOnTooLargeCollection (result, collection) {
   }
 }
 
-function notCapturedDepth (type) {
+function notCapturedDepth (type, incomplete) {
+  incomplete.reasons |= INCOMPLETE_REASON.DEPTH
   return { type, notCapturedReason: 'depth' }
 }
 
@@ -347,6 +393,7 @@ function notCapturedRedacted (type) {
   return { type, notCapturedReason: 'redactedIdent' }
 }
 
-function notCapturedTimeBudget (type) {
+function notCapturedTimeBudget (type, incomplete) {
+  incomplete.reasons |= INCOMPLETE_REASON.TIMEOUT
   return { type, notCapturedReason: 'timeout' }
 }

package/packages/dd-trace/src/debugger/devtools_client/snapshot-pruner.js

@@ -143,7 +143,6 @@ class PriorityQueue {
    *
    * @param {TreeNode} a - First node to compare
    * @param {TreeNode} b - Second node to compare
-   * @returns {number} - > 0 if a has higher priority, < 0 if b has higher priority, 0 if equal
    */
   #compare (a, b) {
     const keyA = a.priorityKey
@@ -243,7 +242,6 @@ function parseJsonToTree (json) {
  *
  * @param {string} json - The JSON string to skip
  * @param {number} startIndex - The index to start skipping from
- * @returns {number} The index of the closing quote
  */
 function skipString (json, startIndex) {
   let index = startIndex + 1 // Skip opening quote
@@ -353,7 +351,6 @@ function selectNodesToPrune (root, bytesToRemove) {
  *
  * @param {string} json - The JSON string to rebuild
  * @param {Set<TreeNode>} prunedNodes - The set of nodes to replace with {"pruned":true}
- * @returns {string} The rebuilt JSON string
  */
 function rebuildJson (json, prunedNodes) {
   // Convert set to array and sort by start position (descending)

package/packages/dd-trace/src/debugger/devtools_client/status.js

@@ -7,8 +7,10 @@ const { version } = require('../../../../../package.json')
 const TTLSet = require('../../../../../vendor/dist/ttl-set')
 const request = require('../../exporters/common/request')
 const FormData = require('../../exporters/common/form-data')
-const { DEBUGGER_DIAGNOSTICS_V1 } = require('../constants')
+const { DEBUGGER_DIAGNOSTICS_V1, DIAGNOSTICS_QUEUE_MAX_BYTES } = require('../constants')
+const { DROPPED_REASON, EVENT_TYPE } = require('../guardrail-metrics')
 const config = require('./config')
+const guardrailMetrics = require('./guardrail-metrics')
 const JSONBuffer = require('./json-buffer')
 const log = require('./log')
 const getRequestOptions = require('./request-options')
@@ -28,8 +30,11 @@ const ddtags = buildTags(config, getHostname(), version, log)
 
 const cache = new TTLSet(60 * 60 * 1000) // 1 hour
 
+// Diagnostics are queued separately from probe results so that large snapshots cannot starve them. Each diagnostic is
+// a few hundred bytes, so this bound leaves room for thousands of pending status updates.
 const jsonBuffer = new JSONBuffer({
   size: config.maxTotalPayloadSize,
+  maxQueueBytes: DIAGNOSTICS_QUEUE_MAX_BYTES,
   timeout: config.dynamicInstrumentation.uploadIntervalSeconds * 1000,
   onFlush,
 })
@@ -81,15 +86,24 @@ function ackError (err, { id: probeId, version }) {
       stacktrace: err.stack,
     }
 
-    send(payload)
+    return send(payload)
   })
 }
 
 function send (payload) {
-  jsonBuffer.write(JSON.stringify(payload))
+  if (jsonBuffer.write(JSON.stringify(payload))) return true
+
+  const { probeId, status } = payload.debugger.diagnostics
+  log.debug('[debugger:devtools_client] Dropping %s status for probe %s: diagnostics queue is full', status, probeId)
+  guardrailMetrics.eventDropped(DROPPED_REASON.QUEUE_FULL, EVENT_TYPE.DIAGNOSTIC)
+  return false
 }
 
-function onFlush (payload) {
+/**
+ * @param {string} payload - The payload to send
+ * @param {() => void} done - Releases the payload from the diagnostics queue
+ */
+function onFlush (payload, done) {
   log.debug('[debugger:devtools_client] Flushing diagnostics payload buffer')
 
   const form = new FormData()
@@ -106,6 +120,7 @@ function onFlush (payload) {
   const options = getRequestOptions(config, path, form.getHeaders())
 
   request(form, options, (err) => {
+    done()
     if (err) log.error('[debugger:devtools_client] Error sending diagnostics payload', err)
   })
 }
@@ -123,6 +138,5 @@ function statusPayload (probeId, probeVersion, status) {
 function onlyUniqueUpdates (type, id, version, fn) {
   const key = `${type}-${id}-${version}`
   if (cache.has(key)) return
-  fn()
-  cache.add(key)
+  if (fn()) cache.add(key)
 }

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,
+}