chore: Record subscriber usage metric

Author: jsumners-nr

lib/metrics/names.js

@@ -353,7 +353,8 @@ const FEATURES = {
   SOURCE_MAPS: `${SUPPORTABILITY.FEATURES}/EnableSourceMaps`,
   CERTIFICATES: SUPPORTABILITY.FEATURES + '/Certificates',
   INSTRUMENTATION: {
-    ON_REQUIRE: SUPPORTABILITY.FEATURES + '/Instrumentation/OnRequire'
+    ON_REQUIRE: SUPPORTABILITY.FEATURES + '/Instrumentation/OnRequire',
+    SUBSCRIBER_USED: SUPPORTABILITY.FEATURES + '/Instrumentation/SubscriberUsed'
   }
 }
 

lib/subscribers/base.js

@@ -7,6 +7,8 @@
 // eslint-disable-next-line n/no-unsupported-features/node-builtins
 const { tracingChannel } = require('node:diagnostics_channel')
 const cat = require('#agentlib/util/cat.js')
+const recordSupportabilityMetric = require('./record-supportability-metric.js')
+
 // Used for the `traceCallback` work.
 // This can be removed when we add true support into orchestrion
 const makeCall = (fn) => (...args) => fn.call(...args)
@@ -60,6 +62,8 @@ const ArrayPrototypeSplice = makeCall(Array.prototype.splice)
  * -1 means last argument.
  */
 class Subscriber {
+  #usageMetricRecorded = false
+
   /**
    * @param {SubscriberParams} params the subscriber constructor params
    */
@@ -211,6 +215,14 @@ class Subscriber {
    * @returns {Context} either new context or existing
    */
   handler(data, ctx) {
+    if (this.#usageMetricRecorded === false) {
+      recordSupportabilityMetric({
+        agent: this.agent,
+        moduleName: this.packageName,
+        moduleVersion: data.moduleVersion
+      })
+      this.#usageMetricRecorded = true
+    }
     return ctx
   }
 

lib/subscribers/dc-base.js

@@ -4,8 +4,11 @@
  */
 
 'use strict'
+
 // eslint-disable-next-line n/no-unsupported-features/node-builtins
 const dc = require('node:diagnostics_channel')
+const recordSupportabilityMetric = require('./record-supportability-metric.js')
+const resolvePackageVersion = require('./resolve-package-version.js')
 
 /**
  * The baseline parameters available to all subscribers.
@@ -34,6 +37,8 @@ const dc = require('node:diagnostics_channel')
  * This is the same string one would pass to the `require` function.
  */
 class Subscriber {
+  #usageMetricRecorded = false
+
   /**
    * @param {SubscriberParams} params to function
    */
@@ -46,7 +51,7 @@ class Subscriber {
 
   set channels(channels) {
     if (!Array.isArray(channels)) {
-      throw new Error('channels must be a collection of with propertiesof channel and hook')
+      throw new Error('channels must be a collection of objects with properties channel and hook')
     }
     this._channels = channels
   }
@@ -73,18 +78,43 @@ class Subscriber {
 
   subscribe() {
     for (let index = 0; index < this.channels.length; index++) {
+      const chan = this.channels[index]
       const { hook, channel } = this.channels[index]
       const boundHook = hook.bind(this)
-      dc.subscribe(channel, boundHook)
-      this.channels[index].boundHook = boundHook
+      chan.boundHook = boundHook
+      chan.eventHandler = (message, name) => {
+        this.#supportability()
+        boundHook(message, name)
+      }
+      dc.subscribe(channel, chan.eventHandler)
     }
   }
 
   unsubscribe() {
     for (let index = 0; index < this.channels.length; index++) {
-      const { channel, boundHook } = this.channels[index]
-      dc.unsubscribe(channel, boundHook)
+      const { channel, eventHandler } = this.channels[index]
+      dc.unsubscribe(channel, eventHandler)
+    }
+  }
+
+  /**
+   * Since this class subscribes to tracing channels natively published by
+   * target modules, we do not get the package metadata that Orchestrion
+   * provides in its channel events. So we have to try and find the package
+   * manifest and get the version out of it in order to record our
+   * supportability metric.
+   */
+  #supportability() {
+    if (this.#usageMetricRecorded === true) {
+      return
     }
+    const version = resolvePackageVersion(this.id)
+    recordSupportabilityMetric({
+      agent: this.agent,
+      moduleName: this.id,
+      moduleVersion: version
+    })
+    this.#usageMetricRecorded = true
   }
 }
 

lib/subscribers/record-supportability-metric.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+module.exports = recordSupportabilityMetric
+
+const {
+  FEATURES: {
+    INSTRUMENTATION: { SUBSCRIBER_USED }
+  }
+} = require('#agentlib/metrics/names.js')
+
+function recordSupportabilityMetric({
+  agent,
+  moduleName,
+  moduleVersion = 'unknown'
+} = {}) {
+  const metric = agent.metrics.getOrCreateMetric(
+    `${SUBSCRIBER_USED}/${moduleName}/${moduleVersion}`
+  )
+  metric.incrementCallCount()
+}

lib/subscribers/resolve-package-version.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const path = require('node:path')
+const defaultLogger = require('#agentlib/logger.js').child({
+  component: 'resolve-module-version'
+})
+
+module.exports = resolveModuleVersion
+
+/**
+ * Given a module name, attempt to read the version string from its
+ * associated package manifest. If the module is a built-in, or one that has
+ * been bundled with Node.js (e.g. `undici`), a package manifest will not be
+ * available. In this case, the string "unknown" will be returned.
+ *
+ * @param {string} moduleSpecifier What would be passed to `resolve()`.
+ * @param {object} [deps] Optional dependencies.
+ * @param {object} [deps.logger] Agent logger instance.
+ * @param {Function} [deps.req] Node.js require function.
+ *
+ * @returns {string} The version string from the package manifest or "unknown".
+ */
+function resolveModuleVersion(moduleSpecifier, {
+  logger = defaultLogger,
+  req = require
+} = {}) {
+  let pkgPath
+  try {
+    pkgPath = req.resolve(moduleSpecifier)
+  } catch {
+    logger.warn(
+      { moduleSpecifier },
+      'Could not resolve module path. Possibly a built-in or Node.js bundled module.'
+    )
+    return 'unknown'
+  }
+
+  const cwd = process.cwd()
+  let reachedCwd = false
+  let pkg
+  let base = path.dirname(pkgPath)
+  do {
+    try {
+      pkgPath = path.join(base, 'package.json')
+      pkg = req(pkgPath)
+    } catch {
+      base = path.resolve(path.join(base, '..'))
+      if (base === cwd) {
+        reachedCwd = true
+      } else if (reachedCwd === true) {
+        // We reached the supposed app root, attempted to load a manifest
+        // file in that location, and still couldn't find one. So we give up.
+        pkg = {}
+      }
+    }
+  } while (!pkg)
+
+  const version = pkg.version ?? 'unknown'
+  logger.trace({ moduleSpecifier, version }, 'Resolved package version.')
+  return version
+}

test/unit/lib/subscribers/base.test.js

@@ -182,6 +182,36 @@ test('should subscribe/unsubscribe to specific events on channel', (t) => {
   assert.equal(subscriber.subscriptions, null)
 })
 
+test('handler should record supportability metric on first invocation', async (t) => {
+  const plan = tspl(t, { plan: 3 })
+  const { agent, subscriber } = t.nr
+  const name = 'test-segment'
+  const metricName = 'Supportability/Features/Instrumentation/SubscriberUsed/test-package/1.0.0'
+  subscriber.enable()
+
+  const handler = subscriber.handler
+  let invocations = 0
+  subscriber.handler = (data, ctx) => {
+    invocations += 1
+    return handler.call(subscriber, data, ctx)
+  }
+
+  helper.runInTransaction(agent, () => {
+    const event = { name, moduleVersion: '1.0.0' }
+    subscriber.channel.start.runStores(event, () => {
+      const metrics = agent.metrics._metrics.unscoped
+      plan.equal(metrics[metricName].callCount, 1)
+
+      subscriber.channel.start.runStores(event, () => {
+        plan.equal(metrics[metricName].callCount, 1)
+        plan.equal(invocations, 2)
+      })
+    })
+  })
+
+  await plan.completed
+})
+
 test('should call handler in start if transaction is active and create a new segment', async (t) => {
   const plan = tspl(t, { plan: 4 })
   const { agent, subscriber } = t.nr

test/unit/lib/subscribers/dc-base.test.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const test = require('node:test')
+const dc = require('node:diagnostics_channel')
+
+const loggerMock = require('../../mocks/logger')
+const helper = require('#testlib/agent_helper.js')
+const Subscriber = require('#agentlib/subscribers/dc-base.js')
+
+test.beforeEach((ctx) => {
+  const agent = helper.loadMockedAgent()
+  const logger = loggerMock()
+  const subscriber = new Subscriber({
+    agent,
+    logger,
+    packageName: 'test-package'
+  })
+  ctx.nr = { agent, subscriber }
+})
+
+test.afterEach((ctx) => {
+  const { subscriber } = ctx.nr
+  subscriber.disable()
+  subscriber.unsubscribe()
+  helper.unloadAgent(ctx.nr.agent)
+})
+
+test('records supportability metric on first usage', (t) => {
+  t.plan(3)
+  const { agent, subscriber } = t.nr
+
+  let invocations = 0
+  const metricName = 'Supportability/Features/Instrumentation/SubscriberUsed/test-package/unknown'
+  const chan = dc.channel('test.channel')
+  subscriber.channels = [
+    { channel: 'test.channel', hook: handler }
+  ]
+  subscriber.subscribe()
+
+  chan.publish({ foo: 'foo' })
+
+  function handler () {
+    invocations += 1
+    t.assert.equal(agent.metrics._metrics.unscoped[metricName].callCount, 1)
+
+    if (invocations === 1) {
+      chan.publish({ bar: 'bar' })
+      const cachedChan = subscriber.channels[0]
+      const keys = Object.keys(cachedChan).sort()
+      t.assert.deepStrictEqual(
+        keys,
+        ['boundHook', 'channel', 'eventHandler', 'hook'],
+        'attaches required properties to cached channel'
+      )
+    }
+  }
+})