@obzerver/node 0.0.0-stage → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +97 -2
- package/dist/agent-types.d.ts +28 -0
- package/dist/agent-types.js +6 -0
- package/dist/agent-types.js.map +1 -0
- package/dist/agent.d.ts +97 -0
- package/dist/agent.js +651 -0
- package/dist/agent.js.map +1 -0
- package/dist/context.d.ts +86 -0
- package/dist/context.js +136 -0
- package/dist/context.js.map +1 -0
- package/dist/errors.d.ts +18 -0
- package/dist/errors.js +108 -0
- package/dist/errors.js.map +1 -0
- package/dist/glob.d.ts +7 -0
- package/dist/glob.js +56 -0
- package/dist/glob.js.map +1 -0
- package/dist/index.d.ts +76 -0
- package/dist/index.js +89 -0
- package/dist/index.js.map +1 -0
- package/dist/instrument/classes.d.ts +18 -0
- package/dist/instrument/classes.js +103 -0
- package/dist/instrument/classes.js.map +1 -0
- package/dist/instrument/console.d.ts +11 -0
- package/dist/instrument/console.js +68 -0
- package/dist/instrument/console.js.map +1 -0
- package/dist/instrument/db.d.ts +7 -0
- package/dist/instrument/db.js +155 -0
- package/dist/instrument/db.js.map +1 -0
- package/dist/instrument/express.d.ts +3 -0
- package/dist/instrument/express.js +133 -0
- package/dist/instrument/express.js.map +1 -0
- package/dist/instrument/fastify.d.ts +35 -0
- package/dist/instrument/fastify.js +88 -0
- package/dist/instrument/fastify.js.map +1 -0
- package/dist/instrument/http.d.ts +10 -0
- package/dist/instrument/http.js +149 -0
- package/dist/instrument/http.js.map +1 -0
- package/dist/instrument/jobs.d.ts +15 -0
- package/dist/instrument/jobs.js +90 -0
- package/dist/instrument/jobs.js.map +1 -0
- package/dist/options.d.ts +110 -0
- package/dist/options.js +3 -0
- package/dist/options.js.map +1 -0
- package/dist/protocol.d.ts +146 -0
- package/dist/protocol.js +4 -0
- package/dist/protocol.js.map +1 -0
- package/dist/redact.d.ts +12 -0
- package/dist/redact.js +54 -0
- package/dist/redact.js.map +1 -0
- package/dist/register.d.ts +1 -0
- package/dist/register.js +9 -0
- package/dist/register.js.map +1 -0
- package/dist/release.d.ts +32 -0
- package/dist/release.js +141 -0
- package/dist/release.js.map +1 -0
- package/dist/runtime.d.ts +37 -0
- package/dist/runtime.js +142 -0
- package/dist/runtime.js.map +1 -0
- package/dist/transport.d.ts +32 -0
- package/dist/transport.js +122 -0
- package/dist/transport.js.map +1 -0
- package/package.json +51 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Obzerver contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,98 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @obzerver/node
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Zero-config observability SDK for **Express** and **Fastify** apps. It sends requests, traces, errors, logs, database queries, background jobs and runtime metrics to an [Obzerver](https://www.npmjs.com/package/@obzerver/server) server, with no changes to your route code.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install @obzerver/node
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Setup
|
|
10
|
+
|
|
11
|
+
The SDK must load before your app, so it can patch Express, Fastify and your database drivers.
|
|
12
|
+
|
|
13
|
+
**Option 1: zero code.** Set two environment variables and preload the SDK:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
OBZERVER_KEY=obz_xxx OBZERVER_ENDPOINT=http://localhost:4319 \
|
|
17
|
+
node --import @obzerver/node/register server.js
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**Option 2: an instrument file.** Useful for setting options in code.
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
// instrument.ts
|
|
24
|
+
import { init } from '@obzerver/node';
|
|
25
|
+
|
|
26
|
+
init({
|
|
27
|
+
serviceId: 'shop-api',
|
|
28
|
+
appKey: process.env.OBZERVER_KEY,
|
|
29
|
+
endpoint: process.env.OBZERVER_ENDPOINT,
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
node --import ./instrument.ts server.ts
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
With CommonJS, `require('./instrument')` as the first line of your entry file.
|
|
38
|
+
|
|
39
|
+
## What is captured automatically
|
|
40
|
+
|
|
41
|
+
- **HTTP**: every request with its route template (`/orders/:id`), status, duration, and Express middleware / Fastify hook timings.
|
|
42
|
+
- **Errors**: thrown errors and `next(err)` with stack and source lines.
|
|
43
|
+
- **Distributed traces**: outbound `http` and `fetch` calls carry `traceparent`, so calls between your services join into one trace.
|
|
44
|
+
- **Databases**: `pg`, `mysql2`, `ioredis`.
|
|
45
|
+
- **Background jobs**: BullMQ workers, `node-cron` and `cron`. Each run is a job with its own trace, failures, queue wait and attempt number.
|
|
46
|
+
- **Your service classes**: every method of classes exported from `*.service.ts` and `*.repository.ts` files (and their `.js` builds), shown with own time and total time.
|
|
47
|
+
- **Releases**: the version is inferred from CI variables or your `.git` checkout.
|
|
48
|
+
- **Logs**: `console.*`, plus `pino` through the `pino()` helper.
|
|
49
|
+
- **Runtime**: CPU, memory, event loop lag and GC.
|
|
50
|
+
|
|
51
|
+
## Optional APIs
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { job, span, instrument, setUser, tag, metrics } from '@obzerver/node';
|
|
55
|
+
|
|
56
|
+
// Any background function that isn't BullMQ / node-cron / cron
|
|
57
|
+
const warmCache = job('warm-cache', async () => { /* … */ });
|
|
58
|
+
|
|
59
|
+
// A custom timed span
|
|
60
|
+
await span('render-invoice', () => renderPdf(order));
|
|
61
|
+
|
|
62
|
+
// Classes exported from *.service.ts / *.repository.ts are timed automatically.
|
|
63
|
+
// Any other class: time every method as its own span
|
|
64
|
+
instrument(PdfRenderer);
|
|
65
|
+
|
|
66
|
+
// Attach the user and tags to the current request
|
|
67
|
+
setUser(req.user.id);
|
|
68
|
+
tag('plan', 'pro');
|
|
69
|
+
|
|
70
|
+
// Business metrics
|
|
71
|
+
metrics.counter('orders_created', { channel: 'web' }).inc();
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Fastify users can also register the `fastify` plugin export instead of relying on auto-detection.
|
|
75
|
+
|
|
76
|
+
## Options
|
|
77
|
+
|
|
78
|
+
| Option | Env | Default |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `appKey` | `OBZERVER_KEY` | required (from the dashboard's **Setup & settings**) |
|
|
81
|
+
| `endpoint` | `OBZERVER_ENDPOINT` | `http://localhost:4319` |
|
|
82
|
+
| `serviceId` | `OBZERVER_SERVICE` | `name` from your package.json |
|
|
83
|
+
| `serviceVersion` | `OBZERVER_VERSION` | Inferred: `OBZERVER_VERSION`, then a CI/platform commit (`GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, …), then the commit in `.git`, then a container revision (`K_REVISION`), then `version` from package.json. `false` reports none. Powers the Releases view |
|
|
84
|
+
| `autoInstrument` | `OBZERVER_AUTO_INSTRUMENT` | `['**/*.service.*', '**/*.repository.*']` (JS/TS extensions): classes exported from matching files are timed method by method in the Services view. `false` turns it off |
|
|
85
|
+
| `environment` | `OBZERVER_ENV`, `NODE_ENV` | `development` |
|
|
86
|
+
| `tracesSampleRate` | `OBZERVER_SAMPLE_RATE` | `1` |
|
|
87
|
+
| `tracePreflights` | `OBZERVER_TRACE_PREFLIGHTS` | `false`: OPTIONS requests (CORS preflights) are not recorded. Set to `true` to record them |
|
|
88
|
+
| `enabled` | `OBZERVER_ENABLED` | `true` |
|
|
89
|
+
| `instrument` | — | all on: `http`, `fetch`, `express`, `fastify`, `pg`, `mysql2`, `ioredis`, `bullmq`, `nodeCron`, `cron`, `console` |
|
|
90
|
+
|
|
91
|
+
## Requirements
|
|
92
|
+
|
|
93
|
+
- Node.js 18.19 or newer.
|
|
94
|
+
- Node.js 22.15+ is needed to auto-instrument BullMQ, node-cron and cron when they are loaded with ESM `import`. With `require` they work on every supported version.
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from 'node:http';
|
|
2
|
+
import type { Trace } from './context';
|
|
3
|
+
import type { Redactor } from './redact';
|
|
4
|
+
import type { Transport } from './transport';
|
|
5
|
+
/** What instrumentation modules need from the agent (keeps imports acyclic). */
|
|
6
|
+
export interface AgentHooks {
|
|
7
|
+
readonly cwd: string;
|
|
8
|
+
readonly redactor: Redactor;
|
|
9
|
+
readonly frameworks: Set<string>;
|
|
10
|
+
readonly transport: Transport | null;
|
|
11
|
+
inLog: boolean;
|
|
12
|
+
inflight: number;
|
|
13
|
+
startHttp(req: IncomingMessage, res: ServerResponse): Trace | null;
|
|
14
|
+
recordRequestError(trace: Trace, err: unknown): void;
|
|
15
|
+
recordLog(level: string, message: string, logger: string | null, attrs?: Record<string, unknown>): void;
|
|
16
|
+
captureError(err: unknown, extra?: {
|
|
17
|
+
handled?: boolean;
|
|
18
|
+
operation?: string;
|
|
19
|
+
standalone?: boolean;
|
|
20
|
+
}): void;
|
|
21
|
+
currentTraceId(): string | null;
|
|
22
|
+
debug(...args: unknown[]): void;
|
|
23
|
+
}
|
|
24
|
+
/** Symbol stored on the raw IncomingMessage pointing at its Trace (null = ignored). */
|
|
25
|
+
export declare const kTrace: unique symbol;
|
|
26
|
+
export type TracedRequest = IncomingMessage & {
|
|
27
|
+
[kTrace]?: Trace | null;
|
|
28
|
+
};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.kTrace = void 0;
|
|
4
|
+
/** Symbol stored on the raw IncomingMessage pointing at its Trace (null = ignored). */
|
|
5
|
+
exports.kTrace = Symbol.for('obzerver.trace');
|
|
6
|
+
//# sourceMappingURL=agent-types.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../src/agent-types.ts"],"names":[],"mappings":";;;AAqBA,uFAAuF;AAC1E,QAAA,MAAM,GAAkB,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAU,CAAC"}
|
package/dist/agent.d.ts
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from 'node:http';
|
|
2
|
+
import { Transport } from './transport';
|
|
3
|
+
import { Trace } from './context';
|
|
4
|
+
import { type Redactor } from './redact';
|
|
5
|
+
import { RuntimeSampler, Metrics } from './runtime';
|
|
6
|
+
import type { AgentHooks } from './agent-types';
|
|
7
|
+
import type { CaptureData, WireError, WireSpan } from './protocol';
|
|
8
|
+
import type { ResolvedOptions, ObzerverOptions } from './options';
|
|
9
|
+
export declare const SDK_VERSION: string;
|
|
10
|
+
/** Files whose exported classes are instrumented automatically (NestJS-style names). */
|
|
11
|
+
export declare const DEFAULT_AUTO_INSTRUMENT: readonly ["**/*.service.{ts,mts,cts,js,mjs,cjs}", "**/*.repository.{ts,mts,cts,js,mjs,cjs}"];
|
|
12
|
+
declare const MODULE_NAMES: readonly ["express", "pg", "mysql2", "ioredis", "bullmq", "node-cron", "cron"];
|
|
13
|
+
type ModuleName = typeof MODULE_NAMES[number];
|
|
14
|
+
/** /orders/123/items/9f1c… -> /orders/:id/items/:id (only when no framework route is known) */
|
|
15
|
+
export declare function normalizePath(p: string): string;
|
|
16
|
+
interface EmitFields {
|
|
17
|
+
method?: string | null;
|
|
18
|
+
route?: string | null;
|
|
19
|
+
path?: string | null;
|
|
20
|
+
status: number | null;
|
|
21
|
+
userId?: string | null;
|
|
22
|
+
unhandled?: boolean;
|
|
23
|
+
failed?: boolean;
|
|
24
|
+
failMessage?: string | null;
|
|
25
|
+
capture?: CaptureData;
|
|
26
|
+
errorEvents: WireError[];
|
|
27
|
+
slow: boolean;
|
|
28
|
+
queue?: string | null;
|
|
29
|
+
queueWait?: number | null;
|
|
30
|
+
attempt?: number | null;
|
|
31
|
+
}
|
|
32
|
+
export interface JobMeta {
|
|
33
|
+
name?: string;
|
|
34
|
+
queue?: string;
|
|
35
|
+
attempt?: number;
|
|
36
|
+
queueWait?: number | null;
|
|
37
|
+
}
|
|
38
|
+
export interface JobOptions<A extends unknown[]> {
|
|
39
|
+
queue?: string;
|
|
40
|
+
meta?: (...args: A) => JobMeta | undefined;
|
|
41
|
+
}
|
|
42
|
+
export declare class Agent implements AgentHooks {
|
|
43
|
+
readonly cwd: string;
|
|
44
|
+
readonly options: ResolvedOptions;
|
|
45
|
+
readonly redactor: Redactor;
|
|
46
|
+
readonly frameworks: Set<string>;
|
|
47
|
+
transport: Transport | null;
|
|
48
|
+
runtime: RuntimeSampler | null;
|
|
49
|
+
metrics: Metrics | null;
|
|
50
|
+
inflight: number;
|
|
51
|
+
inLog: boolean;
|
|
52
|
+
private readonly patched;
|
|
53
|
+
constructor(options?: ObzerverOptions);
|
|
54
|
+
log(...args: unknown[]): void;
|
|
55
|
+
debug(...args: unknown[]): void;
|
|
56
|
+
start(): this;
|
|
57
|
+
applyPatch(name: ModuleName, exportsObj: unknown): unknown;
|
|
58
|
+
/** Matches app files whose exported classes are instrumented automatically (null when off). */
|
|
59
|
+
autoMatch: ((file: string) => boolean) | null;
|
|
60
|
+
private autoDone;
|
|
61
|
+
/** Instrument the classes a matching module exports. Safe to call more than once per file. */
|
|
62
|
+
autoInstrumentModule(file: string, exports: unknown): void;
|
|
63
|
+
private hookModules;
|
|
64
|
+
/**
|
|
65
|
+
* bullmq and node-cron ship separate ESM builds, so an ESM `import` would load an
|
|
66
|
+
* unpatched copy. With module.registerHooks (Node 22.15+) those imports resolve to
|
|
67
|
+
* the CommonJS build instead, which is the copy the SDK has patched.
|
|
68
|
+
*/
|
|
69
|
+
private routeEsmImports;
|
|
70
|
+
private isEnabled;
|
|
71
|
+
startHttp(req: IncomingMessage, res: ServerResponse): Trace | null;
|
|
72
|
+
recordRequestError(trace: Trace, err: unknown): void;
|
|
73
|
+
private finishHttp;
|
|
74
|
+
makeErrorEvent(err: unknown, trace: Trace | null, { status, unhandled, route }: {
|
|
75
|
+
status?: number | null;
|
|
76
|
+
unhandled: boolean;
|
|
77
|
+
route?: string | null;
|
|
78
|
+
}): WireError;
|
|
79
|
+
serializeSpans(trace: Trace): WireSpan[];
|
|
80
|
+
emitTrace(trace: Trace, f: EmitFields): void;
|
|
81
|
+
/** Run one invocation of fn as its own job trace (used by job() and the BullMQ/cron instrumentations). */
|
|
82
|
+
runJob<R>(name: string, fn: () => R, meta: JobMeta, auto?: boolean): R;
|
|
83
|
+
job<A extends unknown[], R>(name: string, fn: (...args: A) => R, opts?: JobOptions<A>): (...args: A) => R;
|
|
84
|
+
currentTraceId(): string | null;
|
|
85
|
+
recordLog(level: string, message: string, logger: string | null, attrs?: Record<string, unknown>): void;
|
|
86
|
+
captureError(err: unknown, extra?: {
|
|
87
|
+
handled?: boolean;
|
|
88
|
+
operation?: string;
|
|
89
|
+
standalone?: boolean;
|
|
90
|
+
}): void;
|
|
91
|
+
private installProcessHooks;
|
|
92
|
+
private spoolFile;
|
|
93
|
+
private writeSpool;
|
|
94
|
+
private loadSpool;
|
|
95
|
+
shutdown(): Promise<void>;
|
|
96
|
+
}
|
|
97
|
+
export {};
|