You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As of v13.2.0, we have begun to refactor our traditional instrumentation (`Shim`-based monkey-patching) to instead subscribe to events emitted by Node's [`diagnostic_channel TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). This is done through [`@apm-js-collab/tracing-hooks`](https://github.com/apm-js-collab/tracing-hooks), a helper for [`orchestrion-js`](https://github.com/apm-js-collab/orchestrion-js) which injects the relevant tracing channels into the instrumented package. We then define a `Subscriber` that listens to these channels for specific events (`asyncEnd`, `asyncStart`, `start`, `end`, and/or `error`) and record what we need from the event data and context (which is preserved through `AsyncLocalStorage`).
4
+
5
+
## How to Implement
6
+
7
+
Like `Shim`-based instrumentation, subscriber-based instrumentation largely relies on the specific way the package you're instrumenting is written. However, all packages will follow the below template/guidelines.
8
+
9
+
### Disable Shim-based Instrumentation
10
+
11
+
1. While you are testing your new instrumentation, it's important that you're not also testing the old instrumentation. However, you likely want to keep the old instrumentation around while you're refactoring for reference. The easiest way to do this is to just remove the instrumentation reference in `lib/instrumentations.js`.
12
+
2. When you are done refactoring, make sure to delete all files in `lib/instrumentation/<package_name>` (or `lib/instrumentation/<package_name>.js`), the tests in `test/unit/instrumentation/<package_name> `that rely on `Shim`-based wrapping, and the instrumentation reference in `instrumentations.js` if you haven't already.
13
+
14
+
### Instrumentation Config
15
+
16
+
Now, it is time to look at the internals of the package you're instrumenting. Again, the `Shim`-based instrumentation you're replacing should be helpful here to get the gist of the package internals.
17
+
18
+
1. Create a folder within `lib/subscribers` with the name of the package. If the package is not a new instrumentation, use the same name as the one in `test/versioned`. If it is a new instrumentation and the package name is exceptionally long or complicated or is prefixed with `@`, you may provide a shortened version (e.g. `@modelcontextprotocol/sdk `->`mcp-sdk `). Remember to name the versioned test folder with the same name (`test/versioned/<package_name|shortened_package_name>`).
19
+
2. Create a `config.js` within that folder.
20
+
3. Add a reference to the new config file in [`lib/subscriber-configs.js`](../subscriber-configs.js):
21
+
1.```javascript
22
+
...require('./subscribers/<package_name>/config')
23
+
```
24
+
4. Identify one function to start with and find where this function lives in the package i.e. the relative file path.
25
+
5. Once you have found where the function you're instrumenting is, you need to determine how it is defined in [AST](https://astexplorer.net/), so that `orchestrion` can properly wrap it. You can then add the proper instrumentation object to your `config.js`.
26
+
27
+
#### ConfigTemplate
28
+
29
+
```javascript
30
+
// in lib/subscribers/<package_name>/config.js
31
+
32
+
const config = {
33
+
path: './<package_name>/<subscriber_name>.js',
34
+
instrumentations: [
35
+
{
36
+
/**
37
+
* By convention, we prefix channelNames with `nr_` and include at least the expressionName or methodName.
38
+
* It could also contain the moduleName or className to further differentiate between subscribers.
39
+
*/
40
+
channelName: 'nr_functionName',
41
+
/**
42
+
* <version_range> should be the same as the old instrumentation.
43
+
* However, you may need to break apart that range across different configs
44
+
* because code can differ from version to version.
45
+
*
46
+
* <relative_path_to_file> is the relative path from the instrumented package
47
+
* to the file that contains the code that you want to instrument
// If the function is `async`, specify `Async` here. Callback functions are typically `Sync`.
54
+
kind: 'Sync' | 'Async'
55
+
},
56
+
// OR
57
+
// if not a Class
58
+
functionQuery: {
59
+
moduleName: 'ModuleName',
60
+
expressionName: 'expressionName',
61
+
kind: 'Sync' | 'Async'
62
+
},
63
+
// OR
64
+
// if the module is not defined
65
+
functionQuery: {
66
+
expressionName: 'expressionName',
67
+
kind: 'Sync' | 'Async'
68
+
}
69
+
}
70
+
/**
71
+
* If you need to use the same instrumentation/subscriber for differently structured code
72
+
* (e.g. an older version of the package uses moduleName/expressionName, but now the
73
+
* same function is className/methodName), you'd add another instrumentation object
74
+
* to the array of `instrumentations`.
75
+
*/
76
+
]
77
+
}
78
+
79
+
module.exports = {
80
+
// Note: config(s) must be in an array, even if there's just one
81
+
'<package_name>': [
82
+
config
83
+
]
84
+
}
85
+
```
86
+
87
+
### CreatingtheSubscribers
88
+
89
+
Nowthatyouhavetheconfigspecifiedforthefunction 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)).
90
+
91
+
#### Datastore Subscribers
92
+
93
+
For datastore queries, inherit from `DbQuerySubscriber`. For datastore operations, inherit from `DbOperationSubscriber`.
94
+
95
+
#### Messaging Subscribers
96
+
97
+
For messaging queues, inherit from `MessageConsumerSubscriber` or `MessageProducerSubscriber.`
98
+
99
+
#### Propagation Subscriber
100
+
101
+
Many packages are written in a way that causes `AsyncLocalStorage` to lose context. A common instance of this is multiple nestled callbacks. To solve this, create `PropagationSubscriber`s for inner functions within the one you are instrumenting. You may have to experiment a few times to know which function is losing context; in most cases, you should only need one `PropagationSubscriber` to support another subscriber.
* register handlers for. For any name in the set, a corresponding method
39
39
* must exist on the subscriber instance. The method will be passed the
40
40
* event object. Possible event names are `start`, `end`, `asyncStart`,
41
-
* `asyncEnd`, and `error`. @link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel
42
-
* @property {boolean} [opaque=false] If true, any children segments will not be created
43
-
* @property {boolean} [internal=false] If true, any children segments from the same library will not be created
41
+
* `asyncEnd`, and `error`.
42
+
*
43
+
* See {@link https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel}
44
+
* @property {boolean} [opaque=false] If true, any children segments will not be created.
45
+
* @property {boolean} [internal=false] If true, any children segments from the same library
46
+
* will not be created.
44
47
* @property {string} [prefix='orchestrion:'] String to prepend to diagnostics
45
48
* channel event names. This provides a namespace for the events we are
46
49
* injecting into a module.
47
-
* @property {boolean} [requireActiveTx=true] If true, the subscriber will only handle events when there is an active transaction.
48
-
* @property {boolean} [propagateContext=false] If true, it will bind `asyncStart` to the store and re-propagate the active context. It will also attach the `transaction` to the event in `start.bindStore`. This is used for functions that queue async code and context is lost.
49
-
* @property {string} id A unique identifier for the subscriber, combining the prefix, package name, and channel name.
50
+
* @property {boolean} [requireActiveTx=true] If true, the subscriber will only handle events
51
+
* when there is an active transaction.
52
+
* @property {boolean} [propagateContext=false] If true, it will bind `asyncStart` to the store
53
+
* and re-propagate the active context. It will also attach the `transaction` to the event in
54
+
* `start.bindStore`. This is used for functions that queue async code and context is lost.
55
+
* @property {string} id A unique identifier for the subscriber, combining the prefix, package
56
+
* name, and channel name.
50
57
* @property {TracingChannel} channel The tracing channel instance this subscriber will be monitoring.
51
58
* @property {AsyncLocalStorage} store The async local storage instance used for context management.
52
-
* @property {number} callback position of callback if it needs to be wrapped for instrumentation. -1 means last argument
59
+
* @property {number} [callback=null] Position of callback if it needs to be wrapped for instrumentation.
60
+
* -1 means last argument.
53
61
*/
54
62
classSubscriber{
63
+
/**
64
+
* @param {SubscriberParams} params the subscriber constructor params
* 1. Calling consume creates a segment if in an active transaction
15
-
* 2. For every consumption, typically registered as a callback, it will create a transaction of type `message`, create a baseSegment, add both segment and trace attributes, and assign the `message-transaction` timeslice metrics
16
-
*
17
13
* @typedef {object} MessageConsumerParams
18
14
* @property {object} agent A New Relic Node.js agent instance.
19
15
* @property {object} logger An agent logger instance.
* @property {number} callback if consumer is callback based, indicates index of callback
27
23
* @property {string} transport identifier of the transport(see Transaction.TRANSPORT_TYPES)
28
24
*/
29
-
classMessageConsumerextendsSubscriber{
25
+
26
+
/**
27
+
* A message consumer does the following:
28
+
* 1. Calling consume creates a segment if in an active transaction
29
+
* 2. For every consumption, typically registered as a callback, it will create a transaction of type `message`, create a baseSegment, add both segment and trace attributes, and assign the `message-transaction` timeslice metrics
0 commit comments