dd-trace 5.80.0 → 5.81.0

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

@@ -1,16 +1,42 @@
 'use strict'
 
-const { collectionSizeSym, fieldCountSym } = require('./symbols')
+const { collectionSizeSym, largeCollectionSkipThresholdSym, fieldCountSym, timeBudgetSym } = require('./symbols')
+const { LARGE_OBJECT_SKIP_THRESHOLD } = require('./constants')
 const session = require('../session')
 
 const LEAF_SUBTYPES = new Set(['date', 'regexp'])
 const ITERABLE_SUBTYPES = new Set(['map', 'set', 'weakmap', 'weakset'])
+const SIZE_IN_DESCRIPTION_SUBTYPES = new Set(['array', 'typedarray', 'arraybuffer', 'dataview', 'map', 'set'])
 
 module.exports = {
-  getRuntimeObject: getObject
+  collectObjectProperties
 }
 
-async function getObject (objectId, opts, depth = 0, collection = false) {
+/**
+ * @typedef {Object} GetObjectOptions
+ * @property {Object} maxReferenceDepth - The maximum depth of the object to traverse
+ * @property {number} maxCollectionSize - The maximum size of a collection to include in the snapshot
+ * @property {number} maxFieldCount - The maximum number of properties on an object to include in the snapshot
+ * @property {bigint} deadlineNs - The deadline in nanoseconds compared to `process.hrtime.bigint()`
+ * @property {Object} ctx - A context object to track the state/progress of the snapshot collection.
+ * @property {boolean} ctx.deadlineReached - Will be set to `true` if the deadline has been reached.
+ * @property {Error[]} ctx.captureErrors - An array on which errors can be pushed if an issue is detected while
+ *   collecting the snapshot.
+ */
+
+/**
+ * Collect the properties of an object using the Chrome DevTools Protocol.
+ *
+ * @param {string} objectId - The ID of the object to get the properties of
+ * @param {GetObjectOptions} opts - The options for the snapshot. Also used to track the deadline and communicate the
+ *   deadline overrun to the caller using the `deadlineReached` flag.
+ * @param {number} [depth=0] - The depth of the object. Only used internally by this module to track the current depth
+ *   and should not be set by the caller.
+ * @param {boolean} [collection=false] - Whether the object is a collection. Only used internally by this module to
+ *   track the current object type and should not be set by the caller.
+ * @returns {Promise<Object[]>} The properties of the object
+ */
+async function collectObjectProperties (objectId, opts, depth = 0, collection = false) {
   const { result, privateProperties } = await session.post('Runtime.getProperties', {
     objectId,
     ownProperties: true // exclude inherited properties
@@ -28,6 +54,13 @@ async function getObject (objectId, opts, depth = 0, collection = false) {
   } else if (result.length > opts.maxFieldCount) {
     // Trim the number of properties on the object if there's too many.
     const size = result.length
+    if (size > LARGE_OBJECT_SKIP_THRESHOLD) {
+      opts.ctx.captureErrors.push(new Error(
+        `An object with ${size} properties was detected while collecting a snapshot. ` +
+        `This exceeds the maximum number of allowed properties of ${LARGE_OBJECT_SKIP_THRESHOLD}. ` +
+        'Future snapshots for existing probes in this location will be skipped until the Node.js process is restarted'
+      ))
+    }
     result.length = opts.maxFieldCount
     result[fieldCountSym] = size
   } else if (privateProperties) {
@@ -43,32 +76,61 @@ async function traverseGetPropertiesResult (props, opts, depth) {
 
   if (depth >= opts.maxReferenceDepth) return props
 
-  const promises = []
+  const work = []
 
   for (const prop of props) {
     if (prop.value === undefined) continue
-    const { value: { type, objectId, subtype } } = prop
+    const { value: { type, objectId, subtype, description } } = prop
     if (type === 'object') {
       if (objectId === undefined) continue // if `subtype` is "null"
       if (LEAF_SUBTYPES.has(subtype)) continue // don't waste time with these subtypes
-      promises.push(getObjectProperties(subtype, objectId, opts, depth).then((properties) => {
-        prop.value.properties = properties
-      }))
+      const size = parseLengthFromDescription(description, subtype)
+      if (size !== null && size >= LARGE_OBJECT_SKIP_THRESHOLD) {
+        const empty = []
+        empty[largeCollectionSkipThresholdSym] = size
+        prop.value.properties = empty
+        continue
+      }
+      work.push([
+        prop.value,
+        () => collectPropertiesBySubtype(subtype, objectId, opts, depth).then((properties) => {
+          prop.value.properties = properties
+        })
+      ])
     } else if (type === 'function') {
-      promises.push(getFunctionProperties(objectId, opts, depth + 1).then((properties) => {
-        prop.value.properties = properties
-      }))
+      work.push([
+        prop.value,
+        () => getFunctionProperties(objectId, opts, depth + 1).then((properties) => {
+          prop.value.properties = properties
+        })
+      ])
     }
   }
 
-  if (promises.length) {
-    await Promise.all(promises)
+  if (work.length) {
+    // Iterate over the work in chunks of 2. The closer to 1, the less we'll overshoot the deadline, but the longer it
+    // takes to complete. `2` seems to be the best compromise.
+    // Anecdotally, on my machine, with no deadline, a concurrency of `1` takes twice as long as a concurrency of `2`.
+    // From thereon, there's no real measurable savings with a higher concurrency.
+    for (let i = 0; i < work.length; i += 2) {
+      if (overBudget(opts)) {
+        for (let j = i; j < work.length; j++) {
+          work[j][0][timeBudgetSym] = true
+        }
+        break
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await Promise.all([
+        work[i][1](),
+        work[i + 1]?.[1]()
+      ])
+    }
   }
 
   return props
 }
 
-function getObjectProperties (subtype, objectId, opts, depth) {
+function collectPropertiesBySubtype (subtype, objectId, opts, depth) {
   if (ITERABLE_SUBTYPES.has(subtype)) {
     return getIterable(objectId, opts, depth)
   } else if (subtype === 'promise') {
@@ -78,7 +140,7 @@ function getObjectProperties (subtype, objectId, opts, depth) {
   } else if (subtype === 'arraybuffer') {
     return getArrayBuffer(objectId, opts, depth)
   }
-  return getObject(objectId, opts, depth + 1, subtype === 'array' || subtype === 'typedarray')
+  return collectObjectProperties(objectId, opts, depth + 1, subtype === 'array' || subtype === 'typedarray')
 }
 
 // TODO: The following extra information from `internalProperties` might be relevant to include for functions:
@@ -189,3 +251,29 @@ function removeNonEnumerableProperties (props) {
     }
   }
 }
+
+function parseLengthFromDescription (description, subtype) {
+  if (typeof description !== 'string') return null
+  if (!SIZE_IN_DESCRIPTION_SUBTYPES.has(subtype)) return null
+
+  const open = description.lastIndexOf('(')
+  if (open === -1) return null
+
+  const close = description.indexOf(')', open + 1)
+  if (close === -1) return null
+
+  const s = description.slice(open + 1, close)
+  if (s === '') return null
+
+  const n = Number(s)
+  if (!Number.isSafeInteger(n) || n < 0) return null
+  if (String(n) !== s) return null
+
+  return n
+}
+
+function overBudget (opts) {
+  if (opts.ctx.deadlineReached) return true
+  opts.ctx.deadlineReached = process.hrtime.bigint() >= opts.deadlineNs
+  return opts.ctx.deadlineReached
+}

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

@@ -0,0 +1,25 @@
+'use strict'
+
+const { getEnvironmentVariable } = require('../../../config-helper')
+
+const largeObjectSkipThreshold = Number(
+  getEnvironmentVariable('_DD_DYNAMIC_INSTRUMENTATION_EXPERIMENTAL_LARGE_OBJECT_SKIP_THRESHOLD')
+)
+
+module.exports = {
+  /**
+   * When collecting a snapshot, this constant controls what happens when objects with a large number of properties or
+   * collections (arrays, maps, sets, etc.) with a large number of elements are detected:
+   *
+   * - If a collection is detected with more than this number of elements, none of its elements will be included in the
+   *   snapshot.
+   * - If an object is detected with more than this number of properties, it will be included in the snapshot, but
+   *   snapshotting will be turned off for that probe in the future, until the probe is either updated or the Node.js
+   *   process is restarted.
+   */
+  LARGE_OBJECT_SKIP_THRESHOLD: Number.isNaN(largeObjectSkipThreshold) ? 500 : largeObjectSkipThreshold,
+  DEFAULT_MAX_COLLECTION_SIZE: 100,
+  DEFAULT_MAX_FIELD_COUNT: 20,
+  DEFAULT_MAX_LENGTH: 255,
+  DEFAULT_MAX_REFERENCE_DEPTH: 3,
+}

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

@@ -1,52 +1,83 @@
 'use strict'
 
-const { getRuntimeObject } = require('./collector')
+const {
+  DEFAULT_MAX_REFERENCE_DEPTH,
+  DEFAULT_MAX_COLLECTION_SIZE,
+  DEFAULT_MAX_FIELD_COUNT,
+  DEFAULT_MAX_LENGTH
+} = require('./constants')
+const { collectObjectProperties } = require('./collector')
 const { processRawState } = require('./processor')
-const log = require('../log')
 
-const DEFAULT_MAX_REFERENCE_DEPTH = 3
-const DEFAULT_MAX_COLLECTION_SIZE = 100
-const DEFAULT_MAX_FIELD_COUNT = 20
-const DEFAULT_MAX_LENGTH = 255
+const BIGINT_MAX = (1n << 256n) - 1n
 
 module.exports = {
   getLocalStateForCallFrame
 }
 
-function returnError () {
-  return new Error('Error getting local state')
-}
+/**
+ * @typedef {Object} GetLocalStateForCallFrameOptions
+ * @property {number} [maxReferenceDepth] - The maximum depth of the object to traverse. Defaults to
+ *   {@link DEFAULT_MAX_REFERENCE_DEPTH}.
+ * @property {number} [maxCollectionSize] - The maximum size of a collection to include in the snapshot. Defaults to
+ *   {@link DEFAULT_MAX_COLLECTION_SIZE}.
+ * @property {number} [maxFieldCount] - The maximum number of properties on an object to include in the snapshot.
+ *   Defaults to {@link DEFAULT_MAX_FIELD_COUNT}.
+ * @property {number} [maxLength] - The maximum length of a string to include in the snapshot. Defaults to
+ *   {@link DEFAULT_MAX_LENGTH}.
+ * @property {bigint} [deadlineNs] - The deadline in nanoseconds compared to `process.hrtime.bigint()`. Defaults to
+ *   {@link BIGINT_MAX}. If the deadline is reached, the snapshot will be truncated.
+ */
 
+/**
+ * Get the local state for a call frame.
+ *
+ * @param {import('inspector').Debugger.CallFrame} callFrame - The call frame to get the local state for
+ * @param {GetLocalStateForCallFrameOptions} [opts] - The options for the snapshot
+ * @returns {Promise<Object>} The local state for the call frame
+ */
 async function getLocalStateForCallFrame (
   callFrame,
   {
     maxReferenceDepth = DEFAULT_MAX_REFERENCE_DEPTH,
     maxCollectionSize = DEFAULT_MAX_COLLECTION_SIZE,
     maxFieldCount = DEFAULT_MAX_FIELD_COUNT,
-    maxLength = DEFAULT_MAX_LENGTH
+    maxLength = DEFAULT_MAX_LENGTH,
+    deadlineNs = BIGINT_MAX
   } = {}
 ) {
+  /** @type {{ deadlineReached: boolean, captureErrors: Error[] }} */
+  const ctx = { deadlineReached: false, captureErrors: [] }
+  const opts = { maxReferenceDepth, maxCollectionSize, maxFieldCount, deadlineNs, ctx }
   const rawState = []
   let processedState = null
 
-  try {
-    await Promise.all(callFrame.scopeChain.map(async (scope) => {
-      if (scope.type === 'global') return // The global scope is too noisy
-      rawState.push(...await getRuntimeObject(
-        scope.object.objectId,
-        { maxReferenceDepth, maxCollectionSize, maxFieldCount }
+  for (const scope of callFrame.scopeChain) {
+    if (scope.type === 'global') continue // The global scope is too noisy
+    const { objectId } = scope.object
+    if (objectId === undefined) continue // I haven't seen this happen, but according to the types it's possible
+    try {
+      // The objectId for a scope points to a pseudo-object whose properties are the actual variables in the scope.
+      // This is why we can just call `collectObjectProperties` directly and expect it to return the in-scope variables
+      // as an array.
+      // eslint-disable-next-line no-await-in-loop
+      rawState.push(...await collectObjectProperties(objectId, opts))
+    } catch (err) {
+      ctx.captureErrors.push(new Error(
+        `Error getting local state for closure scope (type: ${scope.type}). ` +
+        'Future snapshots for existing probes in this location will be skipped until the Node.js process is restarted',
+        { cause: err } // TODO: The cause is not used by the backend
       ))
-    }))
-  } catch (err) {
-    // TODO: We might be able to get part of the scope chain.
-    // Consider if we could set errors just for the part of the scope chain that throws during collection.
-    log.error('[debugger:devtools_client] Error getting local state for call frame', err)
-    return returnError
+    }
+    if (ctx.deadlineReached === true) break // TODO: Bad UX; Variables in remaining scopes are silently dropped
   }
 
   // Delay calling `processRawState` so the caller gets a chance to resume the main thread before processing `rawState`
-  return () => {
-    processedState = processedState ?? processRawState(rawState, maxLength)
-    return processedState
+  return {
+    processLocalState () {
+      processedState = processedState ?? processRawState(rawState, maxLength)
+      return processedState
+    },
+    captureErrors: ctx.captureErrors
   }
 }

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

@@ -1,6 +1,7 @@
 'use strict'
 
-const { collectionSizeSym, fieldCountSym } = require('./symbols')
+const { LARGE_OBJECT_SKIP_THRESHOLD } = require('./constants')
+const { collectionSizeSym, largeCollectionSkipThresholdSym, fieldCountSym, timeBudgetSym } = require('./symbols')
 const { normalizeName, REDACTED_IDENTIFIERS } = require('./redaction')
 
 module.exports = {
@@ -38,7 +39,7 @@ function getPropertyValue (prop, maxLength) {
 
 function getPropertyValueRaw (prop, maxLength) {
   // Special case for getters and setters which does not have a value property
-  if (Object.hasOwn(prop, 'get')) {
+  if (prop.get) {
     const hasGet = prop.get.type !== 'undefined'
     const hasSet = prop.set.type !== 'undefined'
     if (hasGet) {
@@ -74,11 +75,13 @@ function getPropertyValueRaw (prop, maxLength) {
 }
 
 function getObjectValue (obj, maxLength) {
+  const timeBudgetReached = obj[timeBudgetSym] === true
+
   switch (obj.subtype) {
     case undefined:
-      return toObject(obj.className, obj.properties, maxLength)
+      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'array':
-      return toArray(obj.className, obj.properties, maxLength)
+      return toArray(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'null':
       return { type: 'null', isNull: true }
     // case 'node': // TODO: What does this subtype represent?
@@ -89,28 +92,28 @@ function getObjectValue (obj, maxLength) {
       // in the `description` field. Unfortunately that's all we get from the Chrome DevTools Protocol.
       return { type: obj.className, value: `${new Date(obj.description).toISOString().slice(0, -5)}Z` }
     case 'map':
-      return toMap(obj.className, obj.properties, maxLength)
+      return toMap(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'set':
-      return toSet(obj.className, obj.properties, maxLength)
+      return toSet(obj.className, obj.properties, maxLength, timeBudgetReached)
     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)
+      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached)
     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)
+      return toObject(obj.description, obj.properties, maxLength, timeBudgetReached)
     case 'promise':
-      return toObject(obj.className, obj.properties, maxLength)
+      return toObject(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'typedarray':
-      return toArray(obj.className, obj.properties, maxLength)
+      return toArray(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'generator':
       // Use `subtype` instead of `className` to make it obvious it's a generator
-      return toObject(obj.subtype, obj.properties, maxLength)
+      return toObject(obj.subtype, obj.properties, maxLength, timeBudgetReached)
     case 'arraybuffer':
-      return toArrayBuffer(obj.className, obj.properties, maxLength)
+      return toArrayBuffer(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'weakmap':
-      return toMap(obj.className, obj.properties, maxLength)
+      return toMap(obj.className, obj.properties, maxLength, timeBudgetReached)
     case 'weakset':
-      return toSet(obj.className, obj.properties, maxLength)
+      return toSet(obj.className, obj.properties, maxLength, timeBudgetReached)
     // 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
@@ -127,8 +130,9 @@ function toFunctionOrClass (value, maxLength) {
 
   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)
+    return toObject(value.className, value.properties, maxLength, timeBudgetReached)
   }
   // This is a class
   const className = classMatch[1].trim()
@@ -150,7 +154,8 @@ function toString (str, maxLength) {
   }
 }
 
-function toObject (type, props, maxLength) {
+function toObject (type, props, maxLength, timeBudgetReached) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
   if (props === undefined) return notCapturedDepth(type)
 
   const result = {
@@ -158,7 +163,7 @@ function toObject (type, props, maxLength) {
     fields: processProperties(props, maxLength)
   }
 
-  if (Object.hasOwn(props, fieldCountSym)) {
+  if (props[fieldCountSym] !== undefined) {
     result.notCapturedReason = 'fieldCount'
     result.size = props[fieldCountSym]
   }
@@ -166,7 +171,8 @@ function toObject (type, props, maxLength) {
   return result
 }
 
-function toArray (type, elements, maxLength) {
+function toArray (type, elements, maxLength, timeBudgetReached) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
   if (elements === undefined) return notCapturedDepth(type)
 
   const result = {
@@ -177,12 +183,15 @@ function toArray (type, elements, maxLength) {
   }
 
   setNotCaptureReasonOnCollection(result, elements)
+  setNotCaptureReasonOnTooLargeCollection(result, elements)
 
   return result
 }
 
-function toMap (type, pairs, maxLength) {
+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)
 
   const result = {
     type,
@@ -195,6 +204,14 @@ function toMap (type, pairs, maxLength) {
       // This can be skipped and we can go directly to its children, of which
       // there will always be exactly two, the first containing the key, and the
       // second containing the value of this entry of the Map.
+
+      if (value[timeBudgetSym] === true) {
+        return [{ notCapturedReason: 'timeout' }, { notCapturedReason: 'timeout' }]
+      }
+      if (value.properties === undefined) {
+        return [{ notCapturedReason: 'unknown' }, { notCapturedReason: 'unknown' }]
+      }
+
       const shouldRedact = shouldRedactMapValue(value.properties[0])
       const key = getPropertyValue(value.properties[0], maxLength)
       const val = shouldRedact
@@ -205,12 +222,17 @@ function toMap (type, pairs, maxLength) {
   }
 
   setNotCaptureReasonOnCollection(result, pairs)
+  setNotCaptureReasonOnTooLargeCollection(result, pairs)
 
   return result
 }
 
-function toSet (type, values, maxLength) {
+function toSet (type, values, maxLength, timeBudgetReached) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
   if (values === undefined) return notCapturedDepth(type)
+  if (values.length > 0 && values.every(({ value }) => value[timeBudgetSym] === true)) {
+    return notCapturedTimeBudget(type)
+  }
 
   const result = {
     type,
@@ -223,16 +245,22 @@ function toSet (type, values, maxLength) {
       // `internal#entry`. This can be skipped and we can go directly to its
       // 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' }
+
       return getPropertyValue(value.properties[0], maxLength)
     })
   }
 
   setNotCaptureReasonOnCollection(result, values)
+  setNotCaptureReasonOnTooLargeCollection(result, values)
 
   return result
 }
 
-function toArrayBuffer (type, bytes, maxLength) {
+function toArrayBuffer (type, bytes, maxLength, timeBudgetReached) {
+  if (timeBudgetReached === true) return notCapturedTimeBudget(type)
   if (bytes === undefined) return notCapturedDepth(type)
 
   const size = bytes.length
@@ -271,16 +299,25 @@ function shouldRedactMapValue (key) {
 }
 
 function getNormalizedNameFromProp (prop) {
-  return normalizeName(prop.name, Object.hasOwn(prop, 'symbol'))
+  return normalizeName(prop.name, prop.symbol !== undefined)
 }
 
 function setNotCaptureReasonOnCollection (result, collection) {
-  if (Object.hasOwn(collection, collectionSizeSym)) {
+  if (collection[collectionSizeSym] !== undefined) {
     result.notCapturedReason = 'collectionSize'
     result.size = collection[collectionSizeSym]
   }
 }
 
+function setNotCaptureReasonOnTooLargeCollection (result, collection) {
+  if (collection[largeCollectionSkipThresholdSym] !== undefined) {
+    result.notCapturedReason = `Large collection with too many elements (skip threshold: ${
+      LARGE_OBJECT_SKIP_THRESHOLD
+    })`
+    result.size = collection[largeCollectionSkipThresholdSym]
+  }
+}
+
 function notCapturedDepth (type) {
   return { type, notCapturedReason: 'depth' }
 }
@@ -288,3 +325,7 @@ function notCapturedDepth (type) {
 function notCapturedRedacted (type) {
   return { type, notCapturedReason: 'redactedIdent' }
 }
+
+function notCapturedTimeBudget (type) {
+  return { type, notCapturedReason: 'timeout' }
+}

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

@@ -2,5 +2,7 @@
 
 module.exports = {
   collectionSizeSym: Symbol('datadog.collectionSize'),
-  fieldCountSym: Symbol('datadog.fieldCount')
+  largeCollectionSkipThresholdSym: Symbol('datadog.largeCollectionSkipThresholdSym'),
+  fieldCountSym: Symbol('datadog.fieldCount'),
+  timeBudgetSym: Symbol('datadog.timeout')
 }