fix: send telemetry metadata before process spawn (#6375)

majorgreys · web-flow · commit 1c6c7aca491e · 2025-09-05T09:22:53.000-04:00
* fix: send telemetry metadata before process spawn

* fix: update integration test helpers for correct telemetry metadata validation

* fix: allow unknown values in telemetry metadata validation

* fix: restore atomic telemetry for abort and abort.runtime points

* fix: remove trailing spaces and fix line length in helpers

* fix: remove remaining trailing space
diff --git a/integration-tests/helpers/index.js b/integration-tests/helpers/index.js
@@ -78,7 +78,7 @@ function assertTelemetryPoints (pid, msgs, expectedTelemetryPoints) {
   let points = []
   for (const [telemetryType, data] of msgs) {
     assert.strictEqual(telemetryType, 'library_entrypoint')
-    assert.deepStrictEqual(data.metadata, meta(pid))
+    assertMetadata(data.metadata, pid)
     points = points.concat(data.points)
   }
   const expectedPoints = getPoints(...expectedTelemetryPoints)
@@ -106,18 +106,34 @@ function assertTelemetryPoints (pid, msgs, expectedTelemetryPoints) {
     return expectedPoints
   }
 
-  function meta (pid) {
-    return {
+  function assertMetadata (actualMetadata, pid) {
+    const expectedBasicMetadata = {
       language_name: 'nodejs',
       language_version: process.versions.node,
       runtime_name: 'nodejs',
       runtime_version: process.versions.node,
       tracer_version: require('../../package.json').version,
-      pid: Number(pid),
-      result: 'unknown',
-      result_reason: 'unknown',
-      result_class: 'unknown'
+      pid: Number(pid)
     }
+
+    // Validate basic metadata
+    for (const key of Object.keys(expectedBasicMetadata)) {
+      assert.strictEqual(actualMetadata[key], expectedBasicMetadata[key])
+    }
+
+    // Validate result metadata is present and has valid values
+    assert(actualMetadata.result, 'result field should be present')
+    assert(actualMetadata.result_class, 'result_class field should be present')
+    assert(actualMetadata.result_reason, 'result_reason field should be present')
+
+    // Check that result metadata has expected values for telemetry scenarios
+    const validResults = ['success', 'abort', 'error', 'unknown']
+    const validResultClasses = ['success', 'incompatible_runtime', 'incompatible_library', 'internal_error', 'unknown']
+
+    assert(validResults.includes(actualMetadata.result), `Invalid result: ${actualMetadata.result}`)
+    assert(validResultClasses.includes(actualMetadata.result_class),
+      `Invalid result_class: ${actualMetadata.result_class}`)
+    assert(typeof actualMetadata.result_reason === 'string', 'result_reason should be a string')
   }
 }
 
diff --git a/packages/datadog-instrumentations/src/helpers/register.js b/packages/datadog-instrumentations/src/helpers/register.js
@@ -146,7 +146,11 @@ for (const packageName of names) {
               `error_type:${e.constructor.name}`,
               `integration:${name}`,
               `integration_version:${version}`
-            ])
+            ], {
+              result: 'error',
+              result_class: 'internal_error',
+              result_reason: `Error during instrumentation of ${name}@${version}: ${e.message}`
+            })
           }
           namesAndSuccesses[`${name}@${version}`] = true
         }
@@ -160,7 +164,11 @@ for (const packageName of names) {
         telemetry('abort.integration', [
           `integration:${name}`,
           `integration_version:${version}`
-        ])
+        ], {
+          result: 'abort',
+          result_class: 'incompatible_library',
+          result_reason: `Incompatible integration version: ${name}@${version}`
+        })
         log.info('Found incompatible integration version: %s', nameVersion)
         seenCombo.add(nameVersion)
       }
