|
| 1 | +--- |
| 2 | +title: 'Tracing Channels' |
| 3 | +navigation: |
| 4 | + icon: i-lucide-activity |
| 5 | +description: 'ctx.tracing lists the Node.js Tracing Channels an app publishes, subscribes to them on demand, and folds their lifecycle events into trace records a UI can show.' |
| 6 | +--- |
| 7 | + |
| 8 | +`ctx.tracing` lists the Node.js Tracing Channels an app publishes, subscribes to them on demand, and folds their lifecycle events into trace records a UI can show. |
| 9 | + |
| 10 | +A Tracing Channel is a named group of five diagnostics channels (`start`, `end`, `asyncStart`, `asyncEnd`, `error`) from [`node:diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). A library publishes to them around one unit of work. Node itself publishes `module.require` and `net.server.listen`. |
| 11 | + |
| 12 | +The [Node-Side API reference](/references/node-api#devframetracinghost) collects the host methods as a lookup table. |
| 13 | + |
| 14 | +## Listing the channels your app publishes |
| 15 | + |
| 16 | +Node has no API that lists channels, so devframe learns the names from three sources: the two built-in Node channels, `ctx.tracing.register()` calls, and the `tracing.channels` field. |
| 17 | + |
| 18 | +```ts |
| 19 | +import { defineDevframe } from 'devframe' |
| 20 | + |
| 21 | +export default defineDevframe({ |
| 22 | + id: 'my-tool', |
| 23 | + name: 'My Tool', |
| 24 | + tracing: { |
| 25 | + channels: [ |
| 26 | + 'my-app:db', |
| 27 | + { name: 'my-app:queue', description: 'Job queue dispatch' }, |
| 28 | + ], |
| 29 | + }, |
| 30 | + setup(ctx) {}, |
| 31 | +}) |
| 32 | +``` |
| 33 | + |
| 34 | +A hub lists host-level channels the same way with `initHub({ tracing: { channels } })`. Every mounted devframe's own `tracing` field joins the same list, because a hub shares one `ctx.tracing`. |
| 35 | + |
| 36 | +## Publishing a Tracing Channel |
| 37 | + |
| 38 | +`register()` returns Node's `TracingChannel`, so one call both lists the channel and gives you the object to trace with: |
| 39 | + |
| 40 | +```ts |
| 41 | +export default defineDevframe({ |
| 42 | + id: 'my-tool', |
| 43 | + name: 'My Tool', |
| 44 | + setup(ctx) { |
| 45 | + const queries = ctx.tracing.register('my-tool:query', { description: 'Database queries' }) |
| 46 | + |
| 47 | + ctx.rpc.register({ |
| 48 | + name: 'my-tool:run-query', |
| 49 | + type: 'query', |
| 50 | + handler: (sql: string) => queries.tracePromise(() => db.run(sql), { sql }), |
| 51 | + }) |
| 52 | + }, |
| 53 | +}) |
| 54 | +``` |
| 55 | + |
| 56 | +`tracePromise` writes the resolved value to `context.result` and a rejection to `context.error`, so a record shows both. Publishing costs nothing while nobody records: `TracingChannel` skips its work when `hasSubscribers` is `false`. |
| 57 | + |
| 58 | +## Recording |
| 59 | + |
| 60 | +Recording is off until something calls `record(name)`. Subscribing flips `hasSubscribers` in the app, so the app starts paying the tracing cost only while someone looks. |
| 61 | + |
| 62 | +```ts |
| 63 | +ctx.tracing.record('module.require') |
| 64 | +const off = ctx.tracing.onRecord('module.require', (record) => { |
| 65 | + console.log(record.status, record.duration, record.context) |
| 66 | +}) |
| 67 | +// later |
| 68 | +off() |
| 69 | +ctx.tracing.stop('module.require') |
| 70 | +``` |
| 71 | + |
| 72 | +Every lifecycle event that shares the same context object folds into one record: |
| 73 | + |
| 74 | +```ts |
| 75 | +interface DevframeTraceRecord { |
| 76 | + id: string |
| 77 | + channel: string |
| 78 | + startedAt: number |
| 79 | + duration?: number // ms from start to the latest event |
| 80 | + status: 'pending' | 'ok' | 'error' |
| 81 | + context: SerializedValue |
| 82 | + result?: SerializedValue |
| 83 | + error?: { name: string, message: string, stack?: string } |
| 84 | + events: { phase: 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error', at: number }[] |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +The context, result and error pass through a serializer that caps depth at 4, truncates long strings, drops functions, and marks cycles, so a record that holds a socket or a request object still crosses the wire. A ring buffer keeps the last 500 records per channel; `records(name)` reads them and `clear(name)` drops them. |
| 89 | + |
| 90 | +## Attaching a tool's own recorder |
| 91 | + |
| 92 | +A tool that already traces on its own does not need to move its recording into `ctx.tracing`. It keeps its own recorder and, when a devframe mounts it, attaches the recorder so the channels and records show up there. Devframe relays them. It does not subscribe to the channels itself. |
| 93 | + |
| 94 | +`createTracingRecorder()` from `devframe/node` returns a recorder with the same recording methods as `ctx.tracing`, but without the wire: |
| 95 | + |
| 96 | +```ts |
| 97 | +import { defineDevframe } from 'devframe' |
| 98 | +import { createTracingRecorder } from 'devframe/node' |
| 99 | + |
| 100 | +// The tool's own tracing instance. It works with or without devframe. |
| 101 | +export const tracer = createTracingRecorder() |
| 102 | +const queries = tracer.register('my-tool:query', { description: 'Database queries' }) |
| 103 | +tracer.record('my-tool:query') |
| 104 | + |
| 105 | +export default defineDevframe({ |
| 106 | + id: 'my-tool', |
| 107 | + name: 'My Tool', |
| 108 | + setup(ctx) { |
| 109 | + ctx.tracing.attach(tracer) |
| 110 | + }, |
| 111 | +}) |
| 112 | +``` |
| 113 | + |
| 114 | +`attach()` returns a function that detaches the recorder and removes its channels from the list. While the recorder is attached: |
| 115 | + |
| 116 | +- `list()`, `records(name)` and `onRecord(name)` include its channels. |
| 117 | +- `record(name)`, `stop(name)` and `clear(name)`, and the matching RPC actions, call the recorder's own methods. Devframe never records an attached channel itself. |
| 118 | +- When the recorder and `ctx.tracing` both know a name, the recorder wins. Use a prefix such as `my-tool:` to keep names apart. |
| 119 | + |
| 120 | +The recorder does not have to come from devframe. Any object with the `DevframeTracingSource` shape works, so the tool can keep devframe out of its runtime dependencies: |
| 121 | + |
| 122 | +```ts |
| 123 | +interface DevframeTracingSource { |
| 124 | + list: () => DevframeTracingChannelInfo[] |
| 125 | + records: (name: string) => DevframeTraceRecord[] |
| 126 | + subscribe: (listener: (event: |
| 127 | + | { type: 'record', record: DevframeTraceRecord } |
| 128 | + | { type: 'channels' } |
| 129 | + | { type: 'clear', channel: string } |
| 130 | + ) => void) => () => void |
| 131 | + record?: (name: string) => void |
| 132 | + stop?: (name: string) => void |
| 133 | + clear?: (name: string) => void |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +Emit `record` on every record update, `channels` when a channel is added or its `recording` changes, and `clear` when a buffer is dropped. Leave out `record`, `stop` or `clear` to keep that control in the tool: the matching devframe call then does nothing. |
| 138 | + |
| 139 | +## Reading from the browser |
| 140 | + |
| 141 | +The node side publishes two wire pieces. `devframe:tracing:channels` is a shared state keyed by channel name with `source`, `recording`, `count` and, while recording, a `streamId`. `devframe:tracing` is a streaming channel; subscribe with that `streamId` to receive each record as it updates, and upsert by `id`: |
| 142 | + |
| 143 | +```ts |
| 144 | +const channels = await rpc.sharedState.get('devframe:tracing:channels') |
| 145 | +await rpc.call('devframe:tracing:record', 'module.require') |
| 146 | +const { streamId } = channels.value()['module.require']! |
| 147 | +for await (const record of rpc.streaming.subscribe('devframe:tracing', streamId)) { |
| 148 | + records.set(record.id, record) |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +`record()` and `clear()` issue a fresh `streamId`, so watch the shared state and re-subscribe when it changes. The RPC actions `devframe:tracing:record`, `devframe:tracing:stop` and `devframe:tracing:clear` take the channel name. |
| 153 | + |
| 154 | +## Runtimes |
| 155 | + |
| 156 | +Node.js and Bun provide `tracingChannel`. On a runtime without it, every `ctx.tracing` and recorder method is a no-op, `register()` returns a stand-in whose `traceSync` / `tracePromise` run the function directly, and the first `record()` reports [`DF0086`](/errors/DF0086) once. |
0 commit comments