@zharp/node 0.4.0 → 0.5.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 +22 -1
- package/dist/index.d.mts +60 -2
- package/dist/index.d.ts +60 -2
- package/dist/index.js +569 -9
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +573 -11
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -69,7 +69,25 @@ Listening for `uncaughtException` / `unhandledRejection` stops Node from exiting
|
|
|
69
69
|
|
|
70
70
|
### Exit
|
|
71
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.
|
|
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, wrap the handler (below) — or `await Zharp.flush()` before returning.
|
|
73
|
+
|
|
74
|
+
### Serverless functions
|
|
75
|
+
|
|
76
|
+
A function's process is frozen as soon as the handler returns, so wrap the handler. Each invocation becomes one SERVER span with the FaaS attributes (`faas.trigger`, `faas.invocation_id`, `faas.coldstart`, `faas.name`, `cloud.provider`), continuing the caller's trace when the trigger carries a `traceparent` (API Gateway, HTTP triggers, a CloudEvent's tracing extension). An error the handler throws is reported once and thrown on unchanged. Everything is flushed before the result goes back — for at most `flushTimeout` (2 s by default; on Lambda never past the invocation's remaining time). The wrapped handler has the same arguments and result as yours. Call `Zharp.init()` at the top of the handler's module, with `logs: true` if the function's console output should be sent too (nothing else collects it there).
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
// AWS Lambda (async, callback or streamifyResponse handlers)
|
|
80
|
+
export const handler = Zharp.lambda(async (event, context) => ({ statusCode: 200, body: 'ok' }));
|
|
81
|
+
|
|
82
|
+
// Azure Functions, v4 programming model (any trigger)
|
|
83
|
+
app.http('orders', { handler: Zharp.azureFunction(async (request, context) => ({ status: 200 })) });
|
|
84
|
+
|
|
85
|
+
// Google Cloud Functions: HTTP, CloudEvent or background functions
|
|
86
|
+
functions.http('orders', Zharp.cloudFunction((req, res) => res.send('ok')));
|
|
87
|
+
functions.cloudEvent('onMessage', Zharp.cloudFunction(async (cloudEvent) => { /* … */ }));
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
On Cloud Functions the response is held until the flush is done (the CPU may be stopped once it is out), and the wrapper makes the request's span itself, so the http instrumentation leaves incoming requests alone from the moment a function is wrapped. On Lambda, OpenTelemetry's own `aws-lambda` instrumentation is off (it would make a second span); `Zharp.lambda` replaces it. Running on Lambda, Azure Functions or Cloud Functions also puts `cloud.provider`, `cloud.platform`, `cloud.region` and `faas.*` on the resource, and the function's name is the default `service.name`.
|
|
73
91
|
|
|
74
92
|
### Logs only
|
|
75
93
|
|
|
@@ -90,6 +108,9 @@ Logs (`Zharp.log.*`, and with `logs: true` the console, pino, winston, bunyan),
|
|
|
90
108
|
| `Zharp.captureError(err, attrs?)` | |
|
|
91
109
|
| `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
110
|
| `Zharp.startSpan(name, fn, options?)` | Run `fn` in a span, ending when it returns or its promise settles. |
|
|
111
|
+
| `Zharp.lambda(handler, { flushTimeout? })` | An AWS Lambda handler, traced and flushed per invocation. See [Serverless functions](#serverless-functions). |
|
|
112
|
+
| `Zharp.azureFunction(handler, { flushTimeout? })` | The same for an Azure Functions handler. |
|
|
113
|
+
| `Zharp.cloudFunction(handler, { flushTimeout? })` | The same for a Google Cloud Function (HTTP, CloudEvent or background). |
|
|
93
114
|
| `Zharp.flush(timeoutMs?)` | Send everything waiting. |
|
|
94
115
|
| `Zharp.shutdown()` | Flush and stop. |
|
|
95
116
|
|
package/dist/index.d.mts
CHANGED
|
@@ -160,6 +160,14 @@ interface NodeOptions {
|
|
|
160
160
|
debug?: boolean;
|
|
161
161
|
}
|
|
162
162
|
|
|
163
|
+
interface ServerlessOptions {
|
|
164
|
+
/**
|
|
165
|
+
* How long the flush after each invocation may hold the function up, in milliseconds.
|
|
166
|
+
* Default 2000. On Lambda it is also kept inside the invocation's remaining time.
|
|
167
|
+
*/
|
|
168
|
+
flushTimeout?: number;
|
|
169
|
+
}
|
|
170
|
+
|
|
163
171
|
type LogFn = (message: unknown, attributes?: Attributes) => void;
|
|
164
172
|
declare class ZharpNode {
|
|
165
173
|
private sdk;
|
|
@@ -174,6 +182,13 @@ declare class ZharpNode {
|
|
|
174
182
|
private readonly reported;
|
|
175
183
|
/** Failed queries waiting to be reported, once and with their call site. */
|
|
176
184
|
private dbErrors;
|
|
185
|
+
/** No invocation has run in this process yet: the next one is the cold start. */
|
|
186
|
+
private cold;
|
|
187
|
+
/**
|
|
188
|
+
* A Cloud Function is wrapped: its wrapper makes each request's span (and flushes before the
|
|
189
|
+
* response), so the http server instrumentation leaves incoming requests alone.
|
|
190
|
+
*/
|
|
191
|
+
private wrapsHttp;
|
|
177
192
|
/** `Zharp.log.info("Order placed", { orderId })` — and debug, warn, error, fatal, trace. */
|
|
178
193
|
readonly log: Record<Level, LogFn>;
|
|
179
194
|
/** Whether `init()` started the SDK. */
|
|
@@ -230,6 +245,49 @@ declare class ZharpNode {
|
|
|
230
245
|
startSpan<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T;
|
|
231
246
|
/** Send everything waiting now. Await it before a serverless function returns. */
|
|
232
247
|
flush(timeoutMs?: number): Promise<void>;
|
|
248
|
+
/**
|
|
249
|
+
* An AWS Lambda handler (async, callback, or `awslambda.streamifyResponse`):
|
|
250
|
+
*
|
|
251
|
+
* export const handler = Zharp.lambda(async (event, context) => { … });
|
|
252
|
+
*/
|
|
253
|
+
lambda<H extends (...args: any[]) => any>(handler: H, options?: ServerlessOptions): H;
|
|
254
|
+
/**
|
|
255
|
+
* An Azure Functions handler, v4 programming model (`(request, context)`, any trigger) or v3
|
|
256
|
+
* (`(context, req)`):
|
|
257
|
+
*
|
|
258
|
+
* app.http('orders', { handler: Zharp.azureFunction(async (request, context) => { … }) });
|
|
259
|
+
*/
|
|
260
|
+
azureFunction<H extends (...args: any[]) => any>(handler: H, options?: ServerlessOptions): H;
|
|
261
|
+
/**
|
|
262
|
+
* A Google Cloud Function: an HTTP function `(req, res)`, a CloudEvent function `(cloudEvent)`,
|
|
263
|
+
* or a background function `(data, context)`.
|
|
264
|
+
*
|
|
265
|
+
* functions.http('orders', Zharp.cloudFunction((req, res) => { … }));
|
|
266
|
+
*
|
|
267
|
+
* An HTTP function's response is held until everything is sent — Cloud Functions may stop
|
|
268
|
+
* the instance's CPU the moment the response is out.
|
|
269
|
+
*/
|
|
270
|
+
cloudFunction<H extends (...args: any[]) => any>(handler: H, options?: ServerlessOptions): H;
|
|
271
|
+
/** The first invocation in the process is the cold start (not under provisioned concurrency). */
|
|
272
|
+
private takeColdstart;
|
|
273
|
+
/** The http instrumentation's config, leaving incoming requests to a wrapped Cloud Function. */
|
|
274
|
+
private withWrappedRequests;
|
|
275
|
+
/** The invocation's span, in a context of its own: the caller's trace, or a new one. */
|
|
276
|
+
private beginInvocation;
|
|
277
|
+
/** Report what the handler threw, in its invocation, and fail the span. Once per error. */
|
|
278
|
+
private invocationFailed;
|
|
279
|
+
/** End the invocation's span, then send everything waiting, within the budget. */
|
|
280
|
+
private endInvocation;
|
|
281
|
+
/**
|
|
282
|
+
* Run a handler as one invocation. Its result (a value, a promise, or what it passes to its
|
|
283
|
+
* callback) comes back unchanged — after the span has ended and been flushed.
|
|
284
|
+
*/
|
|
285
|
+
private runInvocation;
|
|
286
|
+
/**
|
|
287
|
+
* An HTTP function `(req, res)`: the invocation ends with the response. `res.end` is held
|
|
288
|
+
* until the span has ended and everything is flushed, then goes out as the handler wrote it.
|
|
289
|
+
*/
|
|
290
|
+
private runHttpFunction;
|
|
233
291
|
/** Flush, stop, and put back everything that was patched. */
|
|
234
292
|
shutdown(): Promise<void>;
|
|
235
293
|
private emit;
|
|
@@ -256,8 +314,8 @@ declare class ZharpNode {
|
|
|
256
314
|
}
|
|
257
315
|
|
|
258
316
|
/** Sent as `telemetry.sdk.version`. Bumped with package.json. */
|
|
259
|
-
declare const VERSION = "0.
|
|
317
|
+
declare const VERSION = "0.5.0";
|
|
260
318
|
|
|
261
319
|
declare const Zharp: ZharpNode;
|
|
262
320
|
|
|
263
|
-
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
|
321
|
+
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, type ServerlessOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
package/dist/index.d.ts
CHANGED
|
@@ -160,6 +160,14 @@ interface NodeOptions {
|
|
|
160
160
|
debug?: boolean;
|
|
161
161
|
}
|
|
162
162
|
|
|
163
|
+
interface ServerlessOptions {
|
|
164
|
+
/**
|
|
165
|
+
* How long the flush after each invocation may hold the function up, in milliseconds.
|
|
166
|
+
* Default 2000. On Lambda it is also kept inside the invocation's remaining time.
|
|
167
|
+
*/
|
|
168
|
+
flushTimeout?: number;
|
|
169
|
+
}
|
|
170
|
+
|
|
163
171
|
type LogFn = (message: unknown, attributes?: Attributes) => void;
|
|
164
172
|
declare class ZharpNode {
|
|
165
173
|
private sdk;
|
|
@@ -174,6 +182,13 @@ declare class ZharpNode {
|
|
|
174
182
|
private readonly reported;
|
|
175
183
|
/** Failed queries waiting to be reported, once and with their call site. */
|
|
176
184
|
private dbErrors;
|
|
185
|
+
/** No invocation has run in this process yet: the next one is the cold start. */
|
|
186
|
+
private cold;
|
|
187
|
+
/**
|
|
188
|
+
* A Cloud Function is wrapped: its wrapper makes each request's span (and flushes before the
|
|
189
|
+
* response), so the http server instrumentation leaves incoming requests alone.
|
|
190
|
+
*/
|
|
191
|
+
private wrapsHttp;
|
|
177
192
|
/** `Zharp.log.info("Order placed", { orderId })` — and debug, warn, error, fatal, trace. */
|
|
178
193
|
readonly log: Record<Level, LogFn>;
|
|
179
194
|
/** Whether `init()` started the SDK. */
|
|
@@ -230,6 +245,49 @@ declare class ZharpNode {
|
|
|
230
245
|
startSpan<T>(name: string, fn: (span: Span) => T, options?: SpanOptions): T;
|
|
231
246
|
/** Send everything waiting now. Await it before a serverless function returns. */
|
|
232
247
|
flush(timeoutMs?: number): Promise<void>;
|
|
248
|
+
/**
|
|
249
|
+
* An AWS Lambda handler (async, callback, or `awslambda.streamifyResponse`):
|
|
250
|
+
*
|
|
251
|
+
* export const handler = Zharp.lambda(async (event, context) => { … });
|
|
252
|
+
*/
|
|
253
|
+
lambda<H extends (...args: any[]) => any>(handler: H, options?: ServerlessOptions): H;
|
|
254
|
+
/**
|
|
255
|
+
* An Azure Functions handler, v4 programming model (`(request, context)`, any trigger) or v3
|
|
256
|
+
* (`(context, req)`):
|
|
257
|
+
*
|
|
258
|
+
* app.http('orders', { handler: Zharp.azureFunction(async (request, context) => { … }) });
|
|
259
|
+
*/
|
|
260
|
+
azureFunction<H extends (...args: any[]) => any>(handler: H, options?: ServerlessOptions): H;
|
|
261
|
+
/**
|
|
262
|
+
* A Google Cloud Function: an HTTP function `(req, res)`, a CloudEvent function `(cloudEvent)`,
|
|
263
|
+
* or a background function `(data, context)`.
|
|
264
|
+
*
|
|
265
|
+
* functions.http('orders', Zharp.cloudFunction((req, res) => { … }));
|
|
266
|
+
*
|
|
267
|
+
* An HTTP function's response is held until everything is sent — Cloud Functions may stop
|
|
268
|
+
* the instance's CPU the moment the response is out.
|
|
269
|
+
*/
|
|
270
|
+
cloudFunction<H extends (...args: any[]) => any>(handler: H, options?: ServerlessOptions): H;
|
|
271
|
+
/** The first invocation in the process is the cold start (not under provisioned concurrency). */
|
|
272
|
+
private takeColdstart;
|
|
273
|
+
/** The http instrumentation's config, leaving incoming requests to a wrapped Cloud Function. */
|
|
274
|
+
private withWrappedRequests;
|
|
275
|
+
/** The invocation's span, in a context of its own: the caller's trace, or a new one. */
|
|
276
|
+
private beginInvocation;
|
|
277
|
+
/** Report what the handler threw, in its invocation, and fail the span. Once per error. */
|
|
278
|
+
private invocationFailed;
|
|
279
|
+
/** End the invocation's span, then send everything waiting, within the budget. */
|
|
280
|
+
private endInvocation;
|
|
281
|
+
/**
|
|
282
|
+
* Run a handler as one invocation. Its result (a value, a promise, or what it passes to its
|
|
283
|
+
* callback) comes back unchanged — after the span has ended and been flushed.
|
|
284
|
+
*/
|
|
285
|
+
private runInvocation;
|
|
286
|
+
/**
|
|
287
|
+
* An HTTP function `(req, res)`: the invocation ends with the response. `res.end` is held
|
|
288
|
+
* until the span has ended and everything is flushed, then goes out as the handler wrote it.
|
|
289
|
+
*/
|
|
290
|
+
private runHttpFunction;
|
|
233
291
|
/** Flush, stop, and put back everything that was patched. */
|
|
234
292
|
shutdown(): Promise<void>;
|
|
235
293
|
private emit;
|
|
@@ -256,8 +314,8 @@ declare class ZharpNode {
|
|
|
256
314
|
}
|
|
257
315
|
|
|
258
316
|
/** Sent as `telemetry.sdk.version`. Bumped with package.json. */
|
|
259
|
-
declare const VERSION = "0.
|
|
317
|
+
declare const VERSION = "0.5.0";
|
|
260
318
|
|
|
261
319
|
declare const Zharp: ZharpNode;
|
|
262
320
|
|
|
263
|
-
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|
|
321
|
+
export { type AttributeValue, type Attributes, type CaptureBodies, type CaptureBodiesOptions, type NodeOptions, type ServerlessOptions, VERSION, Zharp, ZharpNode, type ZharpUser, Zharp as default };
|