--- title: 'Tracing Channels' navigation: icon: i-lucide-activity 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.' --- `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. 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`. The [Node-Side API reference](/references/node-api#devframetracinghost) collects the host methods as a lookup table. ## Listing the channels your app publishes 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. ```ts import { defineDevframe } from 'devframe' export default defineDevframe({ id: 'my-tool', name: 'My Tool', tracing: { channels: [ 'my-app:db', { name: 'my-app:queue', description: 'Job queue dispatch' }, ], }, setup(ctx) {}, }) ``` 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`. ## Publishing a Tracing Channel `register()` returns Node's `TracingChannel`, so one call both lists the channel and gives you the object to trace with: ```ts export default defineDevframe({ id: 'my-tool', name: 'My Tool', setup(ctx) { const queries = ctx.tracing.register('my-tool:query', { description: 'Database queries' }) ctx.rpc.register({ name: 'my-tool:run-query', type: 'query', handler: (sql: string) => queries.tracePromise(() => db.run(sql), { sql }), }) }, }) ``` `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`. ## Recording 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. ```ts ctx.tracing.record('module.require') const off = ctx.tracing.onRecord('module.require', (record) => { console.log(record.status, record.duration, record.context) }) // later off() ctx.tracing.stop('module.require') ``` Every lifecycle event that shares the same context object folds into one record: ```ts interface DevframeTraceRecord { id: string channel: string startedAt: number duration?: number // ms from start to the latest event status: 'pending' | 'ok' | 'error' context: SerializedValue result?: SerializedValue error?: { name: string, message: string, stack?: string } events: { phase: 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error', at: number }[] } ``` 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. ## Attaching a tool's own recorder 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. `createTracingRecorder()` from `devframe/node` returns a recorder with the same recording methods as `ctx.tracing`, but without the wire: ```ts import { defineDevframe } from 'devframe' import { createTracingRecorder } from 'devframe/node' // The tool's own tracing instance. It works with or without devframe. export const tracer = createTracingRecorder() const queries = tracer.register('my-tool:query', { description: 'Database queries' }) tracer.record('my-tool:query') export default defineDevframe({ id: 'my-tool', name: 'My Tool', setup(ctx) { ctx.tracing.attach(tracer) }, }) ``` `attach()` returns a function that detaches the recorder and removes its channels from the list. While the recorder is attached: - `list()`, `records(name)` and `onRecord(name)` include its channels. - `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. - When the recorder and `ctx.tracing` both know a name, the recorder wins. Use a prefix such as `my-tool:` to keep names apart. 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: ```ts interface DevframeTracingSource { list: () => DevframeTracingChannelInfo[] records: (name: string) => DevframeTraceRecord[] subscribe: (listener: (event: | { type: 'record', record: DevframeTraceRecord } | { type: 'channels' } | { type: 'clear', channel: string } ) => void) => () => void record?: (name: string) => void stop?: (name: string) => void clear?: (name: string) => void } ``` 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. ## Reading from the browser 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`: ```ts const channels = await rpc.sharedState.get('devframe:tracing:channels') await rpc.call('devframe:tracing:record', 'module.require') const { streamId } = channels.value()['module.require']! for await (const record of rpc.streaming.subscribe('devframe:tracing', streamId)) { records.set(record.id, record) } ``` `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. ## Runtimes 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.