dd-trace 6.0.0 → 6.2.0

package/packages/dd-trace/src/ci-visibility/requests/upload-test-screenshot.js

@@ -0,0 +1,156 @@
+'use strict'
+
+const { readFileSync } = require('node:fs')
+const { extname } = require('node:path')
+
+const getConfig = require('../../config')
+const request = require('../../exporters/common/request')
+const log = require('../../log')
+
+const UPLOAD_TIMEOUT_MS = 30_000
+const TEST_SCREENSHOT_ENDPOINT_PREFIX = '/api/v2/ci/test-runs/'
+const TEST_SCREENSHOT_ENDPOINT_SUFFIX = '/media'
+const UINT64_MAX = 18_446_744_073_709_551_615n
+
+function getContentType (filePath) {
+  const extension = extname(filePath).toLowerCase()
+  if (extension === '.gif') {
+    return 'image/gif'
+  }
+  if (extension === '.jpg' || extension === '.jpeg') {
+    return 'image/jpeg'
+  }
+  if (extension === '.webp') {
+    return 'image/webp'
+  }
+  return 'image/png'
+}
+
+function isValidTraceId (traceId) {
+  if (!/^[1-9]\d*$/.test(traceId)) {
+    return false
+  }
+  return BigInt(traceId) <= UINT64_MAX
+}
+
+/**
+ * Renders the idempotency key (`${traceId}:${basename(filePath)}`) into a value safe to carry in
+ * the upload's query string. The Agent's evp_proxy validates the forwarded query against a
+ * restrictive charset and rejects a raw Cypress filename (spaces, parens, non-ASCII), so the
+ * filename part is hex-encoded to [0-9a-f]; the decimal trace id and ':' separator are already in
+ * the allowed set and stay readable. Deterministic, so a retried upload reproduces the same key
+ * and the backend's UUIDv5 overwrite-on-retry holds.
+ *
+ * @param {string} idempotencyKey - The raw idempotency key (`<traceId>:<filename>`)
+ * @returns {string} A query-safe, deterministic representation of the key
+ */
+function toIdempotencyQueryValue (idempotencyKey) {
+  const separatorIndex = idempotencyKey.indexOf(':')
+  if (separatorIndex === -1) {
+    return Buffer.from(idempotencyKey, 'utf8').toString('hex')
+  }
+  const traceIdPart = idempotencyKey.slice(0, separatorIndex)
+  const filenamePart = idempotencyKey.slice(separatorIndex + 1)
+  return `${traceIdPart}:${Buffer.from(filenamePart, 'utf8').toString('hex')}`
+}
+
+/**
+ * Uploads a single test screenshot to the Test Optimization media intake.
+ * The trace id is included in the request path and the body is the raw image bytes.
+ *
+ * The media service requires two values from the tracer, sent as query params so they
+ * survive the Agent's evp_proxy (which forwards only an allow-listed header set and would
+ * otherwise strip the metadata, leaving the backend with an empty idempotency key):
+ * - `idempotencyKey`: stable per artifact and reused on retry, so a retried
+ *   upload overwrites the same stored object instead of creating a duplicate.
+ * - `capturedAtMs`: the capture time in epoch milliseconds, stamped once at
+ *   capture and resent unchanged on retry (it is part of the stored object key).
+ *
+ * @param {object} options - Upload options
+ * @param {string} options.filePath - Path to the screenshot file
+ * @param {string} options.traceId - Test trace id used as the screenshot key
+ * @param {string} options.idempotencyKey - Stable per-artifact key, reused on retry
+ * @param {number} options.capturedAtMs - Capture time in epoch milliseconds
+ * @param {URL} options.url - The base URL for the screenshot upload
+ * @param {boolean} [options.isEvpProxy] - Whether to upload through the Agent's evp_proxy
+ * @param {string} [options.evpProxyPrefix] - The evp_proxy path prefix (e.g. '/evp_proxy/v4')
+ * @param {Function} callback - Callback function (err)
+ */
+function uploadTestScreenshot (
+  { filePath, traceId, idempotencyKey, capturedAtMs, url, isEvpProxy, evpProxyPrefix },
+  callback
+) {
+  const { DD_API_KEY } = getConfig()
+
+  if (!isValidTraceId(traceId)) {
+    return callback(new Error('A non-zero decimal uint64 trace_id is required for test screenshot upload'))
+  }
+  if (!DD_API_KEY && !isEvpProxy) {
+    return callback(new Error('DD_API_KEY is required for test screenshot upload'))
+  }
+  if (!idempotencyKey) {
+    return callback(new Error('An idempotency key is required for test screenshot upload'))
+  }
+  if (!Number.isInteger(capturedAtMs) || capturedAtMs <= 0) {
+    return callback(new Error('A positive captured-at timestamp (epoch ms) is required for test screenshot upload'))
+  }
+
+  let screenshotContent
+  try {
+    screenshotContent = readFileSync(filePath)
+  } catch (err) {
+    return callback(new Error(`Failed to read screenshot at ${filePath}: ${err.message}`))
+  }
+  if (screenshotContent.length === 0) {
+    return callback(new Error(`Screenshot at ${filePath} is empty`))
+  }
+
+  // Metadata rides the query string, not X-Dd-* headers: the Agent's evp_proxy strips
+  // non-allow-listed headers, so header-borne metadata reached the backend empty. The key is
+  // rendered proxy-safe (see toIdempotencyQueryValue) because evp_proxy also validates the
+  // forwarded query against a restrictive charset. capturedAtMs is a plain integer and part of the
+  // stored object key, so it (and the key) must stay stable across retries.
+  const query = new URLSearchParams({
+    idempotency_key: toIdempotencyQueryValue(idempotencyKey),
+    captured_at_ms: String(capturedAtMs),
+  }).toString()
+  const basePath = `${TEST_SCREENSHOT_ENDPOINT_PREFIX}${traceId}${TEST_SCREENSHOT_ENDPOINT_SUFFIX}`
+
+  const contentType = getContentType(filePath)
+  const options = {
+    method: 'POST',
+    headers: {
+      'Content-Type': contentType,
+    },
+    path: `${basePath}?${query}`,
+    timeout: UPLOAD_TIMEOUT_MS,
+    url,
+  }
+
+  if (isEvpProxy) {
+    // Agent mode: prefix the evp_proxy path, tell the proxy which subdomain to forward to, and
+    // drop the API key — the Agent injects it. The query params survive the proxy.
+    options.path = `${evpProxyPrefix}${basePath}?${query}`
+    options.headers['X-Datadog-EVP-Subdomain'] = 'api'
+  } else {
+    options.headers['DD-API-KEY'] = DD_API_KEY
+  }
+
+  log.debug('Uploading test screenshot %s to %s', filePath, new URL(options.path, url).href)
+
+  request(screenshotContent, options, (err, res, statusCode) => {
+    if (err) {
+      log.error('Error uploading test screenshot: %s', err.message)
+      return callback(err)
+    }
+    if (statusCode === undefined) {
+      const uploadError = new Error('Test screenshot upload request was dropped before it was sent')
+      log.error('Error uploading test screenshot: %s', uploadError.message)
+      return callback(uploadError)
+    }
+    log.debug('Test screenshot uploaded successfully (status: %d)', statusCode)
+    callback(null)
+  })
+}
+
+module.exports = { TEST_SCREENSHOT_ENDPOINT_PREFIX, TEST_SCREENSHOT_ENDPOINT_SUFFIX, uploadTestScreenshot }

