@zharp/node 0.1.0 → 0.3.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 +8 -6
- package/dist/index.d.mts +62 -3
- package/dist/index.d.ts +62 -3
- package/dist/index.js +882 -12
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +879 -9
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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`, `
|
|
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.
|
|
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
|
-
| `
|
|
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
|
|
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
|
@@ -26,6 +26,26 @@ interface ZharpUser {
|
|
|
26
26
|
/** Sent as `enduser.name`. */
|
|
27
27
|
name?: string;
|
|
28
28
|
}
|
|
29
|
+
/** `captureBodies`: which request and response bodies go on HTTP spans. */
|
|
30
|
+
interface CaptureBodiesOptions {
|
|
31
|
+
/** `errors` (default): failed requests only (status 400 and above). `all`: every request. */
|
|
32
|
+
mode?: 'errors' | 'all';
|
|
33
|
+
/** Characters kept per body. Default 32768 (32 KB), at most 131072 (128 KB). */
|
|
34
|
+
maxSize?: number;
|
|
35
|
+
/**
|
|
36
|
+
* More keys whose values are replaced with `[Filtered]`, on top of the built-in ones. A string
|
|
37
|
+
* matches a key ignoring case, `-` and `_`; a RegExp is tested against the key as it is.
|
|
38
|
+
*/
|
|
39
|
+
redactKeys?: Array<string | RegExp>;
|
|
40
|
+
/**
|
|
41
|
+
* Which requests (incoming and outgoing) have their bodies captured: a bare host matches that
|
|
42
|
+
* host, a string with a scheme matches URLs starting with it, a RegExp is tested against the
|
|
43
|
+
* full URL. Default: all of them.
|
|
44
|
+
*/
|
|
45
|
+
urls?: Array<string | RegExp>;
|
|
46
|
+
}
|
|
47
|
+
/** `true` is `'errors'`. */
|
|
48
|
+
type CaptureBodies = boolean | 'errors' | 'all' | CaptureBodiesOptions;
|
|
29
49
|
interface NodeOptions {
|
|
30
50
|
/**
|
|
31
51
|
* The app's key from the Zharp dashboard (`zpk_…`), or a workspace API key with the ingest
|
|
@@ -55,11 +75,50 @@ interface NodeOptions {
|
|
|
55
75
|
*/
|
|
56
76
|
tracing?: boolean;
|
|
57
77
|
/**
|
|
58
|
-
* Send
|
|
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
|
|
59
94
|
* logging already goes. pino, winston and bunyan are bridged by their instrumentations
|
|
60
95
|
* whatever this says.
|
|
61
96
|
*/
|
|
62
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;
|
|
108
|
+
/**
|
|
109
|
+
* Request and response bodies on HTTP spans — incoming requests and outgoing http/https
|
|
110
|
+
* calls. Default **off**. `'errors'` (or `true`) keeps them for failed requests only (status
|
|
111
|
+
* 400 and above); `'all'` for every request. Falls back to `ZHARP_CAPTURE_BODIES`
|
|
112
|
+
* (`errors` or `all`). Text is capped at 32 KB; files in uploads, inline images and binary
|
|
113
|
+
* bodies are described (name, type, size), never sent. Field names are always kept; values
|
|
114
|
+
* under secret-looking keys (`password`, `token`, `authorization`, `card`, …) are replaced
|
|
115
|
+
* with `[Filtered]` before anything is sent. Other personal data in a body is sent as it is:
|
|
116
|
+
* add its keys to `redactKeys`.
|
|
117
|
+
*
|
|
118
|
+
* captureBodies: 'errors'
|
|
119
|
+
* captureBodies: { mode: 'all', redactKeys: ['dateOfBirth'], urls: [/\/api\//] }
|
|
120
|
+
*/
|
|
121
|
+
captureBodies?: CaptureBodies;
|
|
63
122
|
/**
|
|
64
123
|
* Capture uncaught exceptions and unhandled rejections. Default true. The process still
|
|
65
124
|
* exits as Node would have, once they have been sent.
|
|
@@ -150,8 +209,8 @@ declare class ZharpNode {
|
|
|
150
209
|
}
|
|
151
210
|
|
|
152
211
|
/** Sent as `telemetry.sdk.version`. Bumped with package.json. */
|
|
153
|
-
declare const VERSION = "0.
|
|
212
|
+
declare const VERSION = "0.3.0";
|
|
154
213
|
|
|
155
214
|
declare const Zharp: ZharpNode;
|
|
156
215
|
|
|
157
|
-
export { type AttributeValue, type Attributes, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
|
216
|
+
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
package/dist/index.d.ts
CHANGED
|
@@ -26,6 +26,26 @@ interface ZharpUser {
|
|
|
26
26
|
/** Sent as `enduser.name`. */
|
|
27
27
|
name?: string;
|
|
28
28
|
}
|
|
29
|
+
/** `captureBodies`: which request and response bodies go on HTTP spans. */
|
|
30
|
+
interface CaptureBodiesOptions {
|
|
31
|
+
/** `errors` (default): failed requests only (status 400 and above). `all`: every request. */
|
|
32
|
+
mode?: 'errors' | 'all';
|
|
33
|
+
/** Characters kept per body. Default 32768 (32 KB), at most 131072 (128 KB). */
|
|
34
|
+
maxSize?: number;
|
|
35
|
+
/**
|
|
36
|
+
* More keys whose values are replaced with `[Filtered]`, on top of the built-in ones. A string
|
|
37
|
+
* matches a key ignoring case, `-` and `_`; a RegExp is tested against the key as it is.
|
|
38
|
+
*/
|
|
39
|
+
redactKeys?: Array<string | RegExp>;
|
|
40
|
+
/**
|
|
41
|
+
* Which requests (incoming and outgoing) have their bodies captured: a bare host matches that
|
|
42
|
+
* host, a string with a scheme matches URLs starting with it, a RegExp is tested against the
|
|
43
|
+
* full URL. Default: all of them.
|
|
44
|
+
*/
|
|
45
|
+
urls?: Array<string | RegExp>;
|
|
46
|
+
}
|
|
47
|
+
/** `true` is `'errors'`. */
|
|
48
|
+
type CaptureBodies = boolean | 'errors' | 'all' | CaptureBodiesOptions;
|
|
29
49
|
interface NodeOptions {
|
|
30
50
|
/**
|
|
31
51
|
* The app's key from the Zharp dashboard (`zpk_…`), or a workspace API key with the ingest
|
|
@@ -55,11 +75,50 @@ interface NodeOptions {
|
|
|
55
75
|
*/
|
|
56
76
|
tracing?: boolean;
|
|
57
77
|
/**
|
|
58
|
-
* Send
|
|
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
|
|
59
94
|
* logging already goes. pino, winston and bunyan are bridged by their instrumentations
|
|
60
95
|
* whatever this says.
|
|
61
96
|
*/
|
|
62
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;
|
|
108
|
+
/**
|
|
109
|
+
* Request and response bodies on HTTP spans — incoming requests and outgoing http/https
|
|
110
|
+
* calls. Default **off**. `'errors'` (or `true`) keeps them for failed requests only (status
|
|
111
|
+
* 400 and above); `'all'` for every request. Falls back to `ZHARP_CAPTURE_BODIES`
|
|
112
|
+
* (`errors` or `all`). Text is capped at 32 KB; files in uploads, inline images and binary
|
|
113
|
+
* bodies are described (name, type, size), never sent. Field names are always kept; values
|
|
114
|
+
* under secret-looking keys (`password`, `token`, `authorization`, `card`, …) are replaced
|
|
115
|
+
* with `[Filtered]` before anything is sent. Other personal data in a body is sent as it is:
|
|
116
|
+
* add its keys to `redactKeys`.
|
|
117
|
+
*
|
|
118
|
+
* captureBodies: 'errors'
|
|
119
|
+
* captureBodies: { mode: 'all', redactKeys: ['dateOfBirth'], urls: [/\/api\//] }
|
|
120
|
+
*/
|
|
121
|
+
captureBodies?: CaptureBodies;
|
|
63
122
|
/**
|
|
64
123
|
* Capture uncaught exceptions and unhandled rejections. Default true. The process still
|
|
65
124
|
* exits as Node would have, once they have been sent.
|
|
@@ -150,8 +209,8 @@ declare class ZharpNode {
|
|
|
150
209
|
}
|
|
151
210
|
|
|
152
211
|
/** Sent as `telemetry.sdk.version`. Bumped with package.json. */
|
|
153
|
-
declare const VERSION = "0.
|
|
212
|
+
declare const VERSION = "0.3.0";
|
|
154
213
|
|
|
155
214
|
declare const Zharp: ZharpNode;
|
|
156
215
|
|
|
157
|
-
export { type AttributeValue, type Attributes, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
|
216
|
+
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|