feat(span-stats): encode SpanKind and GRPCStatusCode in v0.6 stats payload (#9190)

* feat(span-stats): encode SpanKind and GRPCStatusCode in v0.6 stats payload

The Agent's msgpack decoder supports SpanKind and GRPCStatusCode fields
but the encoder was never wired to send them, so spans differing only by
span kind or gRPC status were silently merged at the tracer level. This
adds both fields to the aggregation key, serializes them via toJSON(),
and encodes them in SpanStatsEncoder (map prefix 15 → 17).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore(span-stats): add GRPC_STATUS_CODE to ext/tags TypeScript declaration

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(span-stats): normalize GRPCStatusCode to numeric string to match Agent convention

The Agent's parseGRPCStatusString always produces numeric strings (e.g. "14"
for UNAVAILABLE). String status names like "NOT_FOUND" are now converted to
their numeric equivalents ("5") so client-computed stats aggregate correctly
with Agent-computed stats.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(span-stats): check OTel gRPC status aliases rpc.grpc.status_code and rpc.response.status_code

The OTel bridge stores attributes under their original key, so gRPC status
set via rpc.grpc.status_code or rpc.response.status_code was silently
dropped from GRPCStatusCode in client-side stats.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(span-stats): use bytes.writeMapPrefix for map prefix encoding

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(span-stats): convert numeric rpcStatusCode back to canonical name in OTLP output

The P1 fix stores GRPCStatusCode as a numeric string in SpanAggKey for
correct Agent v0.6 stats aggregation, but the OTLP transformer must emit
the canonical name string (e.g. 'NOT_FOUND') as rpc.response.status_code.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

ext/tags.d.ts

@@ -20,6 +20,7 @@ declare const tags: {
   HTTP_RESPONSE_HEADERS: 'http.response.headers'
   HTTP_USERAGENT: 'http.useragent',
   HTTP_CLIENT_IP: 'http.client_ip',
+  GRPC_STATUS_CODE: 'grpc.status.code'
   PATHWAY_HASH: 'pathway.hash'
 }
 

packages/dd-trace/src/encode/span-stats.js

