@zharp/node 0.0.0-stage → 0.2.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 +123 -3
- package/dist/index.d.mts +191 -0
- package/dist/index.d.ts +191 -0
- package/dist/index.js +1403 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1389 -0
- package/dist/index.mjs.map +1 -0
- package/init.d.ts +2 -0
- package/init.js +4 -0
- package/init.mjs +5 -0
- package/package.json +83 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zharp
|
|
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,123 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# @zharp/node
|
|
2
|
+
|
|
3
|
+
Application Monitoring for Node.js, for [Zharp](https://zharp.io): traces of every request your server handles and makes, its logs, and its errors — joined to the browser session and user that caused them.
|
|
4
|
+
|
|
5
|
+
It is the official [OpenTelemetry Node SDK](https://opentelemetry.io/docs/languages/js/) and its auto-instrumentations, configured for Zharp. Every span comes from OpenTelemetry's instrumentation of `http`, Express, Fastify, Koa, NestJS, pg, mysql, mongodb, redis, undici/fetch, gRPC, GraphQL, AWS SDK and the rest; this package adds the configuration, the user and session on every record, a console bridge, error capture and a small API.
|
|
6
|
+
|
|
7
|
+
Requires Node 22.15 or later (as OpenTelemetry does).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @zharp/node
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Create `instrument.js`:
|
|
16
|
+
|
|
17
|
+
```javascript
|
|
18
|
+
import { Zharp } from '@zharp/node';
|
|
19
|
+
|
|
20
|
+
Zharp.init({
|
|
21
|
+
key: process.env.ZHARP_KEY, // the app key from the dashboard
|
|
22
|
+
service: 'checkout-api',
|
|
23
|
+
environment: 'production',
|
|
24
|
+
release: process.env.GIT_SHA, // optional
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
and load it before your application:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
node --import ./instrument.js server.js
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
[Zharp] Application monitoring active — service "checkout-api", environment "production"
|
|
36
|
+
```
|
|
37
|
+
|
|
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
|
+
|
|
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).
|
|
41
|
+
|
|
42
|
+
### Next.js
|
|
43
|
+
|
|
44
|
+
`instrumentation.ts` in the project root (or `src/`):
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
export async function register() {
|
|
48
|
+
if (process.env.NEXT_RUNTIME === 'nodejs') {
|
|
49
|
+
const { Zharp } = await import('@zharp/node');
|
|
50
|
+
Zharp.init({ key: process.env.ZHARP_KEY!, service: 'checkout-web-server', environment: process.env.NODE_ENV });
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The Edge runtime is not supported. If the build complains about OpenTelemetry modules, add `serverExternalPackages: ['@zharp/node']` to `next.config`.
|
|
56
|
+
|
|
57
|
+
## What is captured
|
|
58
|
+
|
|
59
|
+
| | |
|
|
60
|
+
|---|---|
|
|
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
|
+
| **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. |
|
|
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
|
+
|
|
66
|
+
### Uncaught exceptions
|
|
67
|
+
|
|
68
|
+
Listening for `uncaughtException` / `unhandledRejection` stops Node from exiting, so when Zharp's listener is the only one it does what Node would have: prints the error to stderr and exits with code 1 — after the error has been sent (at most 2 seconds). If your application has its own listeners, they decide what happens and Zharp only reports. `--unhandled-rejections=warn|none|warn-with-error-code` are respected.
|
|
69
|
+
|
|
70
|
+
### Exit
|
|
71
|
+
|
|
72
|
+
What is waiting is sent when the event loop empties, and on SIGTERM/SIGINT (after which the signal is raised again if nothing else is listening for it). In serverless functions, `await Zharp.flush()` before returning.
|
|
73
|
+
|
|
74
|
+
### Logs only
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
Zharp.init({ tracing: false }); // or ZHARP_TRACING=false
|
|
78
|
+
```
|
|
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`.
|
|
81
|
+
|
|
82
|
+
## API
|
|
83
|
+
|
|
84
|
+
| | |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `Zharp.init(options)` | Start. Once per process; a second call is ignored with a warning. |
|
|
87
|
+
| `Zharp.setUser({ id, email?, name? })` | Inside a request: `enduser.id` (email, name) on every span and log of that request from here on, and on the request's span. Outside one: on everything the process sends — for a script or worker. Requests from `@zharp/browser` already carry the user. |
|
|
88
|
+
| `Zharp.clearUser()` | |
|
|
89
|
+
| `Zharp.setTag(key, value)` | An attribute on every span and log from now on. |
|
|
90
|
+
| `Zharp.captureError(err, attrs?)` | |
|
|
91
|
+
| `Zharp.log.<level>(message, attrs?)` | `trace`, `debug`, `info`, `warn`, `error`, `fatal`. An `Error` among the attributes of an error log is sent as its exception. |
|
|
92
|
+
| `Zharp.startSpan(name, fn, options?)` | Run `fn` in a span, ending when it returns or its promise settles. |
|
|
93
|
+
| `Zharp.flush(timeoutMs?)` | Send everything waiting. |
|
|
94
|
+
| `Zharp.shutdown()` | Flush and stop. |
|
|
95
|
+
|
|
96
|
+
Everything else is plain OpenTelemetry: `trace.getActiveSpan()`, `trace.getTracer('my-lib')` and the rest of `@opentelemetry/api` work as usual.
|
|
97
|
+
|
|
98
|
+
## Options
|
|
99
|
+
|
|
100
|
+
| Option | Default | |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| `key` | `ZHARP_API_KEY` | The app key (`zpk_…`) or a workspace API key with ingest scope. |
|
|
103
|
+
| `service` | `ZHARP_SERVICE`, `OTEL_SERVICE_NAME`, package.json name | `service.name` |
|
|
104
|
+
| `environment` | `ZHARP_ENV`, `NODE_ENV` | `deployment.environment.name` |
|
|
105
|
+
| `release` | `ZHARP_RELEASE` | `service.version` |
|
|
106
|
+
| `endpoint` | `https://api.zharp.io/api/v1/otlp` | |
|
|
107
|
+
| `tracing` | `ZHARP_TRACING`, else `true` | `false` for logs only (see above). |
|
|
108
|
+
| `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` | |
|
|
110
|
+
| `captureUncaught` | `true` | |
|
|
111
|
+
| `instrumentations` | | Per-instrumentation config for `getNodeAutoInstrumentations`, e.g. `{ '@opentelemetry/instrumentation-fs': { enabled: true } }`. |
|
|
112
|
+
| `extraInstrumentations` | `[]` | More OpenTelemetry instrumentations. |
|
|
113
|
+
| `debug` | `false` | Print what OpenTelemetry is doing. |
|
|
114
|
+
|
|
115
|
+
Traces and logs go as OTLP/protobuf, gzipped, to `{endpoint}/v1/traces` and `/v1/logs` with `Authorization: Bearer <key>`.
|
|
116
|
+
|
|
117
|
+
## Readable stack traces
|
|
118
|
+
|
|
119
|
+
Bundled or minified server code (a Next.js server build, an esbuild or webpack bundle) becomes original files, lines and code once its source maps are uploaded with a [Zharp bundler plugin](../bundler-plugins/README.md) or [`@zharp/cli`](../cli/README.md). Every error this SDK sends — `captureError`, error logs with an error, uncaught errors, exceptions recorded on spans by the instrumentations, and error logs from pino and winston — carries the debug IDs of the bundled files in its stack as `zharp.debug_ids`. Nothing to configure here.
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import { Span, SpanOptions } from '@opentelemetry/api';
|
|
2
|
+
import { InstrumentationConfigMap } from '@opentelemetry/auto-instrumentations-node';
|
|
3
|
+
import { Instrumentation } from '@opentelemetry/instrumentation';
|
|
4
|
+
|
|
5
|
+
/** OTLP severity numbers. */
|
|
6
|
+
declare const SEVERITY: {
|
|
7
|
+
readonly trace: 1;
|
|
8
|
+
readonly debug: 5;
|
|
9
|
+
readonly info: 9;
|
|
10
|
+
readonly warn: 13;
|
|
11
|
+
readonly error: 17;
|
|
12
|
+
readonly fatal: 21;
|
|
13
|
+
};
|
|
14
|
+
type Level = keyof typeof SEVERITY;
|
|
15
|
+
|
|
16
|
+
/** A value an attribute can hold. Objects and arrays are sent as they are and shown as JSON. */
|
|
17
|
+
type AttributeValue = string | number | boolean | null | undefined | AttributeValue[] | {
|
|
18
|
+
[key: string]: AttributeValue;
|
|
19
|
+
};
|
|
20
|
+
type Attributes = Record<string, unknown>;
|
|
21
|
+
interface ZharpUser {
|
|
22
|
+
/** Sent as `enduser.id`. An ID or an email — whatever identifies the person in your app. */
|
|
23
|
+
id: string | number;
|
|
24
|
+
/** Sent as `enduser.email`. */
|
|
25
|
+
email?: string;
|
|
26
|
+
/** Sent as `enduser.name`. */
|
|
27
|
+
name?: string;
|
|
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;
|
|
49
|
+
interface NodeOptions {
|
|
50
|
+
/**
|
|
51
|
+
* The app's key from the Zharp dashboard (`zpk_…`), or a workspace API key with the ingest
|
|
52
|
+
* scope. Falls back to `ZHARP_API_KEY`. Without one, `init()` starts nothing and says so.
|
|
53
|
+
*/
|
|
54
|
+
key?: string;
|
|
55
|
+
/** `service.name`. Falls back to `ZHARP_SERVICE`, `OTEL_SERVICE_NAME`, then package.json's name. */
|
|
56
|
+
service?: string;
|
|
57
|
+
/** `deployment.environment.name`. Falls back to `ZHARP_ENV`, then `NODE_ENV`. */
|
|
58
|
+
environment?: string;
|
|
59
|
+
/** `service.version`, e.g. `api@2.3.0` or a commit SHA. Falls back to `ZHARP_RELEASE`. */
|
|
60
|
+
release?: string;
|
|
61
|
+
/** Default `https://api.zharp.io/api/v1/otlp`. Falls back to `ZHARP_ENDPOINT`. */
|
|
62
|
+
endpoint?: string;
|
|
63
|
+
/**
|
|
64
|
+
* Fraction of traces to keep, 0 to 1. Default 1. A trace that arrives with a decision from
|
|
65
|
+
* the caller (the browser SDK's `traceparent`) keeps that decision. Errors and logs are always
|
|
66
|
+
* sent.
|
|
67
|
+
*/
|
|
68
|
+
sampleRate?: number;
|
|
69
|
+
/**
|
|
70
|
+
* Traces. Default **true**. `false` is logs only: logs, errors, user, session and tags are
|
|
71
|
+
* sent as usual, but no spans are exported, no http/database/framework instrumentation is
|
|
72
|
+
* installed, and no `traceparent` or `baggage` is added to outgoing requests. An incoming
|
|
73
|
+
* `traceparent` is still read, so the logs of a request carry the caller's trace id.
|
|
74
|
+
* `startSpan` just runs its callback. Falls back to `ZHARP_TRACING` (`false` turns it off).
|
|
75
|
+
*/
|
|
76
|
+
tracing?: boolean;
|
|
77
|
+
/**
|
|
78
|
+
* Send `console.*` output as logs. Default **true**: on a server, the console is where most
|
|
79
|
+
* logging already goes. pino, winston and bunyan are bridged by their instrumentations
|
|
80
|
+
* whatever this says.
|
|
81
|
+
*/
|
|
82
|
+
captureConsole?: boolean;
|
|
83
|
+
/**
|
|
84
|
+
* Request and response bodies on HTTP spans — incoming requests and outgoing http/https
|
|
85
|
+
* calls. Default **off**. `'errors'` (or `true`) keeps them for failed requests only (status
|
|
86
|
+
* 400 and above); `'all'` for every request. Falls back to `ZHARP_CAPTURE_BODIES`
|
|
87
|
+
* (`errors` or `all`). Text is capped at 32 KB; files in uploads, inline images and binary
|
|
88
|
+
* bodies are described (name, type, size), never sent. Field names are always kept; values
|
|
89
|
+
* under secret-looking keys (`password`, `token`, `authorization`, `card`, …) are replaced
|
|
90
|
+
* with `[Filtered]` before anything is sent. Other personal data in a body is sent as it is:
|
|
91
|
+
* add its keys to `redactKeys`.
|
|
92
|
+
*
|
|
93
|
+
* captureBodies: 'errors'
|
|
94
|
+
* captureBodies: { mode: 'all', redactKeys: ['dateOfBirth'], urls: [/\/api\//] }
|
|
95
|
+
*/
|
|
96
|
+
captureBodies?: CaptureBodies;
|
|
97
|
+
/**
|
|
98
|
+
* Capture uncaught exceptions and unhandled rejections. Default true. The process still
|
|
99
|
+
* exits as Node would have, once they have been sent.
|
|
100
|
+
*/
|
|
101
|
+
captureUncaught?: boolean;
|
|
102
|
+
/**
|
|
103
|
+
* Per-instrumentation settings, passed to `getNodeAutoInstrumentations`. `dns`, `net` and
|
|
104
|
+
* `fs` are off by default (a span per lookup, socket or file read is noise); turn one back on
|
|
105
|
+
* with `{ '@opentelemetry/instrumentation-dns': { enabled: true } }`.
|
|
106
|
+
*/
|
|
107
|
+
instrumentations?: InstrumentationConfigMap;
|
|
108
|
+
/** More instrumentations to register alongside the automatic ones. */
|
|
109
|
+
extraInstrumentations?: Instrumentation[];
|
|
110
|
+
/** Print what the SDK and OpenTelemetry are doing. Default false. */
|
|
111
|
+
debug?: boolean;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
type LogFn = (message: unknown, attributes?: Attributes) => void;
|
|
115
|
+
declare class ZharpNode {
|
|
116
|
+
private sdk;
|
|
117
|
+
private spanProcessors;
|
|
118
|
+
private logProcessors;
|
|
119
|
+
private logger;
|
|
120
|
+
private readonly store;
|
|
121
|
+
private teardowns;
|
|
122
|
+
/** False in logs-only mode (`tracing: false` / `ZHARP_TRACING=false`). */
|
|
123
|
+
private tracing;
|
|
124
|
+
/** Errors already sent, so one that is both rejected and then thrown is reported once. */
|
|
125
|
+
private readonly reported;
|
|
126
|
+
/** `Zharp.log.info("Order placed", { orderId })` — and debug, warn, error, fatal, trace. */
|
|
127
|
+
readonly log: Record<Level, LogFn>;
|
|
128
|
+
/** Whether `init()` started the SDK. */
|
|
129
|
+
get isActive(): boolean;
|
|
130
|
+
/**
|
|
131
|
+
* Start sending traces, logs and errors. Call it once, before the application's own modules
|
|
132
|
+
* load — from a file preloaded with `node --import` (see the README) — so that http, the
|
|
133
|
+
* database drivers and the frameworks are instrumented when they are first imported.
|
|
134
|
+
*/
|
|
135
|
+
init(options?: NodeOptions): void;
|
|
136
|
+
private start;
|
|
137
|
+
/**
|
|
138
|
+
* The user the current request is for: `enduser.id` (and `enduser.email`, `enduser.name`) on
|
|
139
|
+
* every span and log of the request from here on, and on the request's own span. Outside a
|
|
140
|
+
* request it applies to everything the process sends — for a script or a worker that runs as
|
|
141
|
+
* one user.
|
|
142
|
+
*
|
|
143
|
+
* Requests from a page running @zharp/browser already carry the user in their baggage; this
|
|
144
|
+
* is for servers that know the user themselves.
|
|
145
|
+
*/
|
|
146
|
+
setUser(user: ZharpUser | null): void;
|
|
147
|
+
/** Forget the user — for the current request, or the process's when called outside one. */
|
|
148
|
+
clearUser(): void;
|
|
149
|
+
/** An attribute on every span and log sent from now on, e.g. `setTag("region", "eu-west-1")`. */
|
|
150
|
+
setTag(key: string, value: string | number | boolean | null | undefined): void;
|
|
151
|
+
/**
|
|
152
|
+
* Report an error you caught. It is sent as handled, in the trace of the request it happened
|
|
153
|
+
* in, and grouped into an issue with every other occurrence.
|
|
154
|
+
*/
|
|
155
|
+
captureError(error: unknown, attributes?: Attributes): void;
|
|
156
|
+
/**
|
|
157
|
+
* Run `fn` inside a span named `name`, which ends when `fn` returns or its promise settles. A
|
|
158
|
+
* throw or rejection marks the span as failed and is passed on unchanged.
|
|
159
|
+
*/
|
|
160
|
+
startSpan<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T;
|
|
161
|
+
/** Send everything waiting now. Await it before a serverless function returns. */
|
|
162
|
+
flush(timeoutMs?: number): Promise<void>;
|
|
163
|
+
/** Flush, stop, and put back everything that was patched. */
|
|
164
|
+
shutdown(): Promise<void>;
|
|
165
|
+
private emit;
|
|
166
|
+
private report;
|
|
167
|
+
/**
|
|
168
|
+
* Uncaught exceptions and unhandled rejections, reported as unhandled.
|
|
169
|
+
*
|
|
170
|
+
* Listening for either changes what Node does — it no longer exits — so when Zharp's listener
|
|
171
|
+
* is the only one, it finishes the job the way Node would have: print the error, then exit
|
|
172
|
+
* with code 1, after the error has been sent. When the application has listeners of its own,
|
|
173
|
+
* they decide, and Zharp only reports.
|
|
174
|
+
*/
|
|
175
|
+
private captureProcessErrors;
|
|
176
|
+
private crashing;
|
|
177
|
+
private crash;
|
|
178
|
+
/**
|
|
179
|
+
* Send what is waiting when the process ends on its own (the event loop drains) or is told to
|
|
180
|
+
* stop. A signal listener also replaces Node's default of exiting, so once the flush is done,
|
|
181
|
+
* if no one else is listening, the signal is raised again with Zharp's listener gone.
|
|
182
|
+
*/
|
|
183
|
+
private flushOnExit;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Sent as `telemetry.sdk.version`. Bumped with package.json. */
|
|
187
|
+
declare const VERSION = "0.2.0";
|
|
188
|
+
|
|
189
|
+
declare const Zharp: ZharpNode;
|
|
190
|
+
|
|
191
|
+
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import { Span, SpanOptions } from '@opentelemetry/api';
|
|
2
|
+
import { InstrumentationConfigMap } from '@opentelemetry/auto-instrumentations-node';
|
|
3
|
+
import { Instrumentation } from '@opentelemetry/instrumentation';
|
|
4
|
+
|
|
5
|
+
/** OTLP severity numbers. */
|
|
6
|
+
declare const SEVERITY: {
|
|
7
|
+
readonly trace: 1;
|
|
8
|
+
readonly debug: 5;
|
|
9
|
+
readonly info: 9;
|
|
10
|
+
readonly warn: 13;
|
|
11
|
+
readonly error: 17;
|
|
12
|
+
readonly fatal: 21;
|
|
13
|
+
};
|
|
14
|
+
type Level = keyof typeof SEVERITY;
|
|
15
|
+
|
|
16
|
+
/** A value an attribute can hold. Objects and arrays are sent as they are and shown as JSON. */
|
|
17
|
+
type AttributeValue = string | number | boolean | null | undefined | AttributeValue[] | {
|
|
18
|
+
[key: string]: AttributeValue;
|
|
19
|
+
};
|
|
20
|
+
type Attributes = Record<string, unknown>;
|
|
21
|
+
interface ZharpUser {
|
|
22
|
+
/** Sent as `enduser.id`. An ID or an email — whatever identifies the person in your app. */
|
|
23
|
+
id: string | number;
|
|
24
|
+
/** Sent as `enduser.email`. */
|
|
25
|
+
email?: string;
|
|
26
|
+
/** Sent as `enduser.name`. */
|
|
27
|
+
name?: string;
|
|
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;
|
|
49
|
+
interface NodeOptions {
|
|
50
|
+
/**
|
|
51
|
+
* The app's key from the Zharp dashboard (`zpk_…`), or a workspace API key with the ingest
|
|
52
|
+
* scope. Falls back to `ZHARP_API_KEY`. Without one, `init()` starts nothing and says so.
|
|
53
|
+
*/
|
|
54
|
+
key?: string;
|
|
55
|
+
/** `service.name`. Falls back to `ZHARP_SERVICE`, `OTEL_SERVICE_NAME`, then package.json's name. */
|
|
56
|
+
service?: string;
|
|
57
|
+
/** `deployment.environment.name`. Falls back to `ZHARP_ENV`, then `NODE_ENV`. */
|
|
58
|
+
environment?: string;
|
|
59
|
+
/** `service.version`, e.g. `api@2.3.0` or a commit SHA. Falls back to `ZHARP_RELEASE`. */
|
|
60
|
+
release?: string;
|
|
61
|
+
/** Default `https://api.zharp.io/api/v1/otlp`. Falls back to `ZHARP_ENDPOINT`. */
|
|
62
|
+
endpoint?: string;
|
|
63
|
+
/**
|
|
64
|
+
* Fraction of traces to keep, 0 to 1. Default 1. A trace that arrives with a decision from
|
|
65
|
+
* the caller (the browser SDK's `traceparent`) keeps that decision. Errors and logs are always
|
|
66
|
+
* sent.
|
|
67
|
+
*/
|
|
68
|
+
sampleRate?: number;
|
|
69
|
+
/**
|
|
70
|
+
* Traces. Default **true**. `false` is logs only: logs, errors, user, session and tags are
|
|
71
|
+
* sent as usual, but no spans are exported, no http/database/framework instrumentation is
|
|
72
|
+
* installed, and no `traceparent` or `baggage` is added to outgoing requests. An incoming
|
|
73
|
+
* `traceparent` is still read, so the logs of a request carry the caller's trace id.
|
|
74
|
+
* `startSpan` just runs its callback. Falls back to `ZHARP_TRACING` (`false` turns it off).
|
|
75
|
+
*/
|
|
76
|
+
tracing?: boolean;
|
|
77
|
+
/**
|
|
78
|
+
* Send `console.*` output as logs. Default **true**: on a server, the console is where most
|
|
79
|
+
* logging already goes. pino, winston and bunyan are bridged by their instrumentations
|
|
80
|
+
* whatever this says.
|
|
81
|
+
*/
|
|
82
|
+
captureConsole?: boolean;
|
|
83
|
+
/**
|
|
84
|
+
* Request and response bodies on HTTP spans — incoming requests and outgoing http/https
|
|
85
|
+
* calls. Default **off**. `'errors'` (or `true`) keeps them for failed requests only (status
|
|
86
|
+
* 400 and above); `'all'` for every request. Falls back to `ZHARP_CAPTURE_BODIES`
|
|
87
|
+
* (`errors` or `all`). Text is capped at 32 KB; files in uploads, inline images and binary
|
|
88
|
+
* bodies are described (name, type, size), never sent. Field names are always kept; values
|
|
89
|
+
* under secret-looking keys (`password`, `token`, `authorization`, `card`, …) are replaced
|
|
90
|
+
* with `[Filtered]` before anything is sent. Other personal data in a body is sent as it is:
|
|
91
|
+
* add its keys to `redactKeys`.
|
|
92
|
+
*
|
|
93
|
+
* captureBodies: 'errors'
|
|
94
|
+
* captureBodies: { mode: 'all', redactKeys: ['dateOfBirth'], urls: [/\/api\//] }
|
|
95
|
+
*/
|
|
96
|
+
captureBodies?: CaptureBodies;
|
|
97
|
+
/**
|
|
98
|
+
* Capture uncaught exceptions and unhandled rejections. Default true. The process still
|
|
99
|
+
* exits as Node would have, once they have been sent.
|
|
100
|
+
*/
|
|
101
|
+
captureUncaught?: boolean;
|
|
102
|
+
/**
|
|
103
|
+
* Per-instrumentation settings, passed to `getNodeAutoInstrumentations`. `dns`, `net` and
|
|
104
|
+
* `fs` are off by default (a span per lookup, socket or file read is noise); turn one back on
|
|
105
|
+
* with `{ '@opentelemetry/instrumentation-dns': { enabled: true } }`.
|
|
106
|
+
*/
|
|
107
|
+
instrumentations?: InstrumentationConfigMap;
|
|
108
|
+
/** More instrumentations to register alongside the automatic ones. */
|
|
109
|
+
extraInstrumentations?: Instrumentation[];
|
|
110
|
+
/** Print what the SDK and OpenTelemetry are doing. Default false. */
|
|
111
|
+
debug?: boolean;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
type LogFn = (message: unknown, attributes?: Attributes) => void;
|
|
115
|
+
declare class ZharpNode {
|
|
116
|
+
private sdk;
|
|
117
|
+
private spanProcessors;
|
|
118
|
+
private logProcessors;
|
|
119
|
+
private logger;
|
|
120
|
+
private readonly store;
|
|
121
|
+
private teardowns;
|
|
122
|
+
/** False in logs-only mode (`tracing: false` / `ZHARP_TRACING=false`). */
|
|
123
|
+
private tracing;
|
|
124
|
+
/** Errors already sent, so one that is both rejected and then thrown is reported once. */
|
|
125
|
+
private readonly reported;
|
|
126
|
+
/** `Zharp.log.info("Order placed", { orderId })` — and debug, warn, error, fatal, trace. */
|
|
127
|
+
readonly log: Record<Level, LogFn>;
|
|
128
|
+
/** Whether `init()` started the SDK. */
|
|
129
|
+
get isActive(): boolean;
|
|
130
|
+
/**
|
|
131
|
+
* Start sending traces, logs and errors. Call it once, before the application's own modules
|
|
132
|
+
* load — from a file preloaded with `node --import` (see the README) — so that http, the
|
|
133
|
+
* database drivers and the frameworks are instrumented when they are first imported.
|
|
134
|
+
*/
|
|
135
|
+
init(options?: NodeOptions): void;
|
|
136
|
+
private start;
|
|
137
|
+
/**
|
|
138
|
+
* The user the current request is for: `enduser.id` (and `enduser.email`, `enduser.name`) on
|
|
139
|
+
* every span and log of the request from here on, and on the request's own span. Outside a
|
|
140
|
+
* request it applies to everything the process sends — for a script or a worker that runs as
|
|
141
|
+
* one user.
|
|
142
|
+
*
|
|
143
|
+
* Requests from a page running @zharp/browser already carry the user in their baggage; this
|
|
144
|
+
* is for servers that know the user themselves.
|
|
145
|
+
*/
|
|
146
|
+
setUser(user: ZharpUser | null): void;
|
|
147
|
+
/** Forget the user — for the current request, or the process's when called outside one. */
|
|
148
|
+
clearUser(): void;
|
|
149
|
+
/** An attribute on every span and log sent from now on, e.g. `setTag("region", "eu-west-1")`. */
|
|
150
|
+
setTag(key: string, value: string | number | boolean | null | undefined): void;
|
|
151
|
+
/**
|
|
152
|
+
* Report an error you caught. It is sent as handled, in the trace of the request it happened
|
|
153
|
+
* in, and grouped into an issue with every other occurrence.
|
|
154
|
+
*/
|
|
155
|
+
captureError(error: unknown, attributes?: Attributes): void;
|
|
156
|
+
/**
|
|
157
|
+
* Run `fn` inside a span named `name`, which ends when `fn` returns or its promise settles. A
|
|
158
|
+
* throw or rejection marks the span as failed and is passed on unchanged.
|
|
159
|
+
*/
|
|
160
|
+
startSpan<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T;
|
|
161
|
+
/** Send everything waiting now. Await it before a serverless function returns. */
|
|
162
|
+
flush(timeoutMs?: number): Promise<void>;
|
|
163
|
+
/** Flush, stop, and put back everything that was patched. */
|
|
164
|
+
shutdown(): Promise<void>;
|
|
165
|
+
private emit;
|
|
166
|
+
private report;
|
|
167
|
+
/**
|
|
168
|
+
* Uncaught exceptions and unhandled rejections, reported as unhandled.
|
|
169
|
+
*
|
|
170
|
+
* Listening for either changes what Node does — it no longer exits — so when Zharp's listener
|
|
171
|
+
* is the only one, it finishes the job the way Node would have: print the error, then exit
|
|
172
|
+
* with code 1, after the error has been sent. When the application has listeners of its own,
|
|
173
|
+
* they decide, and Zharp only reports.
|
|
174
|
+
*/
|
|
175
|
+
private captureProcessErrors;
|
|
176
|
+
private crashing;
|
|
177
|
+
private crash;
|
|
178
|
+
/**
|
|
179
|
+
* Send what is waiting when the process ends on its own (the event loop drains) or is told to
|
|
180
|
+
* stop. A signal listener also replaces Node's default of exiting, so once the flush is done,
|
|
181
|
+
* if no one else is listening, the signal is raised again with Zharp's listener gone.
|
|
182
|
+
*/
|
|
183
|
+
private flushOnExit;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Sent as `telemetry.sdk.version`. Bumped with package.json. */
|
|
187
|
+
declare const VERSION = "0.2.0";
|
|
188
|
+
|
|
189
|
+
declare const Zharp: ZharpNode;
|
|
190
|
+
|
|
191
|
+
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|