Tracing Hooks

This repository contains a ESM loader for injecting tracing channel hooks into Node.js modules. It also has a patch for Module to be used to patch CJS modules.

Usage

To load esm loader:

``js
// esm-loader.mjs
import { register } from 'node:module';
const instrumentations = [
{
channelName: 'channel1',
module: { name: 'pkg1', verisonRange: '>=1.0.0', filePath: 'index.js' },
functionQuery: {
className: 'Class1',
methodName: 'method1',
kind: 'Async'
}
},
{
channelName: 'channel2',
module: { name: 'pkg2', verisonRange: '>=1.0.0', filePath: 'index.js' },
functionQuery: {
className: 'Class2,
methodName: 'method2',
kind: 'Sync'
}
}
]

register('@apm-js-collab/tracing-hooks/hook.mjs', import.meta.url, {
data: { instrumentations }
});
`

To use the loader, you can run your Node.js application with the --import flag:

`bash
node --import esm-loader.mjs your-app.js
`

To load CJS patch:

`js
// cjs-patch.js
const ModulePatch = require('@apm-js-collab/tracing-hooks')
const instrumentations = [
{
channelName: 'channel1',
module: { name: 'pkg1', verisonRange: '>=1.0.0', filePath: 'index.js' },
functionQuery: {
className: 'Class1',
methodName: 'method1',
kind: 'Async'
}
},
{
channelName: 'channel2',
module: { name: 'pkg2', verisonRange: '>=1.0.0', filePath: 'index.js' },
functionQuery: {
className: 'Class2',
methodName: 'method2',
kind: 'Sync'
}
}
]


const modulePatch = new ModulePatch({ instrumentations });
modulePatch.patch()
`

To use the CJS patch you can run your Node.js application with the --require flag:

`bash
node --require cjs-patch.js your-app.js
`

Debugging

The debug module is used to provide
insight into the patching process. Set DEBUG='@apm-js-collab*' to view these
logs.

Additionally, any patched files can be written out by enabling dump mode. This
is done by setting the environment variable TRACING_DUMP to any value. By
default, it will write out file to the system's temporary directory as the
parent directory. The target parent directory can be configured by setting
the TRACING_DUMP_DIR environment variable to an absolute path. In either
case, the resolved filename of the module being patched is appended. For
example, if we are patching lib/index.js in the foo package, and we set
a base directory of /tmp/dump/, then the patched code will be written to
/tmp/dump/foo/lib/index.js`.