feat: Updated Context class to ensure bi-directional context propagation with opentelemetry bridge (#2962)

Author: bizob2828

lib/context-manager/context.js

@@ -5,6 +5,7 @@
 
 'use strict'
 const { otelSynthesis } = require('../symbols')
+const FakeSpan = require('../otel/fake-span')
 
 module.exports = class Context {
   constructor(transaction, segment, parentContext) {
@@ -21,12 +22,41 @@ module.exports = class Context {
     return this._transaction
   }
 
+  /**
+   * Constructs a new context from segment about to be bound to context manager
+   * along with the current transaction.
+   *
+   * If agent is in otel bridge mode it will also bind a FakeSpan to the otel ctx.
+   *
+   * @param {object} params to function
+   * @param {TraceSegment} params.segment segment to bind to context
+   * @param {Transaction} params.transaction active transaction
+   * @returns {Context} a newly constructed context
+   */
   enterSegment({ segment, transaction = this._transaction }) {
-    return new this.constructor(transaction, segment)
+    if (transaction?.agent?.otelSpanKey) {
+      this._otelCtx.set(transaction.agent.otelSpanKey, new FakeSpan(segment, transaction))
+    }
+    return new this.constructor(transaction, segment, this._otelCtx)
   }
 
+  /**
+   * Constructs a new context from transaction about to be bound to context manager.
+   * It uses the trace root segment as the segment in context.
+   *
+   * If agent is in otel bridge mode it will also bind a FakeSpan to the otel ctx.
+   *
+   * @param {object} params to function
+   * @param {TraceSegment} params.segment transaction trace root segment
+   * @param {Transaction} params.transaction transaction to bind to context
+   * @param transaction
+   * @returns {Context} a newly constructed context
+   */
   enterTransaction(transaction) {
-    return new this.constructor(transaction, transaction.trace.root)
+    if (transaction?.agent?.otelSpanKey) {
+      this._otelCtx.set(transaction.agent.otelSpanKey, new FakeSpan(transaction.trace.root, transaction))
+    }
+    return new this.constructor(transaction, transaction.trace.root, this._otelCtx)
   }
 
   /**

lib/otel/fake-span.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+/**
+ * In order to be able to return the appropriate span context
+ * wihtin otel bridge. We have to create fake spans for new relic
+ * segments.  The only thing needed is a method for `spanContext`
+ * which should return the spanId(segment id) and traceId(transaction trace id).
+ * We hardcode traceFlags to 1.
+ */
+module.exports = class FakeSpan {
+  constructor(segment, transaction) {
+    this.segment = segment
+    this.transaction = transaction
+  }
+
+  spanContext() {
+    return {
+      spanId: this.segment.id,
+      traceId: this.transaction.traceId,
+      traceFlags: 1
+    }
+  }
+}

lib/otel/segments/utils.js

@@ -5,12 +5,22 @@
 
 'use strict'
 
+/**
+ * Accepts trace context payload if span has a parent. It will use the
+ * span context to extract the traceId, traceFlags and trace state.
+ *
+ * @param {object} params to function
+ * @param {Transaction} params.transaction active transaction
+ * @param {object} params.otelSpan active span
+ * @param {string} params.transport indicator of type of span(http, kafkajs, rabbitmq, etc)
+ */
 function propagateTraceContext({ transaction, otelSpan, transport }) {
   const spanContext = otelSpan.spanContext()
+  const parentSpanId = otelSpan?.parentSpanId || otelSpan?.parentSpanContext?.spanId
 
-  if (otelSpan.parentSpanId) {
+  if (parentSpanId) {
     // prefix traceFlags with 0 as it is stored as a parsed int on spanContext
-    const traceparent = `00-${spanContext.traceId}-${otelSpan.parentSpanId}-0${spanContext.traceFlags}`
+    const traceparent = `00-${spanContext.traceId}-${parentSpanId}-0${spanContext.traceFlags}`
     transaction.acceptTraceContextPayload(traceparent, spanContext?.traceState?.state, transport)
   }
 }

lib/otel/setup.js

@@ -14,6 +14,7 @@ const createOtelLogger = require('./logger')
 const TracePropagator = require('./trace-propagator')
 
 const { ATTR_SERVICE_NAME } = require('./constants')
+const interceptSpanKey = require('./span-key-interceptor')
 
 module.exports = function setupOtel(agent, logger = defaultLogger) {
   if (agent.config.feature_flag.opentelemetry_bridge !== true) {
@@ -35,6 +36,7 @@ module.exports = function setupOtel(agent, logger = defaultLogger) {
     }
   }))
 
+  interceptSpanKey(agent)
   opentelemetry.context.setGlobalContextManager(new ContextManager(agent))
   opentelemetry.propagation.setGlobalPropagator(new TracePropagator(agent))
 

lib/otel/span-key-interceptor.js

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const otelApi = require('@opentelemetry/api')
+
+/**
+ * Called before setting up the otel bridge ContextManager.
+ * This creates a fake context and uses the otel api to set a span.
+ * By creating a fake `setValue` when it will give us the symbol used for enqueueing spans to the context.
+ * This is assigned as a key on the agent.
+ * We will use this key to enqueue our FakeSpan when we enter a segment or transaction so that when using otel API it will return the appropriate traceId and spanId.
+ *
+ * @param {Agent} agent instance
+ */
+module.exports = function interceptSpanKey(agent) {
+  const fakeCtx = {
+    spanKey: null,
+    setValue(key) {
+      this.spanKey = key
+    }
+  }
+
+  const fakeSpan = {}
+  otelApi.trace.setSpan(fakeCtx, fakeSpan)
+  agent.otelSpanKey = fakeCtx.spanKey
+}

lib/otel/trace-propagator.js

@@ -32,7 +32,6 @@ class TraceState {
  *     (01 = sampled, 00 = not sampled).
  *     for example: '{version}-{traceId}-{spanId}-{sampleDecision}'
  *     For more information see {@link https://www.w3.org/TR/trace-context/}
- * @param traceParen
  */
 function parseTraceParent(traceParent) {
   const match = TRACE_PARENT_REGEX.exec(traceParent)

test/unit/lib/otel/fake-span.test.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const test = require('node:test')
+const assert = require('node:assert')
+const helper = require('#testlib/agent_helper.js')
+const FakeSpan = require('#agentlib/otel/fake-span.js')
+
+test('should create a fake span from segment and transaction', (t) => {
+  const agent = helper.loadMockedAgent()
+  t.after(() => {
+    helper.unloadAgent(agent)
+  })
+
+  const segment = { id: 'id' }
+  const tx = { traceId: 'traceId' }
+  const span = new FakeSpan(segment, tx)
+  const spanCtx = span.spanContext()
+  assert.deepEqual(spanCtx, {
+    spanId: 'id',
+    traceId: 'traceId',
+    traceFlags: 1
+  })
+})

test/unit/lib/otel/segment-utils.test.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const test = require('node:test')
+const assert = require('node:assert')
+const sinon = require('sinon')
+const helper = require('#testlib/agent_helper.js')
+const { propagateTraceContext } = require('#agentlib/otel/segments/utils.js')
+
+test.beforeEach((ctx) => {
+  const agent = helper.loadMockedAgent()
+  const transaction = {
+    acceptTraceContextPayload: sinon.stub()
+  }
+  ctx.nr = {
+    agent,
+    transaction
+  }
+})
+
+test.afterEach((ctx) => {
+  helper.unloadAgent(ctx.nr.agent)
+})
+
+test('should accept traceparent when span has parentSpanId', (t) => {
+  const { transaction } = t.nr
+  const otelSpan = {
+    parentSpanId: 'parentId',
+    spanContext() {
+      return {
+        traceId: 'traceId',
+        traceFlags: 1,
+        traceState: { state: 'state' }
+      }
+    }
+  }
+  propagateTraceContext({ transaction, otelSpan, transport: 'transport' })
+  assert.equal(transaction.acceptTraceContextPayload.callCount, 1)
+  assert.deepEqual(transaction.acceptTraceContextPayload.args[0], [
+    '00-traceId-parentId-01', 'state', 'transport'
+  ])
+})
+
+test('should accept traceparent when span has parentSpanContext.spanId', (t) => {
+  const { transaction } = t.nr
+  const otelSpan = {
+    parentSpanContext: { spanId: 'parentId' },
+    spanContext() {
+      return {
+        traceId: 'traceId',
+        traceFlags: 1,
+        traceState: { state: 'state' }
+      }
+    }
+  }
+  propagateTraceContext({ transaction, otelSpan, transport: 'transport' })
+  assert.equal(transaction.acceptTraceContextPayload.callCount, 1)
+  assert.deepEqual(transaction.acceptTraceContextPayload.args[0], [
+    '00-traceId-parentId-01', 'state', 'transport'
+  ])
+})
+
+test('should not accept traceparent when span has not parent span id', (t) => {
+  const { transaction } = t.nr
+  const otelSpan = { spanContext() { return {} } }
+  propagateTraceContext({ transaction, otelSpan, transport: 'transport' })
+  assert.equal(transaction.acceptTraceContextPayload.callCount, 0)
+})

test/unit/lib/otel/setup.test.js

@@ -49,3 +49,10 @@ test('should not create provider when `feature_flag.opentelemetry_bridge` is fal
   assert.equal(provider, null)
   assert.equal(loggerMock.warn.args[0][0], '`feature_flag.opentelemetry_bridge` is not enabled, skipping setup of opentelemetry-bridge')
 })
+
+test('should assign span key to agent', (t) => {
+  const { agent, loggerMock } = t.nr
+  agent.config.feature_flag.opentelemetry_bridge = true
+  otelSetup(agent, loggerMock)
+  assert.ok(agent.otelSpanKey)
+})

test/versioned/otel-bridge/span.test.js

@@ -67,9 +67,10 @@ test.afterEach((ctx) => {
 
 test('mix internal and NR span tests', (t, end) => {
   const { agent, api, tracer } = t.nr
-  function main(mainSegment) {
+  function main(mainSegment, tx) {
     tracer.startActiveSpan('hi', (span) => {
       const segment = agent.tracer.getSegment()
+      assert.equal(tx.traceId, span.spanContext().traceId)
       assert.equal(segment.name, span.name)
       assert.equal(segment.parentId, mainSegment.id)
       span.end()
@@ -81,6 +82,7 @@ test('mix internal and NR span tests', (t, end) => {
       const parentSegment = agent.tracer.getSegment()
       tracer.startActiveSpan('bye', (span) => {
         const segment = agent.tracer.getSegment()
+        assert.equal(tx.traceId, span.spanContext().traceId)
         assert.equal(segment.name, span.name)
         assert.equal(segment.parentId, parentSegment.id)
         span.end()
@@ -93,7 +95,8 @@ test('mix internal and NR span tests', (t, end) => {
     tx.name = 'otel-example-tx'
     tracer.startActiveSpan('main', (span) => {
       const segment = agent.tracer.getSegment()
-      main(segment)
+      assert.equal(tx.traceId, span.spanContext().traceId)
+      main(segment, tx)
       span.end()
       assert.equal(span[otelSynthesis], undefined)
       assert.equal(segment.name, span.name)
@@ -121,6 +124,7 @@ test('client span(http) is bridge accordingly', (t, end) => {
     tracer.startActiveSpan('http-outbound', { kind: otel.SpanKind.CLIENT, attributes: { [ATTR_HTTP_HOST]: 'newrelic.com', [ATTR_HTTP_METHOD]: 'GET' } }, (span) => {
       const segment = agent.tracer.getSegment()
       assert.equal(segment.name, 'External/newrelic.com')
+      assert.equal(tx.traceId, span.spanContext().traceId)
       span.end()
       const duration = hrTimeToMilliseconds(span.duration)
       assert.equal(duration, segment.getDurationInMillis())
@@ -152,6 +156,7 @@ test('client span(db) is bridge accordingly(statement test)', (t, end) => {
     tracer.startActiveSpan('db-test', { kind: otel.SpanKind.CLIENT, attributes }, (span) => {
       const segment = agent.tracer.getSegment()
       assert.equal(segment.name, 'Datastore/statement/postgresql/test/select')
+      assert.equal(tx.traceId, span.spanContext().traceId)
       span.end()
       const duration = hrTimeToMilliseconds(span.duration)
       assert.equal(duration, segment.getDurationInMillis())
@@ -196,6 +201,7 @@ test('client span(db) is bridged accordingly(operation test)', (t, end) => {
     tracer.startActiveSpan('db-test', { kind: otel.SpanKind.CLIENT, attributes }, (span) => {
       const segment = agent.tracer.getSegment()
       assert.equal(segment.name, 'Datastore/operation/redis/hset')
+      assert.equal(tx.traceId, span.spanContext().traceId)
       span.end()
       const duration = hrTimeToMilliseconds(span.duration)
       assert.equal(duration, segment.getDurationInMillis())
@@ -240,6 +246,7 @@ test('server span is bridged accordingly', (t, end) => {
 
   tracer.startActiveSpan('http-test', { kind: otel.SpanKind.SERVER, attributes }, (span) => {
     const tx = agent.getTransaction()
+    assert.equal(tx.traceId, span.spanContext().traceId)
     span.setAttribute(ATTR_HTTP_STATUS_CODE, 200)
     span.setAttribute(ATTR_HTTP_STATUS_TEXT, 'OK')
     span.end()
@@ -294,6 +301,7 @@ test('server span(rpc) is bridged accordingly', (t, end) => {
   tracer.startActiveSpan('http-test', { kind: otel.SpanKind.SERVER, attributes }, (span) => {
     span.setAttribute(ATTR_GRPC_STATUS_CODE, 0)
     const tx = agent.getTransaction()
+    assert.equal(tx.traceId, span.spanContext().traceId)
     span.end()
     assert.ok(!tx.isDistributedTrace)
     const segment = agent.tracer.getSegment()
@@ -344,6 +352,7 @@ test('server span(fallback) is bridged accordingly', (t, end) => {
   const expectedHost = agent.config.getHostnameSafe('127.0.0.1')
   tracer.startActiveSpan('http-test', { kind: otel.SpanKind.SERVER, attributes }, (span) => {
     const tx = agent.getTransaction()
+    assert.equal(tx.traceId, span.spanContext().traceId)
     span.end()
     assert.ok(!tx.isDistributedTrace)
     const segment = agent.tracer.getSegment()
@@ -394,6 +403,7 @@ test('producer span is bridged accordingly', (t, end) => {
     const expectedHost = agent.config.getHostnameSafe('localhost')
     tracer.startActiveSpan('prod-test', { kind: otel.SpanKind.PRODUCER, attributes }, (span) => {
       const segment = agent.tracer.getSegment()
+      assert.equal(tx.traceId, span.spanContext().traceId)
       assert.equal(segment.name, 'MessageBroker/messaging-lib/queue/Produce/Named/test-queue')
       span.end()
       const duration = hrTimeToMilliseconds(span.duration)
@@ -434,6 +444,7 @@ test('consumer span is bridged correctly', (t, end) => {
     const tx = agent.getTransaction()
     assert.ok(!tx.isDistributedTrace)
     const segment = agent.tracer.getSegment()
+    assert.equal(tx.traceId, span.spanContext().traceId)
     span.end()
     const duration = hrTimeToMilliseconds(span.duration)
     assert.equal(duration, segment.getDurationInMillis())