nanoeffects 0.31.2 → 0.33.0

package/docs/tracing.md

@@ -13,15 +13,20 @@ Tracing is optional. A bus works the same without it, and it costs almost nothin
 - [Show which subscription began a chain](#show-which-subscription-began-a-chain)
 - [Follow one flow with a traceGroupId](#follow-one-flow-with-a-tracegroupid)
 - [Name a listener](#name-a-listener)
+- [List who listens](#list-who-listens)
+- [Find the line of a listener](#find-the-line-of-a-listener)
 - [Keep the chain: `ctx.emit`, not `bus.emit`](#keep-the-chain-ctxemit-not-busemit)
 - [Turn the names off](#turn-the-names-off)
 - [Use built-in loggers](#use-built-in-loggers)
   - [Cut volume in production](#cut-volume-in-production)
   - [Keep the last events for an incident](#keep-the-last-events-for-an-incident)
+  - [Measure time and find open tasks](#measure-time-and-find-open-tasks)
+  - [Find the cause of an error](#find-the-cause-of-an-error)
   - [Configure Redux DevTools](#configure-redux-devtools)
   - [Find loops with `graphLogger`](#find-loops-with-graphlogger)
   - [Send safe data to a tool](#send-safe-data-to-a-tool)
   - [Write your own logger](#write-your-own-logger)
+  - [Stop on an event](#stop-on-an-event)
 - [Drop tracing from a build](#drop-tracing-from-a-build)
 
 ## Attach a tracer
@@ -186,7 +191,7 @@ The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", trac
 
 **When.** An event has more than one listener and you read the trace to see which one did the work.
 
-Give the listener a `traceId` when you register it. The plugin makes each call of it a task with that name, and what it emits with `ctx.emit` is below it. `off` works as before. It also works in a module (`m.on(event, handler, { traceId })`) and on an instance made by `extendBus`.
+A listener is named by its function when you register one with a name (`function saveName() {}`), so a log of an app that nobody annotated is already readable. An inline arrow has no name and stays as it is. To choose the name, or to name an arrow, give the listener a `traceId` when you register it; it wins over the function name. The plugin makes each call of a named listener a task with that name, and what it emits with `ctx.emit` is below it. A minifier can shorten function names in a production build: use `traceId` where a name must stay stable, and for a handler that a policy returns (`latest(fn)`), which has no name of its own. `off` works as before. It also works in a module (`m.on(event, handler, { traceId })`) and on an instance made by `extendBus`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -209,6 +214,88 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 [nanoeffects] saveNotifier · run done
 ```
 
+## List who listens
+
+**Problem.** To know what an emit will start, you search the code for every `bus.on` of that event.
+
+**When.** You read an app that you did not write, or a test must guard the wiring of the bus.
+
+`describeBus(bus)` returns the listeners that each event has right now, by name and in the order they were added. A name is the `traceId`, else the function name, else `"<anonymous>"`. It reads what `tracePlugin` keeps, so it returns `{}` on a bus without the plugin or a tracer, and in the `notrace` build. It does not run anything and does not change the bus.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, describeBus, tracePlugin } from "nanoeffects/trace";
+
+function saveName(name) {
+  console.log("save", name);
+}
+
+function audit(name) {
+  console.log("audit", name);
+}
+
+const trace = createTracer(consoleLogger());
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
+
+bus.on("name/changed", saveName);
+bus.on("name/changed", audit);
+bus.on("saved", () => {}, { traceId: "refreshView" });
+
+// describeBus: the map of events to listener names
+console.log(describeBus(bus));
+```
+
+```
+{ "name/changed": ["saveName", "audit"], saved: ["refreshView"] }
+```
+
+## Find the line of a listener
+
+**Problem.** The log says that `saveNotifier` ran, and you must search the code for the `bus.on` that registered it. An inline arrow has no name at all, so it is not in the log.
+
+**When.** You debug in development and want to jump from a log line to the code.
+
+Pass `source: true` to `tracePlugin`. It reads the place of each `bus.on` and `bus.once` call once, when the listener is registered, and never on `emit`. The events of the listener get a `source` (`file:line:column`), `consoleLogger({ source: true })` prints it, and `describeBus(bus, { source: true })` lists it. An anonymous listener is reported too, under the type of its event and a number: `name/changed#1`, `name/changed#2`, in the order of registration. Two inline listeners on one event are two entries, and the place stays in `source`. Adding or reordering `bus.on` calls renumbers them, so give a `traceId` to a listener whose name must stay the same between builds.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, describeBus, tracePlugin } from "nanoeffects/trace";
+
+// source: print where the listener was registered
+const trace = createTracer(consoleLogger({ source: true }));
+
+// source: read the place of each bus.on, once at registration
+const bus = createBus({ trace })
+  .use(tracePlugin({ source: true }));
+
+function saveName(name) {
+  console.log("save", name);
+}
+
+bus.on("name/changed", saveName);
+bus.on("name/changed", (name) => console.log("audit", name));
+
+bus.emit("name/changed", "Eva");
+
+// describeBus: the same places, without running anything
+console.log(describeBus(bus, { source: true }));
+```
+
+```
+[nanoeffects] saveName · run start (file:///app/src/user.js:13:5)
+[nanoeffects] name/changed#1 · run start (file:///app/src/user.js:14:5)
+{ "name/changed": ["saveName (file:///app/src/user.js:13:5)", "<anonymous> (file:///app/src/user.js:14:5)"] }
+```
+
+Know the limits:
+
+- **Minified or bundled code** gives the line of the bundle. Turn on source maps (`node --enable-source-maps`, or the browser's) to see the original line.
+- **`ctx.on` called by hand** inside a handler shows the line in the library as its place. The `on` of a module and of an instance made by `extendBus`, and the `on` of `matchPlugin`, `signalPlugin` and `devPlugin`, show your line, in any order of plugins and in a bundle.
+- **No stack**, as with `Error.stackTraceLimit = 0`, gives no `source`. The listener runs as usual.
+- **The default is off.** Reading a stack costs a little for each registration, so turn it on in development.
+
 ## Keep the chain: `ctx.emit`, not `bus.emit`
 
 Inside a handler, emit with `ctx.emit`. It keeps the chain: what it starts is below the handler, and its events have the `rootId` of the chain. A plain `bus.emit` inside a handler starts a new root with no `parentId` and no `rootId`, so the trace loses the link. The bus cannot warn about it, because it does not know which handler is running.
@@ -251,7 +338,7 @@ const bus = createBus({
 | `consoleLogger()` | Prints one line per phase, indented by task depth |
 | `performanceLogger()` | User Timing measures for the browser Performance panel |
 | `createTraceRecorder()` | Keeps events in `recorder.events`: all of them for tests, or with `{ capacity }` the last N ([see below](#keep-the-last-events-for-an-incident)) |
-| `graphLogger()` | Builds the map of which event leads to which, finds loops while the app runs, and writes the map as Mermaid, Graphviz or JSON ([see below](#find-loops-with-graphlogger)) |
+| `graphLogger()` | Builds the map of which event leads to which, finds loops while the app runs, and writes the map as Mermaid, Graphviz or JSON ([see below](#find-loops-with-graphlogger)); [`mergeGraphs` and `findOrphans`](debugging-loops.md#find-listeners-that-never-ran) join runs and find listeners that never ran |
 
 ### Cut volume in production
 
@@ -311,12 +398,91 @@ window.addEventListener("error", () => {
 What to know before you send the events:
 
 - **`payload` and `error` can hold private data**: what a user typed, tokens, personal text. The recorder keeps them as they are and does not redact. Choose what to send, as `withoutPayload` does.
-- **There is no time on an event.** You get the order, not the duration. To add a time, wrap the recorder in a logger that stamps `performance.now()` on a copy of the event.
+- **There is no time on an event.** You get the order, not the duration. [`timingLogger`](#measure-time-and-find-open-tasks) measures time.
 - **An old `parentId` can point at an event that was pushed out.** When you build a tree from the events, treat an unknown `parentId` as a root.
 - **`recorder.events` is a snapshot with a `capacity`.** Each read builds a new array, so read it once at the moment you need it. Without a `capacity` it is one live array.
 - **A low `sample` thins the buffer.** `createTracer(recorder, { sample: 0.05 })` records 5% of root tasks, so the buffer may hold little when the incident comes. See [Cut volume in production](#cut-volume-in-production).
 - **A `capacity` that is not a positive integer** (`0`, a negative number, `NaN`) means no limit.
 
+### Measure time and find open tasks
+
+An event has no time, so the recorder cannot tell you which handler is slow, how long a request lived before `cancel`, or whether a test left something running. `timingLogger` stamps the time on each event when it gets it and pairs `start` with the first closing phase (`done`, `error`, `cancel` or `drop`) of the same task.
+
+Pass it to the tracer next to the recorder: `createTracer` takes an array of loggers.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer, timingLogger } from "nanoeffects/trace";
+
+// createTraceRecorder: events in the order they came
+export const recorder = createTraceRecorder();
+
+// timingLogger: the time of each event and the duration of tasks
+export const timing = timingLogger();
+
+// createTracer: both loggers get every event
+const trace = createTracer([recorder, timing]);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// check.js
+import { timing } from "./bus";
+
+// durations: the tasks that ended, with the closing phase and the time in ms
+const slow = timing.durations.filter((task) => task.ms > 500);
+console.log(slow);
+
+// pending: the tasks that started and have not ended
+const leftovers = timing.pending();
+if (leftovers.length > 0) {
+  throw new Error(`${leftovers.length} tasks are still open`);
+}
+```
+
+What to know:
+
+- **The clock.** Time comes from `performance.now()`, or `Date.now()` where there is none. In a test pass your own clock: `timingLogger({ now })`.
+- **`capacity` cuts only `durations`.** `timingLogger({ capacity: 200 })` keeps the last 200 ended tasks. `pending()` is never cut: a leak shows up as a growing list.
+- **`clear()`** empties both lists. Call it between tests.
+- **The logger sees what the tracer lets through.** A task whose `start` was filtered out or not sampled gets no pair, and its ending is ignored.
+
+### Find the cause of an error
+
+An error arrives as one event, and you cannot see what led to it. `chainOf` builds the path from the root to a task by `parentId`. Give it the recorder: then the listeners that send no event (a plain handler that calls `ctx.emit`) are in the path too.
+
+```js
+// why.js
+import { chainOf } from "nanoeffects/trace";
+import { recorder } from "./bus";
+
+const failed = recorder.events.find((event) => event.phase === "error");
+
+// chainOf: the path from the root to the failed task
+const path = chainOf(recorder, failed.id);
+
+const text = path.map((step) => step.type).join(" → ");
+console.log(text); // queryChanged → searchLoaded
+```
+
+A step has `type`, and `effect` and `phase` (a listener with no events has neither), `source` and `traceGroupId` when known. If you pass a list of events (a snapshot, a file) instead of the recorder, the path holds only the tasks that have events.
+
+To see the path right in the console, turn on `chain` in `consoleLogger`:
+
+```js
+import { consoleLogger, createTracer } from "nanoeffects/trace";
+
+// consoleLogger: the line of an error ends with the path from the root
+const trace = createTracer(consoleLogger({ chain: true }));
+// [nanoeffects] render · run error (queryChanged → render)
+```
+
+`chain` remembers the last 1000 tasks. It is off by default.
+
 ### Configure Redux DevTools
 
 <!-- docs-check: new -->
@@ -448,6 +614,26 @@ const errorsOnly = (): TraceLogger => (event) => {
 };
 ```
 
+### Stop on an event
+
+You want the debugger to stop when a certain event comes. No API is needed for that: it is five lines in a logger of your own.
+
+```js
+import { createTracer } from "nanoeffects/trace";
+
+// A logger that stops in the debugger at the start of a task with this type
+const stopOn = (type) => (event) => {
+  if (event.type === type && event.phase === "start") {
+    debugger; // the browser stops here when DevTools is open
+  }
+};
+
+// createTracer: pass the logger like any other
+const trace = createTracer(stopOn("search"));
+```
+
+In the debugger read `event.payload` and walk up the stack: the synchronous part of the chain is all there.
+
 ## Drop tracing from a build
 
 Without a tracer the hooks cost almost nothing. `nanoeffects/trace` is only bundled when imported.