@zharp/node 0.2.0 → 0.4.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/README.md CHANGED
@@ -37,7 +37,7 @@ node --import ./instrument.js server.js
37
37
 
38
38
  Loading it first is what makes it work: the instrumentations patch `http`, your framework and your database driver as they are first imported, so `init()` has to run before any of them are. With CommonJS, `node --require ./instrument.js server.js` does the same.
39
39
 
40
- With nothing but environment variables: `ZHARP_API_KEY=… ZHARP_SERVICE=checkout-api node --import @zharp/node/init server.js` (also `ZHARP_ENV`, `ZHARP_RELEASE`, `ZHARP_ENDPOINT`; `ZHARP_DISABLED=true` turns it off).
40
+ With nothing but environment variables: `ZHARP_API_KEY=… ZHARP_SERVICE=checkout-api node --import @zharp/node/init server.js` (also `ZHARP_ENV`, `ZHARP_RELEASE`, `ZHARP_LOGS`; `ZHARP_DISABLED=true` turns it off).
41
41
 
42
42
  ### Next.js
43
43
 
@@ -60,7 +60,7 @@ The Edge runtime is not supported. If the build complains about OpenTelemetry mo
60
60
  |---|---|
61
61
  | **Requests** | A SERVER span per incoming request (`http.request.method`, `http.route` where the framework knows it, `http.response.status_code`; 5xx are errors), CLIENT spans for outgoing HTTP, and spans for database and cache calls. `dns`, `net` and `fs` are off — one span per lookup or file read is noise. |
62
62
  | **Traces from the browser** | The `traceparent` header continues the browser's trace; `session.id` and `enduser.id` from the `baggage` header are copied onto every span and log of that request. |
63
- | **Logs** | `Zharp.log.*`, `console.*` (default on), and pino, winston and bunyan through OpenTelemetry's log bridges — each with the trace and span it was written in. |
63
+ | **Logs** | Every line the app prints during a request is stamped `trace_id=… span_id=…` (fields in JSON records), so the Zharp agent's copy of the app's output is linked to its request. With `logs: true` (`ZHARP_LOGS=true`) — for serverless or a host without the agent — the SDK sends them itself: `console.*`, pino, winston, bunyan and anything else printed, each with its trace and span. `Zharp.log.*` is always sent. |
64
64
  | **Errors** | `Zharp.captureError(err)` (handled), uncaught exceptions and unhandled rejections (unhandled). Sent as error logs with `exception.type`, `exception.message` and `exception.stacktrace`, grouped into issues. |
65
65
 
66
66
  ### Uncaught exceptions
