refactor: Updated span event generation to assign the appropriate span.kind based on the segment name (#2976)

Author: bizob2828

api.js

@@ -992,6 +992,7 @@ API.prototype.startWebTransaction = function startWebTransaction(url, handle) {
       transaction: tx,
       parent
     })
+    tx.baseSegment.spanKind = 'server'
     const newContext = context.enterSegment({ transaction: tx, segment: tx.baseSegment })
     tx.baseSegment.start()
 
@@ -1101,6 +1102,7 @@ function startBackgroundTransaction(name, group, handle) {
       parent
     })
     const newContext = context.enterSegment({ transaction: tx, segment: tx.baseSegment })
+    tx.baseSegment.spanKind = 'server'
     tx.baseSegment.partialName = group
     tx.baseSegment.start()
 

lib/context-manager/context.js

@@ -29,7 +29,7 @@ module.exports = class Context {
    * @returns {Context} a newly constructed context
    */
   enterSegment({ segment, transaction = this._transaction }) {
-    return new this.constructor(transaction, segment, this._otelCtx)
+    return new this.constructor(transaction, segment)
   }
 
   /**

lib/instrumentation/kafkajs/consumer.js

@@ -42,7 +42,7 @@ function wrapConsumer(shim, orig) {
       consumer,
       'run',
       new MessageSubscribeSpec({
-        name: `${SEGMENT_PREFIX}#run`,
+        name: `${SEGMENT_PREFIX}run`,
         destinationType: shim.TOPIC,
         promise: true,
         consumer: shim.FIRST,

lib/spans/helpers.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const HTTP_LIBRARY = 'http'
+const CATEGORIES = {
+  HTTP: 'http',
+  DATASTORE: 'datastore',
+  GENERIC: 'generic'
+}
+
+const SPAN_KIND = {
+  CONSUMER: 'consumer',
+  CLIENT: 'client',
+  INTERNAL: 'internal',
+  PRODUCER: 'producer',
+  SERVER: 'server'
+}
+
+const REGEXS = {
+  CONSUMER: /^(?:Truncated\/)?OtherTransaction\/Message\//,
+  CLIENT: {
+    EXTERNAL: /^(?:Truncated\/)?External\//,
+    DATASTORE: /^(?:Truncated\/)?Datastore\//,
+  },
+  PRODUCER: /^(?:Truncated\/)?MessageBroker\//,
+  SERVER: /^(?:Truncated\/)?(WebTransaction)\//
+}
+
+/**
+ * Assigns the appropriate span kind based on the segment name.
+ * Does not handle client kind as this is done in the `HttpSpanEvent` and `DatastoreSpanEvent`
+ * Our agent has conventions for naming all types of segments.
+ * The only place this convention does not exist is within the `api.startWebTransaction`
+ * and `api.startBackgroundTransaction`. For those, we have assigned a `spanKind` property
+ * on the segment.  We default to `internal` if it cannot match a regex.
+ *
+ * @param {object} params to function
+ * @param {TraceSegment} params.segment segment that is creating span
+ * @param {object} params.span span to add `intrinsics['span.kind']`
+ */
+function addSpanKind({ segment, span }) {
+  const intrinsics = span.getIntrinsicAttributes()
+  if (!intrinsics['span.kind']) {
+    let spanKind
+    if (segment.spanKind) {
+      spanKind = segment.spanKind
+    } else if (REGEXS.CONSUMER.test(segment.name)) {
+      spanKind = SPAN_KIND.CONSUMER
+    } else if (REGEXS.PRODUCER.test(segment.name)) {
+      spanKind = SPAN_KIND.PRODUCER
+    } else if (REGEXS.SERVER.test(segment.name)) {
+      spanKind = SPAN_KIND.SERVER
+    } else {
+      spanKind = SPAN_KIND.INTERNAL
+    }
+
+    span.addIntrinsicAttribute('span.kind', spanKind)
+  }
+}
+
+module.exports = {
+  HTTP_LIBRARY,
+  CATEGORIES,
+  SPAN_KIND,
+  REGEXS,
+  addSpanKind
+}

lib/spans/span-event.js

@@ -9,18 +9,7 @@ const Config = require('../config')
 const { truncate } = require('../util/byte-limit')
 
 const { DESTINATIONS } = require('../config/attribute-filter')
-
-const HTTP_LIBRARY = 'http'
-const CLIENT_KIND = 'client'
-const CATEGORIES = {
-  HTTP: 'http',
-  DATASTORE: 'datastore',
-  GENERIC: 'generic'
-}
-
-const EXTERNAL_REGEX = /^(?:Truncated\/)?External\//
-const DATASTORE_REGEX = /^(?:Truncated\/)?Datastore\//
-
+const { addSpanKind, HTTP_LIBRARY, REGEXS, SPAN_KIND, CATEGORIES } = require('./helpers')
 const EMPTY_USER_ATTRS = Object.freeze(Object.create(null))
 const SERVER_ADDRESS = 'server.address'
 
@@ -74,6 +63,14 @@ class SpanEvent {
     }
   }
 