package/packages/dd-trace/src/config/generated-config-types.d.ts

@@ -213,6 +213,7 @@ export interface GeneratedConfig {
   DD_TRACE_BUNYAN_ENABLED: boolean;
   DD_TRACE_CASSANDRA_DRIVER_ENABLED: boolean;
   DD_TRACE_CHILD_PROCESS_ENABLED: boolean;
+  DD_TRACE_CLAUDE_AGENT_SDK_ENABLED: boolean;
   DD_TRACE_COLLECTIONS_ENABLED: boolean;
   DD_TRACE_COMMONPLUGIN_ENABLED: boolean;
   DD_TRACE_CONFLUENTINC_KAFKA_JAVASCRIPT_ENABLED: boolean;
@@ -252,11 +253,14 @@ export interface GeneratedConfig {
   DD_TRACE_GOOGLE_CLOUD_VERTEXAI_ENABLED: boolean;
   DD_TRACE_GOOGLE_GAX_ENABLED: boolean;
   DD_TRACE_GOOGLE_GENAI_ENABLED: boolean;
+  DD_TRACE_GRAPHQL_COLLAPSE: boolean;
+  DD_TRACE_GRAPHQL_DEPTH: number;
   DD_TRACE_GRAPHQL_ENABLED: boolean;
   DD_TRACE_GRAPHQL_ERROR_EXTENSIONS: string[];
   DD_TRACE_GRAPHQL_TAG_ENABLED: boolean;
   DD_TRACE_GRAPHQL_TOOLS_ENABLED: boolean;
   DD_TRACE_GRAPHQL_TOOLS_EXECUTOR_ENABLED: boolean;
+  DD_TRACE_GRAPHQL_VARIABLES: string[];
   DD_TRACE_GRAPHQL_YOGA_ENABLED: boolean;
   DD_TRACE_GRPC_ENABLED: boolean;
   DD_TRACE_GRPC_GRPC_JS_ENABLED: boolean;
@@ -558,6 +562,7 @@ export interface GeneratedConfig {
     DD_CIVISIBILITY_TEST_MODULE_ID: string | undefined;
     DD_CIVISIBILITY_TEST_SESSION_ID: string | undefined;
     DD_TEST_FAILED_TEST_REPLAY_ENABLED: boolean;
+    DD_TEST_FAILURE_SCREENSHOTS_ENABLED: boolean | undefined;
     DD_TEST_FLEET_CONFIG_PATH: string | undefined;
     DD_TEST_LOCAL_CONFIG_PATH: string | undefined;
     DD_TEST_MANAGEMENT_ATTEMPT_TO_FIX_RETRIES: number;
@@ -790,6 +795,7 @@ export interface GeneratedEnvVarConfig {
   DD_TELEMETRY_LOG_COLLECTION_ENABLED: boolean;
   DD_TELEMETRY_METRICS_ENABLED: boolean;
   DD_TEST_FAILED_TEST_REPLAY_ENABLED: boolean;
+  DD_TEST_FAILURE_SCREENSHOTS_ENABLED: boolean | undefined;
   DD_TEST_FLEET_CONFIG_PATH: string | undefined;
   DD_TEST_LOCAL_CONFIG_PATH: string | undefined;
   DD_TEST_MANAGEMENT_ATTEMPT_TO_FIX_RETRIES: number;
@@ -868,6 +874,7 @@ export interface GeneratedEnvVarConfig {
   DD_TRACE_BUNYAN_ENABLED: boolean;
   DD_TRACE_CASSANDRA_DRIVER_ENABLED: boolean;
   DD_TRACE_CHILD_PROCESS_ENABLED: boolean;
+  DD_TRACE_CLAUDE_AGENT_SDK_ENABLED: boolean;
   DD_TRACE_CLIENT_IP_ENABLED: boolean;
   DD_TRACE_CLIENT_IP_HEADER: string | undefined;
   DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH: number;
@@ -917,11 +924,14 @@ export interface GeneratedEnvVarConfig {
   DD_TRACE_GOOGLE_CLOUD_VERTEXAI_ENABLED: boolean;
   DD_TRACE_GOOGLE_GAX_ENABLED: boolean;
   DD_TRACE_GOOGLE_GENAI_ENABLED: boolean;
+  DD_TRACE_GRAPHQL_COLLAPSE: boolean;
+  DD_TRACE_GRAPHQL_DEPTH: number;
   DD_TRACE_GRAPHQL_ENABLED: boolean;
   DD_TRACE_GRAPHQL_ERROR_EXTENSIONS: string[];
   DD_TRACE_GRAPHQL_TAG_ENABLED: boolean;
   DD_TRACE_GRAPHQL_TOOLS_ENABLED: boolean;
   DD_TRACE_GRAPHQL_TOOLS_EXECUTOR_ENABLED: boolean;
+  DD_TRACE_GRAPHQL_VARIABLES: string[];
   DD_TRACE_GRAPHQL_YOGA_ENABLED: boolean;
   DD_TRACE_GRPC_ENABLED: boolean;
   DD_TRACE_GRPC_GRPC_JS_ENABLED: boolean;

package/packages/dd-trace/src/config/supported-configurations.json

@@ -1819,6 +1819,14 @@
         "namespace": "testOptimization"
       }
     ],
+    "DD_TEST_FAILURE_SCREENSHOTS_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": null,
+        "namespace": "testOptimization"
+      }
+    ],
     "DD_TEST_FLEET_CONFIG_PATH": [
       {
         "implementation": "A",
@@ -1946,6 +1954,13 @@
         "default": "true"
       }
     ],
+    "DD_TRACE_CLAUDE_AGENT_SDK_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "true"
+      }
+    ],
     "DD_TRACE_APOLLO_ENABLED": [
       {
         "implementation": "A",
@@ -2742,6 +2757,21 @@
         "default": "true"
       }
     ],