@@ -77,7 +77,7 @@ What is waiting is sent when the event loop empties, and on SIGTERM/SIGINT (afte
77
77
  Zharp.init({ tracing: false }); // or ZHARP_TRACING=false
78
78
  ```
79
79
 
80
- Logs (`Zharp.log.*`, the console, pino, winston, bunyan), errors (with `exception.*` and the handled flag), the user, the session and tags are sent as usual. No spans are exported, nothing is instrumented except the log bridges and the incoming side of `http`, and no `traceparent` or `baggage` is added to outgoing requests. An incoming `traceparent` and `baggage` are still read, so a request's logs carry the caller's trace id, session and user (and `setUser()` inside a request stays with that request) — at the cost of one never-exported in-memory span per request. `Zharp.startSpan(name, fn)` just runs `fn`.
80
+ Logs (`Zharp.log.*`, and with `logs: true` the console, pino, winston, bunyan), errors (with `exception.*` and the handled flag), the user, the session and tags are sent as usual. No spans are exported, nothing is instrumented except the log bridges and the incoming side of `http`, and no `traceparent` or `baggage` is added to outgoing requests. An incoming `traceparent` and `baggage` are still read, so a request's logs carry the caller's trace id, session and user (and `setUser()` inside a request stays with that request) — at the cost of one never-exported in-memory span per request. `Zharp.startSpan(name, fn)` just runs `fn`.
81
81
 
82
82
  ## API
83
83
 
@@ -103,16 +103,18 @@ Everything else is plain OpenTelemetry: `trace.getActiveSpan()`, `trace.getTrace
103
103
  | `service` | `ZHARP_SERVICE`, `OTEL_SERVICE_NAME`, package.json name | `service.name` |
104
104
  | `environment` | `ZHARP_ENV`, `NODE_ENV` | `deployment.environment.name` |
105
105
  | `release` | `ZHARP_RELEASE` | `service.version` |
106
- | `endpoint` | `https://api.zharp.io/api/v1/otlp` | |
107
106
  | `tracing` | `ZHARP_TRACING`, else `true` | `false` for logs only (see above). |
108
107
  | `sampleRate` | `1` | Fraction of new traces kept. A trace that arrives with a decision (from the browser) keeps it. Errors and logs are always sent. |
109
- | `captureConsole` | `true` | |
108
+ | `logs` | `ZHARP_LOGS`, else `false` | Send what the app logs and prints. Off by default: where the Zharp agent reads the app's output it brings those lines in, linked by `logCorrelation`. Turn on for serverless or hosts without the agent. Errors, `Zharp.log` and traces are sent either way. |
109
+ | `logCorrelation` | `ZHARP_LOG_CORRELATION`, else `true` | Stamps `trace_id=… span_id=…` on each line printed during a request (fields in JSON records), so Zharp links it to the request. |
110
+ | `captureConsole` | `true` | With `logs` on. |
111
+ | `captureOutput` | `ZHARP_CAPTURE_OUTPUT`, else `true` | With `logs` on: everything else printed to stdout/stderr: NestJS's Logger, debug, log4js, anything writing to `process.stdout`. Level read from the line; keeps the request it was printed in; never sends a line twice. |
110
112
  | `captureUncaught` | `true` | |
111
113
  | `instrumentations` | | Per-instrumentation config for `getNodeAutoInstrumentations`, e.g. `{ '@opentelemetry/instrumentation-fs': { enabled: true } }`. |
112
114
  | `extraInstrumentations` | `[]` | More OpenTelemetry instrumentations. |
113
115
  | `debug` | `false` | Print what OpenTelemetry is doing. |
114
116
 
115
- Traces and logs go as OTLP/protobuf, gzipped, to `{endpoint}/v1/traces` and `/v1/logs` with `Authorization: Bearer <key>`.
117
+ Traces, errors and logs go straight to Zharp as OTLP/protobuf, gzipped.
116
118
 
117
119
  ## Readable stack traces
118
120
 
package/dist/index.d.mts CHANGED
@@ -75,11 +75,36 @@ interface NodeOptions {
75
75
  */
76
76
  tracing?: boolean;
77
77
  /**
78
- * Send `console.*` output as logs. Default **true**: on a server, the console is where most
78
+ * Send what the application logs — `console`, pino, winston, bunyan and everything else it
79
+ * prints. Default **false**: where the Zharp agent reads the app's output it already brings
80
+ * those lines in, linked to their requests by the ids stamped on them (see `logCorrelation`).
81
+ * Turn it on where nothing else collects the output (serverless, a plain VM without the
82
+ * agent). Falls back to `ZHARP_LOGS` (`true` turns it on). Errors, `Zharp.log` and traces are
83
+ * sent either way. `captureConsole` and `captureOutput` refine what is sent when this is on.
84
+ */
85
+ logs?: boolean;
86
+ /**
87
+ * Stamp the request's ids on every line printed during it — `trace_id=… span_id=…` at the end
88
+ * of a text line, two fields in a JSON record — so Zharp links the line to its request
89
+ * whichever way it arrives. Default **true**. Falls back to `ZHARP_LOG_CORRELATION`.
90
+ */
91
+ logCorrelation?: boolean;
92
+ /**
93
+ * With `logs` on: send `console.*` output as logs. Default **true**: on a server, the console is where most
79
94
  * logging already goes. pino, winston and bunyan are bridged by their instrumentations
80
95
  * whatever this says.
81
96
  */
82
97
  captureConsole?: boolean;
98
+ /**
99
+ * With `logs` on: send everything else the process prints as logs too: whatever reaches stdout or stderr
100
+ * without going through `console` or a bridged library — NestJS's Logger, debug, log4js,
101
+ * libraries writing to `process.stdout` directly. Default **true**. Each line keeps the
102
+ * request it was printed in; its level is read from the line (a JSON record's `level`,
103
+ * NestJS's `LOG`/`WARN`/`ERROR`, a word such as `ERROR`), else info on stdout and warn on
104
+ * stderr. A line another capture already sent is not sent again. `false` (or
105
+ * `ZHARP_CAPTURE_OUTPUT=false`) turns it off.
106
+ */
107
+ captureOutput?: boolean;
83
108
  /**
84
109
  * Request and response bodies on HTTP spans — incoming requests and outgoing http/https
85
110
  * calls. Default **off**. `'errors'` (or `true`) keeps them for failed requests only (status
@@ -94,6 +119,30 @@ interface NodeOptions {
94
119
  * captureBodies: { mode: 'all', redactKeys: ['dateOfBirth'], urls: [/\/api\//] }
95
120
  */
96
121
  captureBodies?: CaptureBodies;
122
+ /**
123
+ * Request and response headers on HTTP spans (`http.request.header.user-agent`, …), incoming
124
+ * and outgoing. Default **on**. Secret headers — `authorization`, `cookie`, `set-cookie`, API
125
+ * keys, tokens, and any name matching the body key rules — are recorded as `[Filtered]`: you
126
+ * see that one was sent, never its value. Add names to `redact` to filter more. `false` (or
127
+ * `ZHARP_CAPTURE_HEADERS=false`) turns it off.
128
+ */
129
+ captureHeaders?: boolean | {
130
+ redact?: Array<string | RegExp>;
131
+ };
132
+ /**
133
+ * Failed database queries reported as errors, with the line of your code that ran the query
134
+ * as their stack, the statement, and the driver's code (Postgres 23505 → `UniqueViolation`).
135
+ * Default true.
136
+ */
137
+ captureQueryErrors?: boolean;
138
+ /**
139
+ * The code around each error's lines, read on this server from your own files (never
140
+ * node_modules) and sent with the error, so Zharp shows exactly the code that ran without a
141
+ * repository link. Built code (TypeScript, a NestJS dist/) is read through the .js.map files
142
+ * next to it: the stack and the code are your sources. The innermost five frames, five lines
143
+ * either side. Default true; ZHARP_CAPTURE_SOURCE_CONTEXT=false turns it off.
144
+ */
145
+ captureSourceContext?: boolean;
97
146
  /**
98
147
  * Capture uncaught exceptions and unhandled rejections. Default true. The process still
99
148
  * exits as Node would have, once they have been sent.
@@ -123,6 +172,8 @@ declare class ZharpNode {
123
172
  private tracing;
124
173
  /** Errors already sent, so one that is both rejected and then thrown is reported once. */
125
174
  private readonly reported;
175
+ /** Failed queries waiting to be reported, once and with their call site. */
176
+ private dbErrors;
126
177
  /** `Zharp.log.info("Order placed", { orderId })` — and debug, warn, error, fatal, trace. */
127
178
  readonly log: Record<Level, LogFn>;
128
179
  /** Whether `init()` started the SDK. */
@@ -153,6 +204,25 @@ declare class ZharpNode {
153
204
  * in, and grouped into an issue with every other occurrence.
154
205
  */
155
206
  captureError(error: unknown, attributes?: Attributes): void;
207
+ /**
208
+ * Next.js (15+): errors a route handler, server component, server action or middleware threw,
209
+ * which Next answers with an error page and only prints. Export it from instrumentation.ts:
210
+ *
211
+ * export const onRequestError = Zharp.onRequestError;
212
+ *
213
+ * Each is reported once as a crash, with the request's path, method and route. A bound function,
214
+ * so it can be exported as it is.
215
+ */
216
+ readonly onRequestError: (error: unknown, request?: {
217
+ path?: string;
218
+ method?: string;
219
+ headers?: Record<string, string | string[] | undefined>;
220
+ }, context?: {
221
+ routerKind?: string;
222
+ routePath?: string;
223
+ routeType?: string;
224
+ renderSource?: string;
225
+ }) => void;
156
226
  /**
157
227
  * Run `fn` inside a span named `name`, which ends when `fn` returns or its promise settles. A
158
228
  * throw or rejection marks the span as failed and is passed on unchanged.
@@ -164,6 +234,8 @@ declare class ZharpNode {
164
234
  shutdown(): Promise<void>;
165
235
  private emit;
166
236
  private report;
237
+ /** A failed query as an error, in the query's own span so the error shows the query. */
238
+ private sendQueryError;
167
239
  /**
168
240
  * Uncaught exceptions and unhandled rejections, reported as unhandled.
169
241
  *
@@ -184,7 +256,7 @@ declare class ZharpNode {
184
256
  }
185
257
 
186
258
  /** Sent as `telemetry.sdk.version`. Bumped with package.json. */
187
- declare const VERSION = "0.2.0";
259
+ declare const VERSION = "0.4.0";
188
260
 
189
261
  declare const Zharp: ZharpNode;
190
262
 
package/dist/index.d.ts CHANGED
@@ -75,11 +75,36 @@ interface NodeOptions {
75
75
  */
76
76
  tracing?: boolean;
77
77
  /**
78
- * Send `console.*` output as logs. Default **true**: on a server, the console is where most
78
+ * Send what the application logs — `console`, pino, winston, bunyan and everything else it
79
+ * prints. Default **false**: where the Zharp agent reads the app's output it already brings
80
+ * those lines in, linked to their requests by the ids stamped on them (see `logCorrelation`).
81
+ * Turn it on where nothing else collects the output (serverless, a plain VM without the
82
+ * agent). Falls back to `ZHARP_LOGS` (`true` turns it on). Errors, `Zharp.log` and traces are
83
+ * sent either way. `captureConsole` and `captureOutput` refine what is sent when this is on.
84
+ */
85
+ logs?: boolean;
86
+ /**
87
+ * Stamp the request's ids on every line printed during it — `trace_id=… span_id=…` at the end
88
+ * of a text line, two fields in a JSON record — so Zharp links the line to its request
89
+ * whichever way it arrives. Default **true**. Falls back to `ZHARP_LOG_CORRELATION`.
90
+ */
91
+ logCorrelation?: boolean;
92
+ /**
93
+ * With `logs` on: send `console.*` output as logs. Default **true**: on a server, the console is where most
79
94
  * logging already goes. pino, winston and bunyan are bridged by their instrumentations
80
95
  * whatever this says.
81
96
  */
82
97
  captureConsole?: boolean;
98
+ /**
99
+ * With `logs` on: send everything else the process prints as logs too: whatever reaches stdout or stderr
100
+ * without going through `console` or a bridged library — NestJS's Logger, debug, log4js,
101
+ * libraries writing to `process.stdout` directly. Default **true**. Each line keeps the
102
+ * request it was printed in; its level is read from the line (a JSON record's `level`,
103
+ * NestJS's `LOG`/`WARN`/`ERROR`, a word such as `ERROR`), else info on stdout and warn on
104
+ * stderr. A line another capture already sent is not sent again. `false` (or
105
+ * `ZHARP_CAPTURE_OUTPUT=false`) turns it off.
106
+ */
107
+ captureOutput?: boolean;
83
108
  /**
84
109
  * Request and response bodies on HTTP spans — incoming requests and outgoing http/https
85
110
  * calls. Default **off**. `'errors'` (or `true`) keeps them for failed requests only (status
@@ -94,6 +119,30 @@ interface NodeOptions {
94
119
  * captureBodies: { mode: 'all', redactKeys: ['dateOfBirth'], urls: [/\/api\//] }
95
120
  */
96
121
  captureBodies?: CaptureBodies;
122
+ /**
123
+ * Request and response headers on HTTP spans (`http.request.header.user-agent`, …), incoming
124
+ * and outgoing. Default **on**. Secret headers — `authorization`, `cookie`, `set-cookie`, API
125
+ * keys, tokens, and any name matching the body key rules — are recorded as `[Filtered]`: you
126
+ * see that one was sent, never its value. Add names to `redact` to filter more. `false` (or
127
+ * `ZHARP_CAPTURE_HEADERS=false`) turns it off.
128
+ */
129
+ captureHeaders?: boolean | {
130
+ redact?: Array<string | RegExp>;
131
+ };
132
+ /**
133
+ * Failed database queries reported as errors, with the line of your code that ran the query
134
+ * as their stack, the statement, and the driver's code (Postgres 23505 → `UniqueViolation`).
135
+ * Default true.
136
+ */
137
+ captureQueryErrors?: boolean;
138
+ /**
139
+ * The code around each error's lines, read on this server from your own files (never
140
+ * node_modules) and sent with the error, so Zharp shows exactly the code that ran without a
141
+ * repository link. Built code (TypeScript, a NestJS dist/) is read through the .js.map files
142
+ * next to it: the stack and the code are your sources. The innermost five frames, five lines
143
+ * either side. Default true; ZHARP_CAPTURE_SOURCE_CONTEXT=false turns it off.
144
+ */
145
+ captureSourceContext?: boolean;
97
146
  /**
98
147
  * Capture uncaught exceptions and unhandled rejections. Default true. The process still
99
148
  * exits as Node would have, once they have been sent.
@@ -123,6 +172,8 @@ declare class ZharpNode {
123
172
  private tracing;
124
173
  /** Errors already sent, so one that is both rejected and then thrown is reported once. */
125
174
  private readonly reported;
175
+ /** Failed queries waiting to be reported, once and with their call site. */
176
+ private dbErrors;
126
177
  /** `Zharp.log.info("Order placed", { orderId })` — and debug, warn, error, fatal, trace. */
127
178
  readonly log: Record<Level, LogFn>;
128
179
  /** Whether `init()` started the SDK. */
@@ -153,6 +204,25 @@ declare class ZharpNode {
153
204
  * in, and grouped into an issue with every other occurrence.
154
205
  */
155
206
  captureError(error: unknown, attributes?: Attributes): void;
207
+ /**
208
+ * Next.js (15+): errors a route handler, server component, server action or middleware threw,
209
+ * which Next answers with an error page and only prints. Export it from instrumentation.ts:
210
+ *
211
+ * export const onRequestError = Zharp.onRequestError;
212
+ *
213
+ * Each is reported once as a crash, with the request's path, method and route. A bound function,
214
+ * so it can be exported as it is.
215
+ */
216
+ readonly onRequestError: (error: unknown, request?: {
217
+ path?: string;
218
+ method?: string;
219
+ headers?: Record<string, string | string[] | undefined>;
220
+ }, context?: {
221
+ routerKind?: string;
222
+ routePath?: string;
223
+ routeType?: string;
224
+ renderSource?: string;
225
+ }) => void;
156
226
  /**
157
227
  * Run `fn` inside a span named `name`, which ends when `fn` returns or its promise settles. A
158
228
  * throw or rejection marks the span as failed and is passed on unchanged.
@@ -164,6 +234,8 @@ declare class ZharpNode {
164
234
  shutdown(): Promise<void>;
165
235
  private emit;
166
236
  private report;
237
+ /** A failed query as an error, in the query's own span so the error shows the query. */
238
+ private sendQueryError;
167
239
  /**
168
240
  * Uncaught exceptions and unhandled rejections, reported as unhandled.
169
241
  *
@@ -184,7 +256,7 @@ declare class ZharpNode {
184
256
  }
185
257
 
186
258
  /** Sent as `telemetry.sdk.version`. Bumped with package.json. */
187
- declare const VERSION = "0.2.0";
259
+ declare const VERSION = "0.4.0";
188
260
 
189
261
  declare const Zharp: ZharpNode;
190
262