@obzerver/node 0.0.0-stage → 0.3.2

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.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +92 -2
  3. package/dist/agent-types.d.ts +28 -0
  4. package/dist/agent-types.js +6 -0
  5. package/dist/agent-types.js.map +1 -0
  6. package/dist/agent.d.ts +90 -0
  7. package/dist/agent.js +578 -0
  8. package/dist/agent.js.map +1 -0
  9. package/dist/context.d.ts +86 -0
  10. package/dist/context.js +136 -0
  11. package/dist/context.js.map +1 -0
  12. package/dist/errors.d.ts +18 -0
  13. package/dist/errors.js +108 -0
  14. package/dist/errors.js.map +1 -0
  15. package/dist/index.d.ts +76 -0
  16. package/dist/index.js +110 -0
  17. package/dist/index.js.map +1 -0
  18. package/dist/instrument/console.d.ts +11 -0
  19. package/dist/instrument/console.js +68 -0
  20. package/dist/instrument/console.js.map +1 -0
  21. package/dist/instrument/db.d.ts +7 -0
  22. package/dist/instrument/db.js +155 -0
  23. package/dist/instrument/db.js.map +1 -0
  24. package/dist/instrument/express.d.ts +3 -0
  25. package/dist/instrument/express.js +133 -0
  26. package/dist/instrument/express.js.map +1 -0
  27. package/dist/instrument/fastify.d.ts +35 -0
  28. package/dist/instrument/fastify.js +88 -0
  29. package/dist/instrument/fastify.js.map +1 -0
  30. package/dist/instrument/http.d.ts +10 -0
  31. package/dist/instrument/http.js +149 -0
  32. package/dist/instrument/http.js.map +1 -0
  33. package/dist/instrument/jobs.d.ts +15 -0
  34. package/dist/instrument/jobs.js +90 -0
  35. package/dist/instrument/jobs.js.map +1 -0
  36. package/dist/options.d.ts +89 -0
  37. package/dist/options.js +3 -0
  38. package/dist/options.js.map +1 -0
  39. package/dist/protocol.d.ts +146 -0
  40. package/dist/protocol.js +4 -0
  41. package/dist/protocol.js.map +1 -0
  42. package/dist/redact.d.ts +12 -0
  43. package/dist/redact.js +54 -0
  44. package/dist/redact.js.map +1 -0
  45. package/dist/register.d.ts +1 -0
  46. package/dist/register.js +9 -0
  47. package/dist/register.js.map +1 -0
  48. package/dist/runtime.d.ts +37 -0
  49. package/dist/runtime.js +142 -0
  50. package/dist/runtime.js.map +1 -0
  51. package/dist/transport.d.ts +32 -0
  52. package/dist/transport.js +122 -0
  53. package/dist/transport.js.map +1 -0
  54. 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,93 @@
