@jennifersoft/jennifer5-instrumentation

Node.js APM instrumentation layer for Jennifer5 monitoring system.

Supported Environments

• Platform: Linux x64 gnu (GLIBC 2.15+), Linux x64 musl
• Jennifer5 Server: 5.6.5.7 or later
• Node.js:
  • CommonJS modules: 18.0+
  • ESM modules: 18.19+ or 20.6+
    • This package's ESM setup additionally needs module.register(), which is available from Node.js 20.6.0 and 18.19.0.
    • https://nodejs.org/docs/latest/api/module.html#moduleregisterspecifier-parenturl-options

Installation

Install via NPM

$ # In your Node.js project directory
$ npm install @jennifersoft/jennifer5-instrumentation

Configuration

Copy the jennifer.toml configuration file from the installed package to your Node.js project's working directory:

$ cp node_modules/@jennifersoft/jennifer5-agent/jennifer.toml .

Edit the configuration file with your Jennifer5 server settings:

# jennifer5 server address
server_address = "127.0.0.1"

# jennifer5 server port
server_port = 5000

# domain_id
domain_id = 1000

# instance id, if inst_id is '-1', inst_id will be set by server
inst_id = -1

Running Node.js with Jennifer5 Agent

Option 1: Command Line Arguments

CommonJS application

$ node --require @jennifersoft/jennifer5-instrumentation/auto your_server.js

ESM application

$ node --import @jennifersoft/jennifer5-instrumentation/auto your_server.js

Note (Permission model): If Node.js permission model (--permission) is enabled, add --allow-worker because module.register() requires worker permission.

$ node --permission --allow-worker --import @jennifersoft/jennifer5-instrumentation/auto your_server.js

Option 2: NODE_OPTIONS Environment Variable

CommonJS application

$ export NODE_OPTIONS="--require @jennifersoft/jennifer5-instrumentation/auto"
$ node your_server.js

ESM application

$ export NODE_OPTIONS="--import @jennifersoft/jennifer5-instrumentation/auto"
$ node your_server.js

Note (Permission model): If Node.js permission model (--permission) is enabled, add --allow-worker because module.register() requires worker permission.

$ export NODE_OPTIONS="--permission --allow-worker --import @jennifersoft/jennifer5-instrumentation/auto"
$ node your_server.js

Option 3: Initialize in Entry File

Load Jennifer at the very top of your entry file before other imports.

CommonJS application (your_server.js)

require("@jennifersoft/jennifer5-instrumentation/auto");

ESM application (your_server.js or your_server.mjs)

import "@jennifersoft/jennifer5-instrumentation/auto";

Note (ESM): For the most reliable instrumentation, use Option 1 or Option 2. In ESM, part of the module graph can be resolved or loaded before your entry file body runs. If Jennifer initializes after that point, some modules may be loaded before hooks are registered.