@reqray/core 0.1.0 → 0.1.1

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
@@ -1,12 +1,57 @@
1
1
  # @reqray/core
2
2
 
3
- Reqray core: request context, buffer, sampling, masking, detectors. No third-party runtime dependencies.
3
+ The core of Reqray: the request context, the span buffer, masking, sampling and
4
+ the detectors. No third-party runtime dependencies.
4
5
 
5
- Part of [Reqray](https://github.com/reqray/reqray) — a dev panel and request-inspection tool for
6
- Node.js. It instruments HTTP, SQL, outgoing calls and cache on its own, shows
7
- every request as a waterfall, and finds N+1 down to the file and the line.
6
+ Part of [Reqray](https://github.com/reqray/reqray) — a dev panel and request inspector for Node.js. It
7
+ instruments HTTP, SQL, outgoing calls and cache on its own, shows every
8
+ request as a waterfall, and finds N+1 down to the file and the line.
8
9
 
9
- Documentation, screenshots and a demo that runs with one command are in the
10
+ ## You probably want an adapter
11
+
12
+ To use Reqray in an application, install
13
+ [`@reqray/register`](https://www.npmjs.com/package/@reqray/register) and one of
14
+ [`@reqray/fastify`](https://www.npmjs.com/package/@reqray/fastify),
15
+ [`@reqray/express`](https://www.npmjs.com/package/@reqray/express),
16
+ [`@reqray/nestjs`](https://www.npmjs.com/package/@reqray/nestjs). They depend on
17
+ this package; you do not need to install it yourself.
18
+
19
+ This package is for writing an adapter for another framework or an
20
+ instrumentation for another driver.
21
+
22
+ ## What is in it
23
+
24
+ - **Request context.** `AsyncLocalStorage` holds a `RequestScope` for the
25
+ request being handled; `current()` returns it, or `undefined` outside a
26
+ request — in which case an instrumentation simply does nothing.
27
+ - **Recording.** `record(scope, span)` adds a span. Masking of sensitive
28
+ fields happens here, before anything reaches the buffer.
29
+ - **`createReqray(options)`** — what an adapter calls once: it resolves the
30
+ options, owns the transports and exposes the panel's request handler.
31
+ - **The instrumentation kit**: `patchMethod` / `unpatchMethod`, `settle` /
32
+ `settleCallback` for the promise-or-callback split, `guarded` for the
33
+ try/catch that disables one instrumentation instead of reaching the
34
+ application, `fingerprintSql` for normalizing statements.
35
+ - **Detectors**: N+1, sequential HTTP, duplicate calls and cache reads, pool
36
+ wait, a transaction held across a call, heavy responses, slow code, time
37
+ budgets. They run after the response has been sent.
38
+
39
+ ```js
40
+ import { current, record, fingerprintSql } from '@reqray/core';
41
+
42
+ const scope = current();
43
+ if (scope) {
44
+ record(scope, { kind: 'db', sql, fingerprint: fingerprintSql(sql), duration });
45
+ }
46
+ ```
47
+
48
+ Two rules an instrumentation has to keep: never change the behaviour of what
49
+ it wraps, and never let its own error reach the application.
50
+
51
+ ## More
52
+
53
+ Everything else — the detectors, security defaults, measured overhead and a
54
+ demo that runs with one command — is in the
10
55
  [main README](https://github.com/reqray/reqray#readme).
11
56
 
12
57
  ## License