1
- # Temporary Holding Version
1
+ # @obzerver/node
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ - **Logs**: `console.*`, plus `pino` through the `pino()` helper.
47
+ - **Runtime**: CPU, memory, event loop lag and GC.
48
+
49
+ ## Optional APIs
50
+
51
+ ```ts
52
+ import { job, span, instrument, setUser, tag, metrics } from '@obzerver/node';
53
+
54
+ // Any background function that isn't BullMQ / node-cron / cron
55
+ const warmCache = job('warm-cache', async () => { /* … */ });
56
+
57
+ // A custom timed span
58
+ await span('render-invoice', () => renderPdf(order));
59
+
60
+ // Time every method of a class as its own span
61
+ instrument(OrdersService);
62
+
63
+ // Attach the user and tags to the current request
64
+ setUser(req.user.id);
65
+ tag('plan', 'pro');
66
+
67
+ // Business metrics
68
+ metrics.counter('orders_created', { channel: 'web' }).inc();
69
+ ```
70
+
71
+ Fastify users can also register the `fastify` plugin export instead of relying on auto-detection.
72
+
73
+ ## Options
74
+
75
+ | Option | Env | Default |
76
+ |---|---|---|
77
+ | `appKey` | `OBZERVER_KEY` | required (from the dashboard's **Setup & settings**) |
78
+ | `endpoint` | `OBZERVER_ENDPOINT` | `http://localhost:4319` |
79
+ | `serviceId` | `OBZERVER_SERVICE` | `name` from your package.json |
80
+ | `serviceVersion` | `OBZERVER_VERSION`, `GIT_SHA` | `version` from your package.json (enables the Releases view) |
81
+ | `environment` | `OBZERVER_ENV`, `NODE_ENV` | `development` |
82
+ | `tracesSampleRate` | `OBZERVER_SAMPLE_RATE` | `1` |
83
+ | `enabled` | `OBZERVER_ENABLED` | `true` |
84
+ | `instrument` | — | all on: `http`, `fetch`, `express`, `fastify`, `pg`, `mysql2`, `ioredis`, `bullmq`, `nodeCron`, `cron`, `console` |
85
+
86
+ ## Requirements
87
+
88
+ - Node.js 18.19 or newer.
89
+ - 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.
90
+
91
+ ## License
92
+
93
+ 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"}
@@ -0,0 +1,90 @@
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
+ declare const MODULE_NAMES: readonly ["express", "pg", "mysql2", "ioredis", "bullmq", "node-cron", "cron"];
11
+ type ModuleName = typeof MODULE_NAMES[number];
12
+ /** /orders/123/items/9f1c… -> /orders/:id/items/:id (only when no framework route is known) */
13
+ export declare function normalizePath(p: string): string;
14
+ interface EmitFields {
15
+ method?: string | null;
16
+ route?: string | null;
17
+ path?: string | null;
18
+ status: number | null;
19
+ userId?: string | null;
20
+ unhandled?: boolean;
21
+ failed?: boolean;
22
+ failMessage?: string | null;
23
+ capture?: CaptureData;
24
+ errorEvents: WireError[];
25
+ slow: boolean;
26
+ queue?: string | null;
27
+ queueWait?: number | null;
28
+ attempt?: number | null;
29
+ }
30
+ export interface JobMeta {
31
+ name?: string;
32
+ queue?: string;
33
+ attempt?: number;
34
+ queueWait?: number | null;
35
+ }
36
+ export interface JobOptions<A extends unknown[]> {
37
+ queue?: string;
38
+ meta?: (...args: A) => JobMeta | undefined;
39
+ }
40
+ export declare class Agent implements AgentHooks {
41
+ readonly cwd: string;
42
+ readonly options: ResolvedOptions;
43
+ readonly redactor: Redactor;
44
+ readonly frameworks: Set<string>;
45
+ transport: Transport | null;
46
+ runtime: RuntimeSampler | null;
47
+ metrics: Metrics | null;
48
+ inflight: number;
49
+ inLog: boolean;
50
+ private readonly patched;
51
+ constructor(options?: ObzerverOptions);
52
+ log(...args: unknown[]): void;
53
+ debug(...args: unknown[]): void;
54
+ start(): this;
55
+ applyPatch(name: ModuleName, exportsObj: unknown): unknown;
56
+ private hookModules;
57
+ /**
58
+ * bullmq and node-cron ship separate ESM builds, so an ESM `import` would load an
59
+ * unpatched copy. With module.registerHooks (Node 22.15+) those imports resolve to
60
+ * the CommonJS build instead, which is the copy the SDK has patched.
61
+ */
62
+ private routeEsmImports;
63
+ private isEnabled;
64
+ startHttp(req: IncomingMessage, res: ServerResponse): Trace | null;
65
+ recordRequestError(trace: Trace, err: unknown): void;
66
+ private finishHttp;
67
+ makeErrorEvent(err: unknown, trace: Trace | null, { status, unhandled, route }: {
68
+ status?: number | null;
69
+ unhandled: boolean;
70
+ route?: string | null;
71
+ }): WireError;
72
+ serializeSpans(trace: Trace): WireSpan[];
73
+ emitTrace(trace: Trace, f: EmitFields): void;
74
+ /** Run one invocation of fn as its own job trace (used by job() and the BullMQ/cron instrumentations). */
75
+ runJob<R>(name: string, fn: () => R, meta: JobMeta, auto?: boolean): R;
76
+ job<A extends unknown[], R>(name: string, fn: (...args: A) => R, opts?: JobOptions<A>): (...args: A) => R;
77
+ currentTraceId(): string | null;
78
+ recordLog(level: string, message: string, logger: string | null, attrs?: Record<string, unknown>): void;
79
+ captureError(err: unknown, extra?: {
80
+ handled?: boolean;
81
+ operation?: string;
82
+ standalone?: boolean;
83
+ }): void;
84
+ private installProcessHooks;
85
+ private spoolFile;
86
+ private writeSpool;
87
+ private loadSpool;
88
+ shutdown(): Promise<void>;
89
+ }
90
+ export {};