npm package: @jennifersoft/jennifer5-instrumentation
Description: Instrumentation hooks for Jennifer APM
Author: taylor@jennifersoft.com
Latest version: 5.6.5

# @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

```bash
$ # 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:

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

Edit the configuration file with your Jennifer5 server settings:

```toml
# 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**

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

**ESM application**

```bash
$ 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.
>
> ```bash
> $ node --permission --allow-worker --import @jennifersoft/jennifer5-instrumentation/auto your_server.js
> ```

### Option 2: NODE_OPTIONS Environment Variable

**CommonJS application**

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

**ESM application**

```bash
$ 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.

```bash
$ 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`)**

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

**ESM application (`your_server.js` or `your_server.mjs`)**

```javascript
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.