feat(agentless): add compute_stats, trace_root, and top_level tags to agentless encoder (#7716)

bengl · web-flow · commit f89ed6125fcf · 2026-03-09T18:15:48.000Z
feat(agentless): add compute_stats, trace_root, and top_level tags to agentless encoder

Enriches agentless JSON-encoded spans with metadata required by the
intake to compute APM stats server-side:
- _dd.compute_stats on the first span of each trace
- _trace_root on root spans (parent_id == 0)
- _top_level on top-level spans

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

Co-authored-by: bryan.english &lt;bryan.english@datadoghq.com&gt;
diff --git a/packages/dd-trace/src/encode/agentless-json.js b/packages/dd-trace/src/encode/agentless-json.js
@@ -1,21 +1,35 @@
 'use strict'
 
 const log = require('../log')
+const { TOP_LEVEL_KEY } = require('../constants')
 const { truncateSpan, normalizeSpan } = require('./tags-processors')
 
 /**
  * Formats a span for JSON encoding.
  * @param {object} span - The span to format
+ * @param {boolean} isFirstSpan - Whether this is the first span in the trace
  * @returns {object} The formatted span
  */
-function formatSpan (span) {
+function formatSpan (span, isFirstSpan) {
   span = normalizeSpan(truncateSpan(span, false))
 
   if (span.span_events) {
     span.meta.events = JSON.stringify(span.span_events)
     delete span.span_events
   }
 
+  if (isFirstSpan) {
+    span.meta['_dd.compute_stats'] = '1'
+  }
+
+  if (span.parent_id?.toString(10) === '0') {
+    span.metrics._trace_root = 1
+  }
+
+  if (span.metrics[TOP_LEVEL_KEY]) {
+    span.metrics._top_level = 1
+  }
+
   return span
 }
 
@@ -83,7 +97,7 @@ class AgentlessJSONEncoder {
   encode (trace) {
     for (const span of trace) {
       try {
-        const formattedSpan = formatSpan(span)
+        const formattedSpan = formatSpan(span, this._spanCount === 0)
         const jsonSpan = spanToJSON(formattedSpan)
 
         this._spans.push(jsonSpan)
diff --git a/packages/dd-trace/test/encode/agentless-json.spec.js b/packages/dd-trace/test/encode/agentless-json.spec.js
@@ -11,6 +11,7 @@ const { AgentlessJSONEncoder } = require('../../src/encode/agentless-json')
 describe('AgentlessJSONEncoder', () => {
   let encoder
   let data
+  let childSpan
 
   beforeEach(() => {
     encoder = new AgentlessJSONEncoder()
@@ -33,6 +34,20 @@ describe('AgentlessJSONEncoder', () => {
       duration: 5000000,
       links: [],
     }]
+    childSpan = {
+      trace_id: id('1234abcd1234abcd'),
+      span_id: id('aaaa000000000001'),
+      parent_id: id('5678efab5678efab'),
+      name: 'child',
+      resource: 'child-resource',
+      service: 'test-service',
+      error: 0,
+      meta: {},
+      metrics: {},
+      start: 1234567891000000000,
+      duration: 1000000,
+      links: [],
+    }
   })
 
   describe('encode', () => {
@@ -89,18 +104,20 @@ describe('AgentlessJSONEncoder', () => {
       // Start time is converted from nanoseconds to seconds for intake format
       assert.strictEqual(span.start, 1234567890)
       assert.strictEqual(span.duration, 5000000)
-      assert.deepStrictEqual(span.meta, { foo: 'bar' })
-      assert.deepStrictEqual(span.metrics, { example: 1.5 })
+      assert.deepStrictEqual(span.meta, { foo: 'bar', '_dd.compute_stats': '1' })
+      assert.deepStrictEqual(span.metrics, { example: 1.5, _trace_root: 1 })
     })
 
     it('should handle multiple spans in one trace', () => {
       encoder.encode(data)
-      encoder.encode(data)
+      encoder.encode([childSpan])
 
       const buffer = encoder.makePayload()
       const decoded = JSON.parse(buffer.toString())
 
       assert.strictEqual(decoded.spans.length, 2)
+      assert.strictEqual(decoded.spans[0].meta['_dd.compute_stats'], '1')
+      assert.strictEqual(decoded.spans[1].meta['_dd.compute_stats'], undefined)
     })
 
     it('should handle spans without optional fields', () => {
@@ -155,6 +172,61 @@ describe('AgentlessJSONEncoder', () => {
       assert.deepStrictEqual(decoded.spans[0].links, [{ trace_id: 'abc123', span_id: 'def456' }])
     })
 
+    it('should set _dd.compute_stats on the first span only', () => {
+      encoder.encode([data[0], childSpan])
+
+      const buffer = encoder.makePayload()
+      const decoded = JSON.parse(buffer.toString())
+
+      assert.strictEqual(decoded.spans[0].meta['_dd.compute_stats'], '1')
+      assert.strictEqual(decoded.spans[1].meta['_dd.compute_stats'], undefined)
+    })
+
+    it('should set _trace_root on spans with zero parent_id', () => {
+      encoder.encode([data[0], childSpan])
+
+      const buffer = encoder.makePayload()
+      const decoded = JSON.parse(buffer.toString())
+
+      assert.strictEqual(decoded.spans[0].metrics._trace_root, 1)
+      assert.strictEqual(decoded.spans[1].metrics._trace_root, undefined)
+    })
+
+    it('should set _top_level on spans marked as top-level', () => {
+      data[0].metrics['_dd.top_level'] = 1
+
+      encoder.encode([data[0], childSpan])
+
+      const buffer = encoder.makePayload()
+      const decoded = JSON.parse(buffer.toString())
+
+      assert.strictEqual(decoded.spans[0].metrics._top_level, 1)
+      assert.strictEqual(decoded.spans[1].metrics._top_level, undefined)
+    })
+
+    it('should not set _top_level when _dd.top_level is 0', () => {
+      data[0].metrics['_dd.top_level'] = 0
+
+      encoder.encode(data)
+
+      const buffer = encoder.makePayload()
+      const decoded = JSON.parse(buffer.toString())
+
+      assert.strictEqual(decoded.spans[0].metrics._top_level, undefined)
+    })
+
+    it('should set _dd.compute_stats on next span when first span is malformed', () => {
+      const badSpan = { name: 'bad' }
+
+      encoder.encode([badSpan, childSpan])
+
+      const buffer = encoder.makePayload()
+      const decoded = JSON.parse(buffer.toString())
+
+      assert.strictEqual(decoded.spans.length, 1)
+      assert.strictEqual(decoded.spans[0].meta['_dd.compute_stats'], '1')
+    })
+
     it('should skip malformed spans and continue encoding', () => {
       const goodSpan = data[0]
       const badSpan = { name: 'bad' } // Missing required ID fields