@@ -31,7 +31,7 @@ class SpanStatsEncoder extends AgentEncoder {
   }
 
   _encodeStat (bytes, stat) {
-    bytes.writeMapPrefix(15)
+    bytes.writeMapPrefix(17)
 
     this._encodeString(bytes, 'Service')
     const service = stat.Service || DEFAULT_SERVICE_NAME
@@ -79,6 +79,12 @@ class SpanStatsEncoder extends AgentEncoder {
 
     this._encodeString(bytes, 'srv_src')
     this._encodeString(bytes, stat.srv_src || '')
+
+    this._encodeString(bytes, 'SpanKind')
+    this._encodeString(bytes, stat.SpanKind || '')
+
+    this._encodeString(bytes, 'GRPCStatusCode')
+    this._encodeString(bytes, stat.GRPCStatusCode || '')
   }
 
   _encodeBucket (bytes, bucket) {

packages/dd-trace/src/opentelemetry/metrics/otlp_span_stats_transformer.js

@@ -3,6 +3,7 @@
 const { LogCollapsingLowestDenseDDSketch } = require('../../../../../vendor/dist/@datadog/sketches-js')
 const OtlpTransformerBase = require('../otlp/otlp_transformer_base')
 const { getProtobufTypes } = require('../otlp/protobuf_loader')
+const { GRPC_STATUS_NAMES } = require('../../constants')
 
 const NS_PER_S = 1e9
 
@@ -152,7 +153,10 @@ class OtlpStatsTransformer extends OtlpTransformerBase {
     if (aggKey.method) raw['http.request.method'] = aggKey.method
     if (aggKey.endpoint) raw['http.route'] = aggKey.endpoint
     if (aggKey.rpcStatusCode !== '') {
-      raw['rpc.response.status_code'] = String(aggKey.rpcStatusCode).toUpperCase()
+      const n = Number(aggKey.rpcStatusCode)
+      raw['rpc.response.status_code'] = Number.isInteger(n) && n >= 0 && n < GRPC_STATUS_NAMES.length
+        ? GRPC_STATUS_NAMES[n]
+        : String(aggKey.rpcStatusCode).toUpperCase()
     }
 
     if (!this.#otelSemanticsEnabled) {

packages/dd-trace/src/span_stats.js

@@ -14,6 +14,8 @@ const {
   GRPC_STATUS_CODE,
 } = require('../../../ext/tags')
 const { ORIGIN_KEY, TOP_LEVEL_KEY, SVC_SRC_KEY, GRPC_STATUS_NAMES } = require('./constants')
+
+const GRPC_STATUS_CODE_MAP = Object.fromEntries(GRPC_STATUS_NAMES.map((name, i) => [name, String(i)]))
 const { version } = require('./pkg')
 const processTags = require('./process-tags')
 
@@ -108,10 +110,26 @@ class SpanAggKey {
     this.srvSrc = span.meta[SVC_SRC_KEY] || ''
     this.spanKind = span.meta[SPAN_KIND] || ''
     // dd gRPC plugin sets a numeric code via setTag; OTel/manual sets a string name via meta.
-    const grpcCode = span.meta[GRPC_STATUS_CODE] ?? span.metrics?.[GRPC_STATUS_CODE]
-    this.rpcStatusCode = typeof grpcCode === 'number'
-      ? (GRPC_STATUS_NAMES[grpcCode] ?? String(grpcCode))
-      : (grpcCode ?? '')
+    // Normalize to numeric string to match the Agent's parseGRPCStatusString convention.
+    // Also check OTel semantic aliases (rpc.grpc.status_code, rpc.response.status_code) as
+    // the OTel bridge stores attributes under their original key without remapping.
+    const grpcCode = span.meta[GRPC_STATUS_CODE] ?? span.metrics?.[GRPC_STATUS_CODE] ??
+      span.meta['rpc.grpc.status_code'] ?? span.metrics?.['rpc.grpc.status_code'] ??
+      span.meta['rpc.response.status_code'] ?? span.metrics?.['rpc.response.status_code']
+    if (typeof grpcCode === 'number') {
+      this.rpcStatusCode = String(grpcCode)
+    } else if (grpcCode) {
+      const upper = String(grpcCode).toUpperCase()
+      const numeric = GRPC_STATUS_CODE_MAP[upper]
+      if (numeric === undefined) {
+        const n = Number(grpcCode)
+        this.rpcStatusCode = Number.isInteger(n) && n >= 0 ? String(n) : ''
+      } else {
+        this.rpcStatusCode = numeric
+      }
+    } else {
+      this.rpcStatusCode = ''
+    }
   }
 
   toString () {

packages/dd-trace/test/encode/span-stats.spec.js

@@ -49,6 +49,8 @@ describe('span-stats-encode', () => {
       HTTPMethod: 'GET',
       HTTPEndpoint: '/users/:id',
       srv_src: 'kafka',
+      SpanKind: 'server',
+      GRPCStatusCode: '0',
       Hits: 30799,
       TopLevelHits: 30799,
       Duration: 1230,
@@ -204,4 +206,30 @@ describe('span-stats-encode', () => {
     const decodedStat = decoded.Stats[0].Stats[0]
     assert.strictEqual(decodedStat.srv_src, '')
   })
+
+  it('should encode SpanKind and GRPCStatusCode', () => {
+    encoder.encode(stats)
+
+    const buffer = encoder.makePayload()
+    const decoded = msgpack.decode(buffer)
+
+    const decodedStat = decoded.Stats[0].Stats[0]
+    assert.strictEqual(decodedStat.SpanKind, 'server')
+    assert.strictEqual(decodedStat.GRPCStatusCode, '0')
+  })
+
+  it('should encode SpanKind and GRPCStatusCode as empty strings when not present', () => {
+    const statsWithout = {
+      ...stats,
+      Stats: [{ ...bucket, Stats: [{ ...stat, SpanKind: undefined, GRPCStatusCode: undefined }] }],
+    }
+    encoder.encode(statsWithout)
+
+    const buffer = encoder.makePayload()
+    const decoded = msgpack.decode(buffer)
+
+    const decodedStat = decoded.Stats[0].Stats[0]
+    assert.strictEqual(decodedStat.SpanKind, '')
+    assert.strictEqual(decodedStat.GRPCStatusCode, '')
+  })
 })

packages/dd-trace/test/span_stats.spec.js

@@ -19,6 +19,8 @@ const {
   HTTP_ENDPOINT,
   HTTP_ROUTE,
   HTTP_METHOD,
+  SPAN_KIND,
+  GRPC_STATUS_CODE,
 } = require('../../../ext/tags')
 const {
   DEFAULT_SPAN_NAME,
@@ -179,6 +181,40 @@ describe('SpanAggKey', () => {
     assert.strictEqual(
       key.toString(), 'basic-span,service-name,resource-name,span-type,200,false,,,opt.plugin,,')
   })
+
+  it('should include span kind in aggregation key', () => {
+    const span = { ...basicSpan, meta: { ...basicSpan.meta, [SPAN_KIND]: 'server' } }
+    const key = new SpanAggKey(span)
+    assert.strictEqual(
+      key.toString(), 'basic-span,service-name,resource-name,span-type,200,false,,,integration,server,')
+  })
+
+  it('should normalize gRPC status name to numeric string in aggregation key', () => {
+    const span = { ...basicSpan, meta: { ...basicSpan.meta, [GRPC_STATUS_CODE]: 'NOT_FOUND' } }
+    const key = new SpanAggKey(span)
+    assert.strictEqual(
+      key.toString(), 'basic-span,service-name,resource-name,span-type,200,false,,,integration,,5')
+  })
+
+  it('should keep numeric gRPC status code as numeric string in aggregation key', () => {
+    const span = { ...basicSpan, meta: {}, metrics: { [GRPC_STATUS_CODE]: 14 } }
+    const key = new SpanAggKey(span)
+    assert.strictEqual(
+      key.toString(), 'basic-span,service-name,resource-name,span-type,0,false,,,,,14')
+  })
+
+  it('should use rpc.grpc.status_code OTel alias when grpc.status.code is absent', () => {
+    const span = { ...basicSpan, meta: { ...basicSpan.meta, 'rpc.grpc.status_code': '2' }, metrics: {} }
+    const key = new SpanAggKey(span)
+    assert.strictEqual(key.rpcStatusCode, '2')
+  })
+
+  it('should use rpc.response.status_code OTel alias as last resort', () => {
+    const meta = { ...basicSpan.meta, 'rpc.response.status_code': 'INVALID_ARGUMENT' }
+    const span = { ...basicSpan, meta, metrics: {} }
+    const key = new SpanAggKey(span)
+    assert.strictEqual(key.rpcStatusCode, '3')
+  })
 })
 
 describe('SpanAggStats', () => {