feat(debugger): implement intelligent snapshot pruning for oversized payloads

Replace the crude "delete all captures" approach with an intelligent pruning
algorithm that selectively removes the largest and deepest leaf nodes while
preserving the schema structure.

The algorithm prunes like so:

- Parses snapshots into a tree structure tracking JSON object positions
- Uses a priority queue to select nodes for pruning based on:
  1. Presence of `notCapturedReason: 'depth'`
  2. Depth level (deeper nodes pruned first)
  3. Presence of any `notCapturedReason`
  4. Size (larger nodes pruned first)
- Only prunes nodes at level 6 or deeper (`locals`)
- Promotes parent nodes when all children are pruned to reduce overhead
- Iteratively prunes if needed to reach target size

Author: watson

integration-tests/debugger/snapshot-pruning.spec.js

@@ -1,6 +1,7 @@
 'use strict'
 
-const { assert } = require('chai')
+const assert = require('node:assert/strict')
+
 const { setup } = require('./utils')
 
 describe('Dynamic Instrumentation', function () {
@@ -12,14 +13,12 @@ describe('Dynamic Instrumentation', function () {
 
       it('should prune snapshot if payload is too large', function (done) {
         t.agent.on('debugger-input', ({ payload: [payload] }) => {
-          assert.isBelow(Buffer.byteLength(JSON.stringify(payload)), 1024 * 1024) // 1MB
-          assert.notProperty(payload.debugger.snapshot, 'captures')
-          assert.strictEqual(
-            payload.debugger.snapshot.captureError,
-            'Snapshot was too large (max allowed size is 1 MiB). ' +
-            'Consider reducing the capture depth or turn off "Capture Variables" completely, ' +
-            'and instead include the variables of interest directly in the message template.'
-          )
+          const payloadSize = Buffer.byteLength(JSON.stringify(payload))
+          assert.ok(payloadSize < 1024 * 1024) // 1MB
+
+          const capturesJson = JSON.stringify(payload.debugger.snapshot.captures)
+          assert.ok(capturesJson.includes('"pruned":true'))
+
           done()
         })
 

packages/dd-trace/src/debugger/devtools_client/send.js

@@ -10,6 +10,7 @@ const { GIT_COMMIT_SHA, GIT_REPOSITORY_URL } = require('../../plugins/util/tags'
 const log = require('./log')
 const { version } = require('../../../../../package.json')
 const { getEnvironmentVariable } = require('../../config-helper')
+const { pruneSnapshot } = require('./snapshot-pruner')
 
 module.exports = send
 
@@ -55,14 +56,23 @@ function send (message, logger, dd, snapshot) {
   let size = Buffer.byteLength(json)
 
   if (size > MAX_LOG_PAYLOAD_SIZE_BYTES) {
-    // TODO: This is a very crude way to handle large payloads. Proper pruning will be implemented later (DEBUG-2624)
-    delete payload.debugger.snapshot.captures
-    payload.debugger.snapshot.captureError =
-      `Snapshot was too large (max allowed size is ${MAX_LOG_PAYLOAD_SIZE_MB} MiB). ` +
-      'Consider reducing the capture depth or turn off "Capture Variables" completely, ' +
-      'and instead include the variables of interest directly in the message template.'
-    json = JSON.stringify(payload)
-    size = Buffer.byteLength(json)
+    let pruned
+    try {
+      pruned = pruneSnapshot(json, size, MAX_LOG_PAYLOAD_SIZE_BYTES)
+    } catch (err) {
+      log.error('[debugger:devtools_client] Error pruning snapshot', err)
+    }
+
+    if (pruned) {
+      json = pruned
+      size = Buffer.byteLength(json)
+    } else {
+      // Fallback if pruning fails
+      const line = Object.keys(snapshot.captures.lines)[0]
+      snapshot.captures.lines[line].locals = { pruned: true }
+      json = JSON.stringify(payload)
+      size = Buffer.byteLength(json)
+    }
   }
 
   jsonBuffer.write(json, size)