diff --git a/packages/dd-trace/src/guardrails/index.js b/packages/dd-trace/src/guardrails/index.js
@@ -45,7 +45,11 @@ function guard (fn) {
     telemetry([
       { name: 'abort', tags: ['reason:incompatible_runtime'] },
       { name: 'abort.runtime', tags: [] }
-    ])
+    ], undefined, {
+      result: 'abort',
+      result_class: 'incompatible_runtime',
+      result_reason: 'Incompatible runtime nodejs ' + version + ', supported runtimes: nodejs ' + engines.node
+    })
     log.info('Aborting application instrumentation due to incompatible_runtime.')
     log.info('Found incompatible runtime nodejs %s, Supported runtimes: nodejs %s.', version, engines.node)
     if (forced) {
@@ -56,7 +60,11 @@ function guard (fn) {
   if (!clobberBailout && (!initBailout || forced)) {
     // Ensure the instrumentation source is set for the current process and potential child processes.
     var result = fn()
-    telemetry('complete', ['injection_forced:' + (forced && initBailout ? 'true' : 'false')])
+    telemetry('complete', ['injection_forced:' + (forced && initBailout ? 'true' : 'false')], {
+      result: 'success',
+      result_class: 'success',
+      result_reason: 'Successfully configured ddtrace package'
+    })
     log.info('Application instrumentation bootstrapping complete')
     return result
   }
diff --git a/packages/dd-trace/src/guardrails/telemetry.js b/packages/dd-trace/src/guardrails/telemetry.js
@@ -47,7 +47,7 @@ function shouldSend (point) {
   return true
 }
 
-function sendTelemetry (name, tags) {
+function sendTelemetry (name, tags, resultMetadata) {
   var points = name
   if (typeof name === 'string') {
     points = [{ name: name, tags: tags || [] }]
@@ -62,32 +62,31 @@ function sendTelemetry (name, tags) {
   if (points.length === 0) {
     return
   }
+
+  // Update metadata with provided result metadata
+  var currentMetadata = {}
+  for (var key in metadata) {
+    currentMetadata[key] = metadata[key]
+  }
+  if (resultMetadata) {
+    for (var resultKey in resultMetadata) {
+      currentMetadata[resultKey] = resultMetadata[resultKey]
+    }
+  }
+
   var proc = spawn(process.env.DD_TELEMETRY_FORWARDER_PATH, ['library_entrypoint'], {
     stdio: 'pipe'
   })
   proc.on('error', function () {
     log.error('Failed to spawn telemetry forwarder')
-    metadata.result = 'error'
-    metadata.result_class = 'internal_error'
-    metadata.result_reason = 'Failed to spawn telemetry forwarder'
   })
   proc.on('exit', function (code) {
-    if (code === 0) {
-      metadata.result = 'success'
-      metadata.result_class = 'success'
-      metadata.result_reason = 'Successfully configured ddtrace package'
-    } else {
+    if (code !== 0) {
       log.error('Telemetry forwarder exited with code', code)
-      metadata.result = 'error'
-      metadata.result_class = 'internal_error'
-      metadata.result_reason = 'Telemetry forwarder exited with code ' + code
     }
   })
   proc.stdin.on('error', function () {
     log.error('Failed to write telemetry data to telemetry forwarder')
-    metadata.result = 'error'
-    metadata.result_class = 'internal_error'
-    metadata.result_reason = 'Failed to write telemetry data to telemetry forwarder'
   })
-  proc.stdin.end(JSON.stringify({ metadata: metadata, points: points }))
+  proc.stdin.end(JSON.stringify({ metadata: currentMetadata, points: points }))
 }
diff --git a/packages/dd-trace/test/guardrails/telemetry.spec.js b/packages/dd-trace/test/guardrails/telemetry.spec.js
@@ -73,7 +73,7 @@ describe('sendTelemetry', () => {
     })
   })
 
-  describe('Error scenarios and metadata', () => {
+  describe('Result metadata parameter', () => {
     let mockProc, telemetryModule, capturedStdinData
 
     function createMockProcess () {
@@ -91,28 +91,6 @@ describe('sendTelemetry', () => {
       })
     }
 
-    function runTelemetry (eventType, value) {
-      const originalStringify = JSON.stringify
-      JSON.stringify = function (obj) {
-        if (obj && obj.metadata && obj.points) {
-          if (eventType === 'spawn-error') {
-            mockProc.emit('error', new Error(value))
-          } else if (eventType === 'exit') {
-            mockProc.emit('exit', value)
-          } else if (eventType === 'stdin-error') {
-            mockProc.stdin.emit('error', new Error(value))
-          }
-        }
-        return originalStringify.apply(this, arguments)
-      }
-
-      try {
-        telemetryModule([{ name: 'test', tags: [] }])
-      } finally {
-        JSON.stringify = originalStringify
-      }
-    }
-
     function assertStdinMetadata (expected) {
       expect(capturedStdinData).to.exist
       const parsed = JSON.parse(capturedStdinData)
@@ -127,43 +105,54 @@ describe('sendTelemetry', () => {
       telemetryModule = loadTelemetryModuleWithMockProc()
     })
 
-    it('should set error metadata when telemetry forwarder fails to spawn', () => {
-      runTelemetry('spawn-error', 'Spawn failed')
+    it('should use provided result metadata', () => {
+      telemetryModule([{ name: 'error', tags: ['integration:express'] }], undefined, {
+        result: 'error',
+        result_class: 'internal_error',
+        result_reason: 'Error during instrumentation of express@4.18.0: TypeError'
+      })
 
       assertStdinMetadata({
         result: 'error',
         result_class: 'internal_error',
-        result_reason: 'Failed to spawn telemetry forwarder'
+        result_reason: 'Error during instrumentation of express@4.18.0: TypeError'
       })
     })
 
-    it('should set error metadata when telemetry forwarder exits with non-zero code', () => {
-      runTelemetry('exit', 1)
+    it('should use provided result metadata for abort scenarios', () => {
+      telemetryModule('abort.integration', ['integration:redis'], {
+        result: 'abort',
+        result_class: 'incompatible_library',
+        result_reason: 'Incompatible integration version: redis@2.8.0'
+      })
 
       assertStdinMetadata({
-        result: 'error',
-        result_class: 'internal_error',
-        result_reason: 'Telemetry forwarder exited with code 1'
+        result: 'abort',
+        result_class: 'incompatible_library',
+        result_reason: 'Incompatible integration version: redis@2.8.0'
       })
     })
 
-    it('should set error metadata when writing to telemetry forwarder fails', () => {
-      runTelemetry('stdin-error', 'Write failed')
+    it('should default to unknown values when no metadata provided', () => {
+      telemetryModule([{ name: 'test', tags: [] }])
 
       assertStdinMetadata({
-        result: 'error',
-        result_class: 'internal_error',
-        result_reason: 'Failed to write telemetry data to telemetry forwarder'
+        result: 'unknown',
+        result_class: 'unknown',
+        result_reason: 'unknown'
       })
     })
 
-    it('should set success metadata when telemetry forwarder exits successfully', () => {
-      runTelemetry('exit', 0)
+    it('should partially override default metadata', () => {
+      telemetryModule('error', ['integration:mongodb'], {
+        result: 'error',
+        result_reason: 'Connection failed'
+      })
 
       assertStdinMetadata({
-        result: 'success',
-        result_class: 'success',
-        result_reason: 'Successfully configured ddtrace package'
+        result: 'error',
+        result_class: 'unknown',
+        result_reason: 'Connection failed'
       })
     })
   })
