feat: Added opentelemetry bridge instrumentation that adds a context manager, and processor to handle synthesizing segments and time slice metrics. (#2906)

Author: bizob2828

THIRD_PARTY_NOTICES.md

@@ -32,3 +32,10 @@ Any prerelease flags can be enabled or disabled in your agent config by adding a
 * Configuration: `{ feature_flag: { kafkajs_instrumentation: true|false }}`
 * Environment Variable: `NEW_RELIC_FEATURE_FLAG_KAFKAJS_INSTRUMENTATION`
 * Description: Enables instrumentation of `kafkajs`. 
+
+#### otel_instrumentation
+* Enabled by default: `false`
+* Configuration: `{ feature_flag: { otel_instrumentation: true|false }}`
+* Environment Variable: `NEW_RELIC_FEATURE_FLAG_OTEL_INSTRUMENTATION`
+* Description: Enables the creation of Transaction Trace segments and time slices metrics from opentelemetry spans. This will help drive New Relic UI experience for opentelemetry spans. 
+* **WARNING**: This is not feature complete and is not intended to be enabled yet.

documentation/feature-flags.md

@@ -4,11 +4,13 @@
  */
 
 'use strict'
+const { otelSynthesis } = require('../symbols')
 
 module.exports = class Context {
-  constructor(transaction, segment) {
+  constructor(transaction, segment, parentContext) {
     this._transaction = transaction
     this._segment = segment
+    this._otelCtx = parentContext ? new Map(parentContext) : new Map()
   }
 
   get segment() {
@@ -19,11 +21,58 @@ module.exports = class Context {
     return this._transaction
   }
 
-  enterSegment({ segment, transaction = this.transaction }) {
+  enterSegment({ segment, transaction = this._transaction }) {
     return new this.constructor(transaction, segment)
   }
 
   enterTransaction(transaction) {
     return new this.constructor(transaction, transaction.trace.root)
   }
+
+  /**
+   * Required for bridging OTEL data into the agent.
+   *
+   * @param {string} key Stored entity name to retrieve.
+   *
+   * @returns {*} The stored value.
+   */
+  getValue(key) {
+    return this._otelCtx.get(key)
+  }
+
+  /**
+   * Required for bridging OTEL data into the agent.
+   *
+   * @param {string} key Name for stored value.
+   * @param {*} value Value to store.
+   *
+   * @returns {object} The context manager object.
+   */
+  setValue(key, value) {
+    let ctx
+
+    if (value[otelSynthesis] && value[otelSynthesis].segment && value[otelSynthesis].transaction) {
+      const { segment, transaction } = value[otelSynthesis]
+      segment.start()
+      ctx = new this.constructor(transaction, segment, this._otelCtx)
+    } else {
+      ctx = new this.constructor(this._transaction, this._segment, this._otelCtx)
+    }
+
+    ctx._otelCtx.set(key, value)
+    return ctx
+  }
+
+  /**
+   * Required for bridging OTEL data into the agent.
+   *
+   * @param {string} key Named value to remove from the store.
+   *
+   * @returns {object} The context manager object.
+   */
+  deleteValue(key) {
+    const ctx = new this.constructor(this._transaction, this._segment, this._otelCtx)
+    ctx._otelCtx.delete(key)
+    return ctx
+  }
 }

lib/context-manager/context.js

@@ -10,7 +10,7 @@ exports.prerelease = {
   // internal_test_only is used for testing our feature flag implementation.
   // It is not used to gate any features.
   internal_test_only: false,
-
+  opentelemetry_bridge: false,
   promise_segments: false,
   reverse_naming_rules: false,
   unresolved_promise_cleanup: true,

lib/feature_flags.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2024 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+/**
+ * @see https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.ContextManager.html
+ */
+class ContextManager {
+  #ctxMgr
+
+  constructor(agent) {
+    this.#ctxMgr = agent.tracer._contextManager
+  }
+
+  active() {
+    return this.#ctxMgr.getContext()
+  }
+
+  bind(context, target) {
+    return boundContext.bind(this)
+
+    function boundContext(...args) {
+      return this.with(context, target, this, ...args)
+    }
+  }
+
+  /**
+   * Runs the callback within the provided context, optionally
+   * bound with a provided `this`.
+   *
+   * @param context
+   * @param callback
+   * @param thisRef
+   * @param args
+   */
+  with(context, callback, thisRef, ...args) {
+    return this.#ctxMgr.runInContext(context, callback, thisRef, args)
+  }
+
+  enable() {
+    return this
+  }
+
+  disable() {
+    return this
+  }
+}
+
+module.exports = ContextManager

lib/otel/context-manager.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const { diag, DiagLogLevel } = require('@opentelemetry/api')
+
+// Map New Relic log levels to OTel log levels
+const logLevels = {
+  trace: 'VERBOSE',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARN',
+  error: 'ERROR',
+  fatal: 'ERROR'
+}
+
+module.exports = function createOtelLogger(logger, config) {
+  // enable exporter logging
+  // OTel API calls "verbose" what we call "trace".
+  logger.verbose = logger.trace
+  const logLevel = DiagLogLevel[logLevels[config.logging.level]]
+  diag.setLogger(logger, logLevel)
+}

lib/otel/logger.js

@@ -6,13 +6,15 @@
 'use strict'
 const NAMES = require('../../metrics/names')
 const { SEMATTRS_HTTP_HOST } = require('@opentelemetry/semantic-conventions')
+const recordExternal = require('../../metrics/recorders/http_external')
 
 module.exports = function createHttpExternalSegment(agent, otelSpan) {
   const context = agent.tracer.getContext()
   const host = otelSpan.attributes[SEMATTRS_HTTP_HOST] || 'Unknown'
   const name = NAMES.EXTERNAL.PREFIX + host
   const segment = agent.tracer.createSegment({
     name,
+    recorder: recordExternal(host, 'http'),
     parent: context.segment,
     transaction: context.transaction
   })

lib/otel/segments/http-external.js

@@ -4,13 +4,15 @@
  */
 
 'use strict'
+const customRecorder = require('../../metrics/recorders/custom')
 
 module.exports = function createInternalSegment(agent, otelSpan) {
   const context = agent.tracer.getContext()
-  const name = `Custom/${otelSpan.name}`
+  const name = otelSpan.name
   const segment = agent.tracer.createSegment({
     name,
     parent: context.segment,
+    recorder: customRecorder,
     transaction: context.transaction
   })
   return { segment, transaction: context.transaction }

lib/otel/segments/internal.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base')
+const { Resource } = require('@opentelemetry/resources')
+const { SEMRESATTRS_SERVICE_NAME } = require('@opentelemetry/semantic-conventions')
+const NrSpanProcessor = require('./span-processor')
+const ContextManager = require('./context-manager')
+const defaultLogger = require('../logger').child({ component: 'opentelemetry-bridge' })
+const createOtelLogger = require('./logger')
+
+module.exports = function setupOtel(agent, logger = defaultLogger) {
+  if (agent.config.feature_flag.opentelemetry_bridge !== true) {
+    logger.warn(
+      '`feature_flag.opentelemetry_bridge` is not enabled, skipping setup of opentelemetry-bridge'
+    )
+    return
+  }
+
+  createOtelLogger(logger, agent.config)
+
+  const provider = new BasicTracerProvider({
+    spanProcessors: [new NrSpanProcessor(agent)],
+    resource: new Resource({
+      [SEMRESATTRS_SERVICE_NAME]: agent.config.applications()[0]
+    }),
+    generalLimits: {
+      attributeValueLengthLimit: 4095
+    }
+
+  })
+  provider.register({
+    contextManager: new ContextManager(agent)
+    // propagator: // todo: https://github.com/newrelic/node-newrelic/issues/2662
+  })
+
+  agent.metrics
+    .getOrCreateMetric('Supportability/Nodejs/OpenTelemetryBridge/Setup')
+    .incrementCallCount()
+
+  return provider
+}

lib/otel/setup.js

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const SegmentSynthesizer = require('./segment-synthesis')
+const { otelSynthesis } = require('../symbols')
+const { hrTimeToMilliseconds } = require('@opentelemetry/core')
+
+module.exports = class NrSpanProcessor {
+  constructor(agent) {
+    this.agent = agent
+    this.synthesizer = new SegmentSynthesizer(agent)
+    this.tracer = agent.tracer
+  }
+
+  /**
+   * Synthesize segment at start of span and assign to a symbol
+   * that will be removed in `onEnd` once the correspondig
+   * segment is read.
+   * @param span
+   */
+  onStart(span) {
+    span[otelSynthesis] = this.synthesizer.synthesize(span)
+  }
+
+  /**
+   * Update the segment duration from span and reconcile
+   * any attributes that were added after the start
+   * @param span
+   */
+  onEnd(span) {
+    this.updateDuration(span)
+    // TODO: add attributes from span that did not exist at start
+  }
+
+  updateDuration(span) {
+    if (span[otelSynthesis] && span[otelSynthesis].segment) {
+      const { segment } = span[otelSynthesis]
+      segment.touch()
+      const duration = hrTimeToMilliseconds(span.duration)
+      segment.overwriteDurationInMillis(duration)
+      delete span[otelSynthesis]
+    }
+  }
+}

lib/otel/span-processor.js

@@ -22,6 +22,7 @@ let pkgsToHook = []
 const NAMES = require('./metrics/names')
 const symbols = require('./symbols')
 const { unsubscribe } = require('./instrumentation/undici')
+const setupOtel = require('./otel/setup')
 
 const CORE_INSTRUMENTATION = {
   child_process: {
@@ -393,6 +394,7 @@ const shimmer = (module.exports = {
   bootstrapInstrumentation: function bootstrapInstrumentation(agent) {
     shimmer.registerCoreInstrumentation(agent)
     shimmer.registerThirdPartyInstrumentation(agent)
+    setupOtel(agent)
   },
 
   registerInstrumentation: function registerInstrumentation(opts) {

lib/shimmer.js

@@ -26,6 +26,7 @@ module.exports = {
   openAiApiKey: Symbol('openAiApiKey'),
   parentSegment: Symbol('parentSegment'),
   langchainRunId: Symbol('runId'),
+  otelSynthesis: Symbol('otelSynthesis'),
   prismaConnection: Symbol('prismaConnection'),
   prismaModelCall: Symbol('modelCall'),
   redisClientOpts: Symbol('clientOptions'),

lib/symbols.js

@@ -199,6 +199,9 @@
     "@grpc/proto-loader": "^0.7.5",
     "@newrelic/security-agent": "^2.2.0",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.0",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/semantic-conventions": "^1.27.0",
     "@tyriar/fibonacci-heap": "^2.0.7",
     "concat-stream": "^2.0.0",
@@ -226,7 +229,6 @@
     "@newrelic/newrelic-oss-cli": "^0.1.2",
     "@newrelic/test-utilities": "^9.1.0",
     "@octokit/rest": "^18.0.15",
-    "@opentelemetry/sdk-trace-base": "^1.27.0",
     "@slack/bolt": "^3.7.0",
     "@smithy/eventstream-codec": "^2.2.0",
     "@smithy/util-utf8": "^2.3.0",

package.json

@@ -24,6 +24,7 @@ const used = [
   'legacy_context_manager',
   'native_metrics',
   'new_promise_tracking',
+  'opentelemetry_bridge',
   'promise_segments',
   'protocol_17',
   'serverless_mode',