+  getIntrinsicAttributes() {
+    return this.intrinsics
+  }
+
+  addIntrinsicAttribute(key, value) {
+    this.intrinsics[key] = value
+  }
+
   static get CATEGORIES() {
     return CATEGORIES
   }
@@ -153,6 +150,7 @@ class SpanEvent {
     span.intrinsics.timestamp = segment.timer.start
     span.intrinsics.duration = segment.timer.getDurationInMillis() / 1000
 
+    addSpanKind({ segment, span })
     return span
   }
 
@@ -193,7 +191,7 @@ class HttpSpanEvent extends SpanEvent {
 
     this.intrinsics.category = CATEGORIES.HTTP
     this.intrinsics.component = attributes.library || HTTP_LIBRARY
-    this.intrinsics['span.kind'] = CLIENT_KIND
+    this.intrinsics['span.kind'] = SPAN_KIND.CLIENT
 
     if (attributes.library) {
       attributes.library = null
@@ -217,7 +215,7 @@ class HttpSpanEvent extends SpanEvent {
   }
 
   static testSegment(segment) {
-    return EXTERNAL_REGEX.test(segment.name)
+    return REGEXS.CLIENT.EXTERNAL.test(segment.name)
   }
 }
 
@@ -232,7 +230,7 @@ class DatastoreSpanEvent extends SpanEvent {
     super(attributes, customAttributes)
 
     this.intrinsics.category = CATEGORIES.DATASTORE
-    this.intrinsics['span.kind'] = CLIENT_KIND
+    this.intrinsics['span.kind'] = SPAN_KIND.CLIENT
 
     if (attributes.product) {
       this.intrinsics.component = attributes.product
@@ -279,7 +277,7 @@ class DatastoreSpanEvent extends SpanEvent {
   }
 
   static testSegment(segment) {
-    return DATASTORE_REGEX.test(segment.name)
+    return REGEXS.CLIENT.DATASTORE.test(segment.name)
   }
 }
 

lib/spans/streaming-span-event.js

@@ -10,17 +10,7 @@ const { truncate } = require('../util/byte-limit')
 const Config = require('../config')
 
 const { DESTINATIONS } = require('../config/attribute-filter')
-
-const HTTP_LIBRARY = 'http'
-const CLIENT_KIND = 'client'
-const CATEGORIES = {
-  HTTP: 'http',
-  DATASTORE: 'datastore',
-  GENERIC: 'generic'
-}
-
-const EXTERNAL_REGEX = /^(?:Truncated\/)?External\//
-const DATASTORE_REGEX = /^(?:Truncated\/)?Datastore\//
+const { addSpanKind, HTTP_LIBRARY, REGEXS, SPAN_KIND, CATEGORIES } = require('./helpers')
 
 /**
  * Specialized span event class for use with infinite streaming.
@@ -59,7 +49,7 @@ class StreamingSpanEvent {
   }
 
   /**
-   * Add a key/value pair to the Span's instrinisics collection.
+   * Add a key/value pair to the Span's intrinsics collection.
    *
    * @param {string} key Name of the attribute to be stored.
    * @param {string|boolean|number} value Value of the attribute to be stored.
@@ -68,6 +58,10 @@ class StreamingSpanEvent {
     this._intrinsicAttributes.addAttribute(key, value)
   }
 
+  getIntrinsicAttributes() {
+    return this._intrinsicAttributes
+  }
+
   /**
    * Add a key/value pair to the Span's custom/user attributes collection.
    *
@@ -169,6 +163,7 @@ class StreamingSpanEvent {
     // Timestamp in milliseconds, duration in seconds. Yay consistency!
     span.addIntrinsicAttribute('timestamp', segment.timer.start)
     span.addIntrinsicAttribute('duration', segment.timer.getDurationInMillis() / 1000)
+    addSpanKind({ segment, span })
 
     return span
   }
@@ -196,7 +191,7 @@ class StreamingHttpSpanEvent extends StreamingSpanEvent {
 
     this.addIntrinsicAttribute('category', CATEGORIES.HTTP)
     this.addIntrinsicAttribute('component', library || HTTP_LIBRARY)
-    this.addIntrinsicAttribute('span.kind', CLIENT_KIND)
+    this.addIntrinsicAttribute('span.kind', SPAN_KIND.CLIENT)
 
     if (url) {
       this.addAgentAttribute('http.url', url)
@@ -213,7 +208,7 @@ class StreamingHttpSpanEvent extends StreamingSpanEvent {
   }
 
   static isHttpSegment(segment) {
-    return EXTERNAL_REGEX.test(segment.name)
+    return REGEXS.CLIENT.EXTERNAL.test(segment.name)
   }
 }
 
@@ -248,7 +243,7 @@ class StreamingDatastoreSpanEvent extends StreamingSpanEvent {
     super(traceId, agentAttrs, customAttributes)
 
     this.addIntrinsicAttribute('category', CATEGORIES.DATASTORE)
-    this.addIntrinsicAttribute('span.kind', CLIENT_KIND)
+    this.addIntrinsicAttribute('span.kind', SPAN_KIND.CLIENT)
 
     if (product) {
       this.addIntrinsicAttribute('component', product)
@@ -288,7 +283,7 @@ class StreamingDatastoreSpanEvent extends StreamingSpanEvent {
   /* eslint-enable camelcase */
 
   static isDatastoreSegment(segment) {
-    return DATASTORE_REGEX.test(segment.name)
+    return REGEXS.CLIENT.DATASTORE.test(segment.name)
   }
 }
 

lib/transaction/trace/segment.js

@@ -64,6 +64,9 @@ function TraceSegment({ id, config, name, collect, parentId, root, isRoot = fals
   this.state = STATE.EXTERNAL
   this.async = true
   this.ignore = false
+  // only use to specify spanKind on segments created with `api.startBackgroundTransaction` and `api.startWebTransaction`
+  // we typically determine the span kind based on the segment name
+  this.spanKind = null
 }
 
 TraceSegment.prototype.getSpanContext = function getSpanContext() {

test/lib/custom-assertions/assert-span-kind.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+/**
+ * Gets all spans created during transaction and iterates over to assert the span kind
+ * for each segment in the transaction matches the provided expected `segments`.
+ *
+ * @example
+ * assertSpanKind({
+ *   agent,
+ *   segments: [{ name: 'expectedSegment', kind: 'server' }]
+ * })
+ *
+ * @param {object} params to function
+ * @param {Agent} params.agent instance of agent
+ * @param {segments} params.segments collection of span names and their respective span kind
+ * @param {object} params.assert assertion library
+ */
+module.exports = function assertSpanKind({ agent, segments, assert = require('node:assert') }) {
+  const spans = agent.spanEventAggregator.getEvents()
+  if (segments) {
+    segments.forEach((segment) => {
+      const span = spans.find((s) => s.intrinsics.name === segment.name)
+      if (!span) {
+        assert.fail(`Could not find span: ${segment.name}`)
+      }
+      assert.equal(span.intrinsics['span.kind'], segment.kind)
+    })
+  } else {
+    assert.fail('Custom assertion must either pass in an array of span kinds or a collection of segment names to span kind')
+  }
+}

test/unit/api/api-start-background-transaction.test.js

@@ -8,7 +8,7 @@ const test = require('node:test')
 const assert = require('node:assert')
 const API = require('../../../api')
 const helper = require('../../lib/agent_helper')
-const { assertCLMAttrs } = require('../../lib/custom-assertions')
+const { assertCLMAttrs, assertSpanKind } = require('../../lib/custom-assertions')
 
 function nested({ api }) {
   api.startBackgroundTransaction('nested', function nestedHandler() {})
@@ -72,6 +72,7 @@ test('Agent API - startBackgroundTransaction', async (t) => {
     })
 
     assert.ok(!transaction.isActive())
+    assertSpanKind({ agent, segments: [{ name: transaction.name, kind: 'server' }] })
 
     end()
   })

test/unit/api/api-start-web-transaction.test.js

@@ -8,7 +8,7 @@ const test = require('node:test')
 const assert = require('node:assert')
 const API = require('../../../api')
 const helper = require('../../lib/agent_helper')
-const { assertCLMAttrs } = require('../../lib/custom-assertions')
+const { assertCLMAttrs, assertSpanKind } = require('../../lib/custom-assertions')
 function nested({ api }) {
   api.startWebTransaction('nested', function nestedHandler() {})
 }
@@ -70,6 +70,7 @@ test('Agent API - startWebTransaction', async (t) => {
     })
 
     assert.ok(!transaction.isActive())
+    assertSpanKind({ agent, segments: [{ name: transaction.name, kind: 'server' }] })
     end()
   })
 

