refactor: Refactor memcached instrumentation to subscribe to events emitted (#3849)

Author: amychisholm03

lib/instrumentation/memcached.js

@@ -19,7 +19,6 @@ module.exports = function instrumentations() {
     fastify: { type: InstrumentationDescriptor.TYPE_WEB_FRAMEWORK },
     kafkajs: { type: InstrumentationDescriptor.TYPE_MESSAGE },
     koa: { module: './instrumentation/koa' },
-    memcached: { type: InstrumentationDescriptor.TYPE_DATASTORE },
     mongodb: { type: InstrumentationDescriptor.TYPE_DATASTORE },
     next: { module: './instrumentation/nextjs' },
     restify: { type: InstrumentationDescriptor.TYPE_WEB_FRAMEWORK },

lib/instrumentations.js

@@ -22,6 +22,7 @@ const subscribers = {
   ...require('./subscribers/langchain/config'),
   ...require('./subscribers/langgraph/config'),
   ...require('./subscribers/mcp-sdk/config'),
+  ...require('./subscribers/memcached/config'),
   ...require('./subscribers/mysql/config'),
   ...require('./subscribers/mysql2/config'),
   ...require('./subscribers/nestjs/config'),

lib/subscriber-configs.js

@@ -84,6 +84,16 @@ module.exports = {
 }
 ```
 
+#### Function Query
+
+| Query type                          | Use when                                                                           |
+| ----------------------------------- | ---------------------------------------------------------------------------------- |
+| `expressionName`                  | Function expression assigned to a variable/property (`x.y = function name() {}`) |
+| `functionName`                    | Standalone function declaration (`function foo() {}`)                            |
+| `className` + `methodName`      | Class method (`class Foo { bar() {} }`)                                          |
+| `methodName` alone                | Any method with that name across all classes                                       |
+| `moduleName` + `expressionName` | Disambiguate by the object it's assigned to                                        |
+
 ### Creating the Subscribers
 
 Now that you have the config specified for the function that you are instrumenting, you'll then need to create a subscriber for it. All subscribers should at least inherit from the base [`Subscriber`](./base.js) with the exception of subscribers that do not rely on `orchestrion` to create their tracing channels (they inherit from the `node:diagnostics_channel` `Subscriber` in [`dc-base.js`](./dc-base.js)).

lib/subscribers/README.md

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const DbOperationSubscriber = require('../db-operation')
+const stringify = require('json-stringify-safe')
+
+module.exports = class CommandSubscriber extends DbOperationSubscriber {
+  constructor({ agent, logger }) {
+    super({ agent, logger, channelName: 'nr_command', packageName: 'memcached', system: 'Memcache' })
+    this.events = ['end']
+  }
+
+  handler(data, ctx) {
+    const { arguments: args, self: client } = data
+    // The `command` method takes two arguments: a query generator and a server
+    // address. The query generator returns a simple object describing the
+    // memcached call. The server parameter is only provided for multi-calls.
+    // When not provided, it can be derived from the key being interacted with.
+    const [queryCompiler, server] = args
+    const metacall = queryCompiler()
+    this.parameters = this.#getInstanceParameters({ keys: this.#wrapKeys(metacall), metacall, server, client })
+    this.operation = metacall.type || 'Unknown'
+    const newCtx = super.handler(data, ctx)
+    metacall.callback = this.agent.tracer.bindFunction(metacall.callback, newCtx, true)
+    args[0] = function rewrapped() {
+      // we wrap the queryCompiler function to return the
+      // updated `metacall` object with our callback
+      return metacall
+    }
+    return newCtx
+  }
+
+  #getInstanceParameters({ keys, metacall, server, client }) {
+    const parameters = {}
+    try {
+      parameters.key = stringify(keys[0])
+    } catch (err) {
+      this.logger.debug(err, 'Unable to stringify memcache key')
+      parameters.key = '<unknown>'
+    }
+
+    // Capture connection info for datastore instance metric.
+    let location = null
+    if (typeof server === 'string') {
+      location = server
+    } else if (client.HashRing && client.HashRing.get && metacall.key) {
+      location = client.HashRing.get(metacall.key)
+    }
+    if (location) {
+      location = location.split(':')
+      parameters.host = location[0]
+      parameters.port_path_or_id = location[1]
+    }
+    return parameters
+  }
+
+  #wrapKeys(metacall) {
+    if (metacall.key) {
+      return [metacall.key]
+    } else if (metacall.multi) {
+      return metacall.command.split(' ').slice(1)
+    }
+
+    return []
+  }
+}

lib/subscribers/memcached/command.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const command = {
+  path: './memcached/command.js',
+  instrumentations: [{
+    channelName: 'nr_command',
+    module: { name: 'memcached', versionRange: '>=2', filePath: 'lib/memcached.js' },
+    functionQuery: {
+      // memcached.command = function memcachedCommand(queryCompiler, server) { ... }
+      expressionName: 'command',
+      kind: 'Sync'
+    }
+  }]
+}
+
+module.exports = {
+  memcached: [
+    command
+  ]
+}