+    "DD_TRACE_GRAPHQL_COLLAPSE": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "true"
+      }
+    ],
+    "DD_TRACE_GRAPHQL_DEPTH": [
+      {
+        "implementation": "A",
+        "type": "int",
+        "default": "-1",
+        "allowed": "-1|\\d+"
+      }
+    ],
     "DD_TRACE_GRAPHQL_ENABLED": [
       {
         "implementation": "A",
@@ -2777,6 +2807,13 @@
         "default": "true"
       }
     ],
+    "DD_TRACE_GRAPHQL_VARIABLES": [
+      {
+        "implementation": "A",
+        "type": "array",
+        "default": ""
+      }
+    ],
     "DD_TRACE_GRAPHQL_YOGA_ENABLED": [
       {
         "implementation": "A",

package/packages/dd-trace/src/crashtracking/crashtracker.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { EOL } = require('node:os')
+const { EOL, platform } = require('node:os')
 
 // Load binding first to not import other modules if it throws
 const libdatadog = require('@datadog/libdatadog')
@@ -71,7 +71,7 @@ class Crashtracker {
 
     // Out-of-process symbolication currently works on
     // Linux only, does not work on Mac.
-    const resolveMode = require('os').platform === 'linux'
+    const resolveMode = platform() === 'linux'
       ? 'EnabledWithSymbolsInReceiver'
       : 'EnabledWithInprocessSymbols'
 

package/packages/dd-trace/src/datastreams/writer.js

@@ -4,7 +4,7 @@ const zlib = require('zlib')
 const pkg = require('../../../../package.json')
 const log = require('../log')
 const request = require('../exporters/common/request')
-const { encode: encodeMsgpack } = require('../msgpack')
+const { encode: encodeMsgpack, MAX_SIZE: MAX_CHUNK_SIZE } = require('../msgpack')
 
 function makeRequest (data, url, cb) {
   const options = {
@@ -36,7 +36,19 @@ class DataStreamsWriter {
       log.debug('Maximum number of active requests reached. Payload discarded: %j', payload)
       return
     }
-    const encodedPayload = encodeMsgpack(payload)
+
+    let encodedPayload
+    try {
+      encodedPayload = encodeMsgpack(payload)
+    } catch (error) {
+      if (error.code !== 'ERR_MSGPACK_CHUNK_OVERFLOW') throw error
+      // The msgpack-encoded pipeline-stats payload exceeded the agent
+      // intake cap. Dropping it locally is safer than letting the
+      // RangeError crash the host process; the agent would reject the
+      // oversized payload at the network boundary anyway.
+      log.error('DataStreamsWriter dropped a payload that exceeded the %d byte chunk cap', MAX_CHUNK_SIZE)
+      return
+    }
 
     zlib.gzip(encodedPayload, { level: 1 }, (err, compressedData) => {
       if (err) {

package/packages/dd-trace/src/encode/0.4.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const getConfig = require('../config')
-const { MsgpackChunk } = require('../msgpack')
+const { MsgpackChunk, MAX_SIZE: MAX_CHUNK_SIZE } = require('../msgpack')
 const log = require('../log')
 const { normalizeSpan, eventTimeNano } = require('./tags-processors')
 
@@ -265,7 +265,28 @@ class AgentEncoder {
 
     this._traceCount++
 
-    this._encode(bytes, trace)
+    try {
+      this._encode(bytes, trace)
+    } catch (error) {
+      if (error.code !== 'ERR_MSGPACK_CHUNK_OVERFLOW') throw error
+      // The trace, or the queued payload it joined, hit the chunk cap.
+      // Rolling back just the in-flight trace is unsafe: the string cache
+      // may already hold subarrays / indices pointing at bytes we'd
+      // discard, and the next encode would emit stale bytes against a
+      // smaller string table. Drop the whole queued payload so the next
+      // encode starts from a clean state. Emitting a partial buffer would
+      // corrupt the msgpack wire. The virtual `reset()` is called (not
+      // `_reset()`) so subclasses can clear their own per-payload state
+      // (e.g. `AgentlessCiVisibilityEncoder._eventCount`).
+      const dropped = this._traceCount
+      this.reset()
+      log.error(
+        'Trace encoder reset after exceeding the %d byte chunk cap; dropped %d trace(s)',
+        MAX_CHUNK_SIZE,
+        dropped
+      )
+      return
+    }
 
     if (this.#debugEncoding) {
       const end = bytes.length

package/packages/dd-trace/src/encode/0.5.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { MAX_SIZE, OverflowError } = require('../msgpack')
 const { normalizeSpan } = require('./tags-processors')
 const { AgentEncoder: BaseEncoder, stringifySpanEvents } = require('./0.4')
 
@@ -30,7 +31,17 @@ class AgentEncoder extends BaseEncoder {
     const prefixSize = 1
     const stringSize = this._stringBytes.length + 5
     const traceSize = this._traceBytes.length + 5
-    const buffer = Buffer.allocUnsafe(prefixSize + stringSize + traceSize)
+    const payloadSize = prefixSize + stringSize + traceSize
+
+    // The string table and the trace bytes are capped independently, so both
+    // can sit just under the cap while their concatenation crosses it. `encode`
+    // never sees this overflow — it only exists once the two are summed here —
+    // so the writer's flush-time catch drops the payload.
+    if (payloadSize > MAX_SIZE) {
+      throw new OverflowError(payloadSize)
+    }
+
+    const buffer = Buffer.allocUnsafe(payloadSize)
 
     buffer[0] = ARRAY_OF_TWO
 

package/packages/dd-trace/src/encode/agentless-ci-visibility.js

@@ -7,7 +7,7 @@ const {
   TELEMETRY_ENDPOINT_PAYLOAD_SERIALIZATION_MS,
   TELEMETRY_ENDPOINT_PAYLOAD_EVENTS_COUNT,
 } = require('../ci-visibility/telemetry')
-const { MsgpackChunk } = require('../msgpack')
+const { MsgpackChunk, MAX_SIZE, OverflowError } = require('../msgpack')
 const { AgentEncoder } = require('./0.4')
 const {
   truncateSpanTestOpt,
@@ -371,6 +371,16 @@ class AgentlessCiVisibilityEncoder extends AgentEncoder {
 
     const eventsBytes = this._traceBytes
     const totalSize = prefixBytes.length + eventsBytes.length
+
+    // The metadata prefix (built here, not during `encode`) and the events are
+    // capped independently, so both can stay under the cap while the assembled
+    // payload crosses it. An oversized metadata tag also overflows the prefix
+    // chunk itself inside `_encodePayloadStart` above; either way the tagged
+    // error propagates to the writer's flush-time catch to drop the payload.
+    if (totalSize > MAX_SIZE) {
+      throw new OverflowError(totalSize)
+    }
+
     const buffer = Buffer.allocUnsafe(totalSize)
     prefixBytes.buffer.copy(buffer, 0, 0, prefixBytes.length)
     eventsBytes.buffer.copy(buffer, prefixBytes.length, 0, eventsBytes.length)

package/packages/dd-trace/src/encode/coverage-ci-visibility.js

@@ -1,11 +1,12 @@
 'use strict'
-const { MsgpackChunk } = require('../msgpack')
+const { MsgpackChunk, MAX_SIZE: MAX_CHUNK_SIZE } = require('../msgpack')
 
 const {
   distributionMetric,
   TELEMETRY_ENDPOINT_PAYLOAD_SERIALIZATION_MS,
   TELEMETRY_ENDPOINT_PAYLOAD_EVENTS_COUNT,
 } = require('../ci-visibility/telemetry')
+const log = require('../log')
 const FormData = require('../exporters/common/form-data')
 const { AgentEncoder } = require('./0.4')
 
@@ -40,7 +41,24 @@ class CoverageCIVisibilityEncoder extends AgentEncoder {
     const startTime = Date.now()
 
     this._coveragesCount++
-    this.encodeCodeCoverage(this._coverageBytes, coverage)
+    try {
+      this.encodeCodeCoverage(this._coverageBytes, coverage)
+    } catch (error) {
+      if (error.code !== 'ERR_MSGPACK_CHUNK_OVERFLOW') throw error
+      // The coverage payload hit the chunk cap. `_coverageBytes` may
+      // hold a partial entry and a stale `coverages` array prefix. Drop
+      // the whole queued payload so the next encode starts from a clean
+      // state; the parent `AgentEncoder` does the equivalent for its own
+      // bytes / string cache via the inherited `_reset()`.
+      const dropped = this._coveragesCount
+      this.reset()
+      log.error(
+        'Coverage encoder reset after exceeding the %d byte chunk cap; dropped %d coverage(s)',
+        MAX_CHUNK_SIZE,
+        dropped
+      )
+      return
+    }
 
     distributionMetric(
       TELEMETRY_ENDPOINT_PAYLOAD_SERIALIZATION_MS,

package/packages/dd-trace/src/exporters/common/writer.js

@@ -3,6 +3,7 @@
 const { channel } = require('dc-polyfill')
 
 const log = require('../../log')
+const { MAX_SIZE: MAX_CHUNK_SIZE } = require('../../msgpack')
 const request = require('./request')
 const { safeJSONStringify } = require('./util')
 
@@ -27,7 +28,22 @@ class Writer {
         this.#isFirstFlush = false
         this._beforeFirstFlush()
       }
-      const payload = this._encoder.makePayload()
+      let payload
+      try {
+        payload = this._encoder.makePayload()
+      } catch (error) {
+        if (error.code !== 'ERR_MSGPACK_CHUNK_OVERFLOW') throw error
+        // Multi-chunk encoders (v0.5, CI Visibility) only learn the assembled
+        // payload exceeds the cap when `makePayload` stitches the chunks
+        // together, after `encode` already returned — so the encode-time catch
+        // never sees it. Drop the queued payload here instead of letting the
+        // RangeError escape into the host application; the agent would reject
+        // the oversized payload at the network boundary anyway.
+        this._encoder.reset()
+        log.error('Writer dropped %d trace(s) that exceeded the %d byte chunk cap', count, MAX_CHUNK_SIZE)
+        done()
+        return
+      }
       this._sendPayload(payload, count, done)
     } else {
       done()

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

@@ -48,6 +48,8 @@ function guard (fn) {
   if (!clobberBailout && (NODE_MAJOR < minMajor || NODE_MAJOR >= nextMajor)) {
     initBailout = true
     var runtimeInfo = 'Incompatible runtime Node.js ' + version + ', supported runtimes: Node.js ' + supportedRange
+    // When not forced, the process bails out here and may call process.exit() right away;
+    // forward synchronously so the telemetry child can't outlive us and wedge the exit.
     telemetry([
       { name: 'abort', tags: ['reason:incompatible_runtime'] },
       { name: 'abort.runtime', tags: [] }
@@ -55,7 +57,7 @@ function guard (fn) {
       result: 'abort',
       result_class: 'incompatible_runtime',
       result_reason: runtimeInfo
-    })
+    }, !forced)
     log.info('Aborting application instrumentation due to incompatible_runtime.')
     log.info('Found incompatible runtime Node.js %s, Supported runtimes: Node.js %s.', version, supportedRange)
     if (forced) {

package/packages/dd-trace/src/guardrails/telemetry.js

@@ -1,7 +1,13 @@
 'use strict'
 
 var fs = require('fs')
-var spawn = require('child_process').spawn
+// Capture the child_process functions at load time, before the tracer wraps the module.
+// Reaching through require('child_process') at send time would route the forwarder through
+// the tracer's own child_process instrumentation once the tracer is initialized.
+var childProcess = require('child_process')
+var spawn = childProcess.spawn
+// eslint-disable-next-line n/no-unsupported-features/node-builtins
+var spawnSync = childProcess.spawnSync
 var tracerVersion = require('../../../../package.json').version
 var log = require('./log')
 
@@ -47,7 +53,7 @@ function shouldSend (point) {
   return true
 }
 
-function sendTelemetry (name, tags, resultMetadata) {
+function sendTelemetry (name, tags, resultMetadata, synchronous) {
   var points = name
   if (typeof name === 'string') {
     points = [{ name: name, tags: tags || [] }]
@@ -74,6 +80,37 @@ function sendTelemetry (name, tags, resultMetadata) {
     }
   }
 
+  var payload = JSON.stringify({ metadata: currentMetadata, points: points })
+
+  // A forwarder spawned asynchronously can still be tearing down its stdio pipes when the
+  // injected app calls process.exit(); on Node 24.0.0/24.1.x that deadlocks the exit
+  // (fixed upstream in 24.2), hanging short-lived single-step-install processes. On the
+  // bailout path the caller passes synchronous=true, so the child is fully reaped before we
+  // return and nothing survives to race the exit. spawnSync is only reached on that path,
+  // before any instrumentation is active, so it never traces the forwarder. It exists since
+  // Node 0.11.12; the guardrails still target >=0.8, which predates the exit bug anyway.
+  if (synchronous && spawnSync) {
+    // Bound the blocking send: this telemetry is best-effort and the whole point of the
+    // synchronous path is to avoid a hung exit, so a forwarder that wedges must not become a
+    // new hard hang. On timeout spawnSync kills the child and returns error.code ETIMEDOUT.
+    var result = spawnSync(telemetryForwarderPath, ['library_entrypoint'], {
+      input: payload,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      timeout: 1000,
+      killSignal: 'SIGKILL'
+    })
+    if (result.error) {
+      if (result.error.code === 'ETIMEDOUT') {
+        log.error('Telemetry forwarder timed out')
+      } else {
+        log.error('Failed to spawn telemetry forwarder')
+      }
+    } else if (result.status) {
+      log.error('Telemetry forwarder exited with code', result.status)
+    }
+    return
+  }
+
   var proc = spawn(telemetryForwarderPath, ['library_entrypoint'], {
     stdio: 'pipe'
   })
@@ -88,5 +125,5 @@ function sendTelemetry (name, tags, resultMetadata) {
   proc.stdin.on('error', function () {
     log.error('Failed to write telemetry data to telemetry forwarder')
   })
-  proc.stdin.end(JSON.stringify({ metadata: currentMetadata, points: points }))
+  proc.stdin.end(payload)
 }