test/unit/spans/span-event.test.js

@@ -93,7 +93,7 @@ test('fromSegment()', async (t) => {
         assert.ok(span.intrinsics.duration >= 0.03 && span.intrinsics.duration <= 0.3)
 
         // Generic should not have 'span.kind' or 'component'
-        assert.equal(span.intrinsics['span.kind'], null)
+        assert.equal(span.intrinsics['span.kind'], 'internal')
         assert.equal(span.intrinsics.component, null)
 
         assert.ok(span.customAttributes)

test/unit/spans/streaming-span-event.test.js

@@ -85,13 +85,13 @@ test('fromSegment()', async (t) => {
         assert.deepEqual(span._intrinsicAttributes.priority, { [INT_TYPE]: 42 })
         assert.deepEqual(span._intrinsicAttributes.name, { [STRING_TYPE]: 'timers.setTimeout' })
         assert.deepEqual(span._intrinsicAttributes.timestamp, { [INT_TYPE]: segment.timer.start })
+        assert.deepEqual(span._intrinsicAttributes['span.kind'], { [STRING_TYPE]: 'internal' })
 
         assert.ok(span._intrinsicAttributes.duration)
         assert.ok(span._intrinsicAttributes.duration[DOUBLE_TYPE])
 
         // Generic should not have 'span.kind' or 'component'
         const hasIntrinsic = Object.hasOwnProperty.bind(span._intrinsicAttributes)
-        assert.ok(!hasIntrinsic('span.kind'))
         assert.ok(!hasIntrinsic('component'))
 
         const customAttributes = span._customAttributes