---
title: "Tracing Channels"
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."
canonical_url: "https://devfra.me/guide/tracing-channels"
---
# Tracing Channels

> 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](https://devfra.me/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`](https://devfra.me/errors/DF0086) once.


## Sitemap

See the full [sitemap](https://devfra.me/sitemap.md) for all pages.
