Skip to content

Commit fef9fb3

Browse files
antfubotantfu
andauthored
feat(devframe): add ctx.tracing for Node.js Tracing Channels (#428)
* feat(devframe): add ctx.tracing for Node.js Tracing Channels * feat(devframe): attach a tool's own tracing recorder to ctx.tracing A tool can keep its own Tracing Channel recorder (createTracingRecorder() from devframe/node, or any DevframeTracingSource) and show it in devframe with ctx.tracing.attach(). Devframe relays the channels and records and routes record/stop/clear to the source, but never records them itself. * Delete .pi/skills/npm-antfu-design-antfu-design * refactor(devframe): simplify tracing host and recorder --------- Co-authored-by: Anthony Fu <github@antfu.me>
1 parent dba8b34 commit fef9fb3

40 files changed

Lines changed: 1767 additions & 7 deletions

‎docs/app/app.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ export default defineAppConfig({
132132
'/guide/json-render',
133133
'/guide/diagnostics',
134134
'/guide/streaming',
135+
'/guide/tracing-channels',
135136
],
136137
},
137138
{
Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
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.

‎docs/content/6.errors/DF0086.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: 'DF0086: Tracing Channels Unavailable'
3+
description: 'The runtime does not provide `node:diagnostics_channel`''s `tracingChannel`, so `ctx.tracing` records nothing.'
4+
---
5+
6+
## Message
7+
8+
> Tracing Channels are unavailable: this runtime ({runtime}) does not provide `node:diagnostics_channel`'s `tracingChannel`, so `ctx.tracing` records nothing.
9+
10+
## Cause
11+
12+
`ctx.tracing` wraps the `TracingChannel` class from `node:diagnostics_channel`. Node.js and Bun provide it. A runtime that ships the module without `tracingChannel` (Deno at the time of writing) cannot subscribe to a Tracing Channel, so every `ctx.tracing` method, and every method of a recorder from `createTracingRecorder()`, is a no-op there. The warning fires once per recorder, the first time something calls `record()` on it.
13+
14+
## Example
15+
16+
```ts
17+
// Running under Deno
18+
ctx.tracing.record('module.require') // ⚠ reports DF0086, records nothing
19+
```
20+
21+
## Fix
22+
23+
Run the dev server under Node.js 22+ or Bun to record Tracing Channels. No code change is needed: `register()` still returns a channel whose `traceSync` / `tracePromise` run the wrapped function directly, so producers keep working.
24+
25+
## Source
26+
27+
- [`packages/devframe/src/node/tracing-recorder.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/tracing-recorder.ts): `TracingRecorder.record()` reports this once per recorder when the module loaded at construction has no `tracingChannel` function. `ctx.tracing` and `createTracingRecorder()` both use it.

‎docs/content/6.errors/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
9191
| [DF0082](/errors/DF0082) | error | Addressed Client Not Connected |
9292
| [DF0084](/errors/DF0084) | error | Invalid MCP Resource Template |
9393
| [DF0085](/errors/DF0085) | error | Repeated MCP Prompt Name |
94+
| [DF0086](/errors/DF0086) | warn | Tracing Channels Unavailable |
9495

9596
## Hub: context & lifecycle (DF80xx)
9697

‎docs/content/8.references/1.terms.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ A devframe has two halves: the **node side** registers RPC functions and owns st
3636
| **workspace scope** | Committable per-repository storage. | `DevframeStorageScope` |
3737
| **project scope** | Per-checkout storage, gitignored. | `DevframeStorageScope` |
3838
| **global scope** | Per-user storage. | `DevframeStorageScope` |
39+
| **Tracing Channel** | A named group of five Node.js diagnostics channels (`start`, `end`, `asyncStart`, `asyncEnd`, `error`) that a library publishes around one unit of work. `ctx.tracing` lists them and records them on demand. | `ctx.tracing`, `node:diagnostics_channel` |
40+
| **trace record** | One traced unit of work: every Tracing Channel event that shared the same context object, folded into one row with status, duration, context, result and error. | `DevframeTraceRecord` |
3941

4042
## Browser side
4143

‎docs/content/8.references/3.events.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,15 @@ Pushed to subscribed RPC clients, wired by the core node side.
113113
| `devframe:streaming:end` | A streaming terminator (optionally an error). |
114114
| `devframe:streaming:upload-cancel` | Server-side cancel of an in-flight upload. |
115115

116+
### Shared state & streams (server → client)
117+
118+
Published by the core node side; read them with `rpc.sharedState.get(key)` and `rpc.streaming.subscribe(channel, id)`. The paired request methods (`devframe:tracing:record` / `stop` / `clear`) are RPC endpoints typed in `types/rpc-augments.ts`, not events.
119+
120+
| Name | Kind | Carries |
121+
|---|---|---|
122+
| `devframe:tracing:channels` | shared state | Known [Tracing Channels](/guide/tracing-channels) keyed by base name (`DevframeTracingChannelInfo`): source, description, `recording`, `count`, and the live `streamId` while recording. |
123+
| `devframe:tracing` | streaming channel | Trace records (`DevframeTraceRecord`) of one recording Tracing Channel per stream; the stream id is the `streamId` from `devframe:tracing:channels`. A fresh id is issued on every `record()` and `clear()`. |
124+
116125
### In-page channel notifications (page script → panel)
117126

118127
Pushed over each panel's [in-page channel](/guide/in-page-channel) port; the paired request methods (`devframe:in-page:page-state:subscribe`/`set`/`patch`) are call endpoints defined at their handlers, not events.

‎docs/content/8.references/4.node-api.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ The fields of a `DevframeDefinition`: [Devframe Definition](/guide/devframe-defi
2525
| `duplicationStrategy` | `'warn' \| 'silent' \| 'throw' \| 'duplicate'` | Hub reaction when another devframe shares this `id`. Default `'warn'`. See [Duplication strategies](/references/hub-api#duplication-strategies); standalone adapters ignore it. |
2626
| `capabilities` | `{ dev?, build? }` | Per-runtime feature flags. `boolean` = whole runtime; object = individual features. |
2727
| `services` | `DevframeServiceInput[]` | Wire services consumed: descriptors (`{ package, version?, required?, options? }`) imported against the devframe's own deps, or ready definitions. See [Cross-Devframe Services](/guide/services#wire-services). |
28+
| `tracing` | `{ channels?: (string \| { name, description? })[] }` | Node.js [Tracing Channels](/guide/tracing-channels) the app publishes, listed for inspection tooling. Registered before `setup(ctx)`; recording stays off until a client asks. |
2829
| `clientAssets` | `string \| RemoteAssets` | Built SPA served as the UI: local dist dir or [remote assets](/guide/client-assets). Read by every UI-serving adapter (`dev`, `build`, `vite`, `next`, hub). |
2930
| `rpc` | `{ snapshot?: (string \| { method, inputs })[] }` | RPC config. `rpc.snapshot` opts an RPC this devframe doesn't own into the static dump. Bare method id bakes the no-arg call; `{ method, inputs }` bakes one record per argument-tuple (`inputs` = tuples or async `(ctx) => tuples`). First tuple = fallback. |
3031
| `setup` | `(ctx, info?) => void \| Promise<void>` | **Required.** Server-side entry point, run in every runtime. Optional 2nd arg carries runtime metadata, notably parsed CLI `flags` under `createCac`. |
@@ -130,6 +131,21 @@ The methods on `ctx.services`: [Cross-Devframe Services](/guide/services#the-dev
130131
| `install` | `(input, options?) => Promise<api \| undefined>` | Install a [wire service](#wire-service-definition-fields) at runtime (the dynamic escape hatch; the common path is declarative). `options.resolveFrom` is the descriptor's resolution base. |
131132
| `ready` | `() => Promise<void>` | **Internal.** Construct every queued wire service before any `setup` runs. Adapters call it; application code uses declarative `services`. |
132133

134+
## `DevframeTracingHost`
135+
136+
The methods on `ctx.tracing`: [Tracing Channels](/guide/tracing-channels).
137+
138+
| Method | Signature | Role |
139+
|--------|-----------|------|
140+
| `register` | `(nameOrChannel, { description? }?) => TracingChannel` | Declare a Tracing Channel and get Node's `TracingChannel` back for `traceSync` / `tracePromise`. Idempotent per name; accepts an existing instance. |
141+
| `list` | `() => DevframeTracingChannelInfo[]` | Every known channel with `source` (`builtin` / `registered` / `config` / `adhoc`), `recording`, `count`, `streamId`. |
142+
| `record` | `(name) => void` | Subscribe to the Node channel and fold its events into records. Unknown names are added as `adhoc`. Reports [`DF0086`](/errors/DF0086) once where `tracingChannel` is missing. |
143+
| `stop` | `(name) => void` | Unsubscribe. Buffered records stay. |
144+
| `records` | `(name) => DevframeTraceRecord[]` | Buffered records, oldest first, at most 500 per channel. |
145+
| `clear` | `(name) => void` | Drop the buffer and, while recording, start a fresh stream. |
146+
| `onRecord` | `(name, fn) => unsubscribe` | Run `fn` with the whole record on every lifecycle update. |
147+
| `attach` | `(source) => detach` | Show a tool's own recorder (`createTracingRecorder()` or any `DevframeTracingSource`). Devframe relays its channels and records and routes `record` / `stop` / `clear` to it, but never records them itself. The source attached last wins a name. See [Attaching a tool's own recorder](/guide/tracing-channels#attaching-a-tools-own-recorder). |
148+
133149
## Service tiers
134150

135151
The two tiers a service can take: [Cross-Devframe Services](/guide/services).

‎docs/content/8.references/6.hub-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [
118118

119119
## `buildHub` options
120120

121-
The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/hub-initiate#static-builds). `devframes`, `services`, `rpcDeclarations`, `configure`, `ui`, `renderers`, `name`, `version`, `cwd`, and `getStorageDir` carry the same contracts as their `initHub` counterparts.
121+
The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/hub-initiate#static-builds). `devframes`, `services`, `tracing`, `rpcDeclarations`, `configure`, `ui`, `renderers`, `name`, `version`, `cwd`, and `getStorageDir` carry the same contracts as their `initHub` counterparts.
122122

123123
| Option | Purpose |
124124
|---|---|

‎packages/agentic/src/mcp/__tests__/mcp-server.test.ts‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -514,10 +514,10 @@ describe('mcp adapter (in-memory)', () => {
514514
expect(tool).toBeDefined()
515515
expect(tool!.annotations?.readOnlyHint).toBe(true)
516516

517-
// No key → key list.
517+
// No key → key list, alongside the core's own keys.
518518
const keys = await client.callTool({ name: 'devframe_state_read', arguments: {} })
519519
expect(keys.structuredContent).toEqual({
520-
keys: ['my-plugin:counter'],
520+
keys: ['devframe:tracing:channels', 'my-plugin:counter'],
521521
})
522522

523523
// With key → the value.
@@ -725,6 +725,12 @@ describe('mcp adapter (in-memory)', () => {
725725
expect(lists[0]).toEqual({
726726
resources: [
727727
{ uri: 'devframe://resource/status', name: 'Status', mimeType: 'application/json' },
728+
{
729+
uri: 'devframe://state/devframe%3Atracing%3Achannels',
730+
name: 'devframe:tracing:channels',
731+
description: 'Shared state: devframe:tracing:channels',
732+
mimeType: 'application/json',
733+
},
728734
{
729735
uri: 'devframe://state/my-plugin%3Acounter',
730736
name: 'my-plugin:counter',
@@ -875,8 +881,11 @@ describe('mcp adapter (in-memory)', () => {
875881
initialValue: { count: 3 },
876882
})
877883
const { resources } = await client.listResources()
878-
expect(resources.map(r => r.uri)).toEqual(['test://state/my-plugin%3Acounter'])
879-
const read = await client.readResource({ uri: resources[0]!.uri })
884+
expect(resources.map(r => r.uri)).toEqual([
885+
'test://state/devframe%3Atracing%3Achannels',
886+
'test://state/my-plugin%3Acounter',
887+
])
888+
const read = await client.readResource({ uri: resources[1]!.uri })
880889
expect(JSON.parse((read.contents[0] as { text: string }).text)).toEqual({ count: 3 })
881890
}
882891
finally {

‎packages/devframe/src/adapters/build.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ export async function createBuild(d: DevframeDefinition, options: CreateBuildOpt
8484
for (const input of d.services ?? [])
8585
void ctx.services.install(input, { resolveFrom: d.importMetaUrl })
8686
await ctx.services.ready()
87+
ctx.tracing._applyOptions(d.tracing)
8788
await d.setup(ctx)
8889

8990
// Bake declared `rpc.snapshot` methods (typically a wire service's RPC the

0 commit comments

Comments
 (0)