From c7f1fcc04983eed4633de0c7ae1ecae0e3b34f9e Mon Sep 17 00:00:00 2001 From: "Anthony Fu (via agent)" Date: Mon, 5 Oct 2026 02:51:17 +0000 Subject: [PATCH 1/4] feat(devframe): add ctx.tracing for Node.js Tracing Channels --- docs/app/app.config.ts | 1 + docs/content/1.guide/24.tracing-channels.md | 107 +++++++ docs/content/6.errors/DF0081.md | 27 ++ docs/content/8.references/1.terms.md | 2 + docs/content/8.references/3.events.md | 9 + docs/content/8.references/4.node-api.md | 15 + docs/content/8.references/6.hub-api.md | 2 +- .../src/mcp/__tests__/mcp-server.test.ts | 4 +- packages/devframe/src/adapters/build.ts | 1 + packages/devframe/src/adapters/embedded.ts | 1 + packages/devframe/src/adapters/initiate.ts | 1 + packages/devframe/src/events.ts | 15 + .../src/node/__tests__/host-tracing.test.ts | 251 +++++++++++++++ .../node/__tests__/tracing-serialize.test.ts | 73 +++++ packages/devframe/src/node/context.ts | 3 + packages/devframe/src/node/diagnostics.ts | 5 + packages/devframe/src/node/host-tracing.ts | 297 ++++++++++++++++++ packages/devframe/src/node/scope.ts | 1 + .../devframe/src/node/tracing-serialize.ts | 93 ++++++ packages/devframe/src/types/context.ts | 6 + packages/devframe/src/types/devframe.ts | 7 + packages/devframe/src/types/index.ts | 1 + packages/devframe/src/types/rpc-augments.ts | 29 ++ packages/devframe/src/types/scope.ts | 2 + packages/devframe/src/types/tracing.ts | 117 +++++++ .../node/__tests__/install-devframe.test.ts | 3 + packages/hub/src/node/build.ts | 5 +- packages/hub/src/node/initiate.ts | 8 +- packages/hub/src/node/install-devframe.ts | 1 + .../tsnapi/@devframes/hub/build.snapshot.d.ts | 1 + .../@devframes/hub/initiate.snapshot.d.ts | 1 + .../tsnapi/devframe/constants.snapshot.d.ts | 6 + .../tsnapi/devframe/index.snapshot.d.ts | 58 ++++ .../tsnapi/devframe/internal.snapshot.d.ts | 6 + .../tsnapi/devframe/types.snapshot.d.ts | 9 + 35 files changed, 1163 insertions(+), 5 deletions(-) create mode 100644 docs/content/1.guide/24.tracing-channels.md create mode 100644 docs/content/6.errors/DF0081.md create mode 100644 packages/devframe/src/node/__tests__/host-tracing.test.ts create mode 100644 packages/devframe/src/node/__tests__/tracing-serialize.test.ts create mode 100644 packages/devframe/src/node/host-tracing.ts create mode 100644 packages/devframe/src/node/tracing-serialize.ts create mode 100644 packages/devframe/src/types/tracing.ts diff --git a/docs/app/app.config.ts b/docs/app/app.config.ts index 12f0146ef..6872e5639 100644 --- a/docs/app/app.config.ts +++ b/docs/app/app.config.ts @@ -111,6 +111,7 @@ export default defineAppConfig({ '/guide/json-render', '/guide/diagnostics', '/guide/streaming', + '/guide/tracing-channels', ], }, { diff --git a/docs/content/1.guide/24.tracing-channels.md b/docs/content/1.guide/24.tracing-channels.md new file mode 100644 index 000000000..4a53244e2 --- /dev/null +++ b/docs/content/1.guide/24.tracing-channels.md @@ -0,0 +1,107 @@ +--- +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. + +## 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` method is a no-op, `register()` returns a stand-in whose `traceSync` / `tracePromise` run the function directly, and the first `record()` reports [`DF0081`](/errors/DF0081) once. diff --git a/docs/content/6.errors/DF0081.md b/docs/content/6.errors/DF0081.md new file mode 100644 index 000000000..da84425fe --- /dev/null +++ b/docs/content/6.errors/DF0081.md @@ -0,0 +1,27 @@ +--- +title: 'DF0081: Tracing Channels Unavailable' +description: 'The runtime does not provide `node:diagnostics_channel`''s `tracingChannel`, so `ctx.tracing` records nothing.' +--- + +## Message + +> Tracing Channels are unavailable: this runtime ({runtime}) does not provide `node:diagnostics_channel`'s `tracingChannel`, so `ctx.tracing` records nothing. + +## Cause + +`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 is a no-op there. The warning fires once per process, the first time something calls `record()`. + +## Example + +```ts +// Running under Deno +ctx.tracing.record('module.require') // ⚠ reports DF0081, records nothing +``` + +## Fix + +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. + +## Source + +- [`packages/devframe/src/node/host-tracing.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-tracing.ts): `DevframeTracingHostImpl.record()` reports this once when the module loaded at construction has no `tracingChannel` function. diff --git a/docs/content/8.references/1.terms.md b/docs/content/8.references/1.terms.md index d53d5703f..0b12b14b3 100644 --- a/docs/content/8.references/1.terms.md +++ b/docs/content/8.references/1.terms.md @@ -35,6 +35,8 @@ A devframe has two halves: the **node side** registers RPC functions and owns st | **workspace scope** | Committable per-repository storage. | `DevframeStorageScope` | | **project scope** | Per-checkout storage, gitignored. | `DevframeStorageScope` | | **global scope** | Per-user storage. | `DevframeStorageScope` | +| **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` | +| **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` | ## Browser side diff --git a/docs/content/8.references/3.events.md b/docs/content/8.references/3.events.md index 96fb817f8..e696deff0 100644 --- a/docs/content/8.references/3.events.md +++ b/docs/content/8.references/3.events.md @@ -112,6 +112,15 @@ Pushed to subscribed RPC clients, wired by the core node side. | `devframe:streaming:end` | A streaming terminator (optionally an error). | | `devframe:streaming:upload-cancel` | Server-side cancel of an in-flight upload. | +### Shared state & streams (server → client) + +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. + +| Name | Kind | Carries | +|---|---|---| +| `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. | +| `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()`. | + ### In-page channel notifications (page script → panel) 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. diff --git a/docs/content/8.references/4.node-api.md b/docs/content/8.references/4.node-api.md index 54e5475a4..8283d294f 100644 --- a/docs/content/8.references/4.node-api.md +++ b/docs/content/8.references/4.node-api.md @@ -25,6 +25,7 @@ The fields of a `DevframeDefinition`: [Devframe Definition](/guide/devframe-defi | `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. | | `capabilities` | `{ dev?, build? }` | Per-runtime feature flags. `boolean` = whole runtime; object = individual features. | | `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). | +| `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. | | `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). | | `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. | | `setup` | `(ctx, info?) => void \| Promise` | **Required.** Server-side entry point, run in every runtime. Optional 2nd arg carries runtime metadata, notably parsed CLI `flags` under `createCac`. | @@ -130,6 +131,20 @@ The methods on `ctx.services`: [Cross-Devframe Services](/guide/services#the-dev | `install` | `(input, options?) => Promise` | 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. | | `ready` | `() => Promise` | **Internal.** Construct every queued wire service before any `setup` runs. Adapters call it; application code uses declarative `services`. | +## `DevframeTracingHost` + +The methods on `ctx.tracing`: [Tracing Channels](/guide/tracing-channels). + +| Method | Signature | Role | +|--------|-----------|------| +| `register` | `(nameOrChannel, { description? }?) => TracingChannel` | Declare a Tracing Channel and get Node's `TracingChannel` back for `traceSync` / `tracePromise`. Idempotent per name; accepts an existing instance. | +| `list` | `() => DevframeTracingChannelInfo[]` | Every known channel with `source` (`builtin` / `registered` / `config` / `adhoc`), `recording`, `count`, `streamId`. | +| `record` | `(name) => void` | Subscribe to the Node channel and fold its events into records. Unknown names are added as `adhoc`. Reports [`DF0081`](/errors/DF0081) once where `tracingChannel` is missing. | +| `stop` | `(name) => void` | Unsubscribe. Buffered records stay. | +| `records` | `(name) => DevframeTraceRecord[]` | Buffered records, oldest first, at most 500 per channel. | +| `clear` | `(name) => void` | Drop the buffer and, while recording, start a fresh stream. | +| `onRecord` | `(name, fn) => unsubscribe` | Run `fn` with the whole record on every lifecycle update. | + ## Service tiers The two tiers a service can take: [Cross-Devframe Services](/guide/services). diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md index 8acd106ff..8b63c6f62 100644 --- a/docs/content/8.references/6.hub-api.md +++ b/docs/content/8.references/6.hub-api.md @@ -86,7 +86,7 @@ What `initHub()` serves under its `base`: [The namespace](/guide/hub-initiate#th ## `buildHub` options -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. +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. | Option | Purpose | |---|---| diff --git a/packages/agentic/src/mcp/__tests__/mcp-server.test.ts b/packages/agentic/src/mcp/__tests__/mcp-server.test.ts index 21b7a9f0b..f5e972628 100644 --- a/packages/agentic/src/mcp/__tests__/mcp-server.test.ts +++ b/packages/agentic/src/mcp/__tests__/mcp-server.test.ts @@ -322,9 +322,9 @@ describe('mcp adapter (in-memory)', () => { expect(tool).toBeDefined() expect(tool!.annotations?.readOnlyHint).toBe(true) - // No key → key list. + // No key → key list, alongside the core's own keys. const keys = await client.callTool({ name: 'devframe_state_read', arguments: {} }) - expect(keys.structuredContent).toEqual({ keys: ['my-plugin:counter'] }) + expect(keys.structuredContent).toEqual({ keys: ['devframe:tracing:channels', 'my-plugin:counter'] }) // With key → the value. const value = await client.callTool({ name: 'devframe_state_read', arguments: { key: 'my-plugin:counter' } }) diff --git a/packages/devframe/src/adapters/build.ts b/packages/devframe/src/adapters/build.ts index 2e58d440e..1deaf5875 100644 --- a/packages/devframe/src/adapters/build.ts +++ b/packages/devframe/src/adapters/build.ts @@ -84,6 +84,7 @@ export async function createBuild(d: DevframeDefinition, options: CreateBuildOpt for (const input of d.services ?? []) void ctx.services.install(input, { resolveFrom: d.importMetaUrl }) await ctx.services.ready() + ctx.tracing._applyOptions(d.tracing) await d.setup(ctx) // Bake declared `rpc.snapshot` methods (typically a wire service's RPC the diff --git a/packages/devframe/src/adapters/embedded.ts b/packages/devframe/src/adapters/embedded.ts index cc6275a6f..5f46f4708 100644 --- a/packages/devframe/src/adapters/embedded.ts +++ b/packages/devframe/src/adapters/embedded.ts @@ -22,5 +22,6 @@ export async function createEmbedded(d: DevframeDefinition, options: CreateEmbed for (const input of d.services ?? []) void options.ctx.services.install(input, { resolveFrom: d.importMetaUrl }) await options.ctx.services.ready() + options.ctx.tracing._applyOptions(d.tracing) await d.setup(options.ctx) } diff --git a/packages/devframe/src/adapters/initiate.ts b/packages/devframe/src/adapters/initiate.ts index 1a4dd5162..4cf94732e 100644 --- a/packages/devframe/src/adapters/initiate.ts +++ b/packages/devframe/src/adapters/initiate.ts @@ -304,6 +304,7 @@ export function initDevframe( for (const input of def.services ?? []) void context.services.install(input, { resolveFrom: def.importMetaUrl }) await context.services.ready() + context.tracing._applyOptions(def.tracing) await def.setup(context, setupInfo) const mcp = await mountMcpRoute(app, context, def, base, options.mcp ?? 'auto') diff --git a/packages/devframe/src/events.ts b/packages/devframe/src/events.ts index ebc958d67..87e42c1d9 100644 --- a/packages/devframe/src/events.ts +++ b/packages/devframe/src/events.ts @@ -57,6 +57,21 @@ export const DEVFRAME_EVENTS = { streamingEnd: 'devframe:streaming:end', streamingUploadCancel: 'devframe:streaming:upload-cancel', }, + /** + * Shared-state keys the core node side publishes. The paired request + * methods are the generic `devframe:rpc:server-state:*` endpoints. + */ + sharedState: { + tracingChannels: 'devframe:tracing:channels', + }, + /** + * Streaming channels the core node side owns. Each recording Tracing + * Channel gets its own stream on `devframe:tracing`; the id is published + * as `streamId` in the `devframe:tracing:channels` shared state. + */ + stream: { + tracing: 'devframe:tracing', + }, /** * In-page channel notifications the page script pushes to its panels * (page script → panel), `devframe:` prefix. The paired request methods diff --git a/packages/devframe/src/node/__tests__/host-tracing.test.ts b/packages/devframe/src/node/__tests__/host-tracing.test.ts new file mode 100644 index 000000000..3d8b93e7f --- /dev/null +++ b/packages/devframe/src/node/__tests__/host-tracing.test.ts @@ -0,0 +1,251 @@ +import type { DevframeHost, DevframeNodeContext, DevframeRpcServerFunctions, DevframeTraceRecord, DevframeTracingChannelInfo } from 'devframe/types' +import * as diagnosticsChannel from 'node:diagnostics_channel' +import { mkdtempSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { createRpcStreamingClientHost } from 'devframe/client' +import { DEVFRAME_EVENTS } from 'devframe/constants' +import { createRpcClient } from 'devframe/rpc/client' +import { createWsRpcChannel } from 'devframe/rpc/transports/ws-client' +import { attachWsRpcTransport } from 'devframe/rpc/transports/ws-server' +import { getPort } from 'get-port-please' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { WebSocket } from 'ws' +import { createHostContext } from '../context' +import { RpcFunctionsHostImpl } from '../host-functions' +import { DevframeTracingHostImpl, TRACING_RECORD_BUFFER } from '../host-tracing' +import { createContextRpcServer } from '../rpc-core' + +vi.stubGlobal('WebSocket', WebSocket) + +const tempDirs: string[] = [] +afterEach(() => { + for (const dir of tempDirs.splice(0)) + rmSync(dir, { recursive: true, force: true }) +}) + +function createTestHost(dir: string): DevframeHost { + return { + mountStatic: () => {}, + resolveOrigin: () => 'http://localhost', + getStorageDir: scope => join(dir, scope), + } +} + +async function createCtx(): Promise { + const dir = mkdtempSync(join(tmpdir(), 'devframe-tracing-')) + tempDirs.push(dir) + return createHostContext({ cwd: dir, mode: 'dev', host: createTestHost(dir) }) +} + +async function channelsState(ctx: DevframeNodeContext): Promise> { + const state = await ctx.rpc.sharedState.get>(DEVFRAME_EVENTS.sharedState.tracingChannels) + await new Promise(resolve => setTimeout(resolve, 0)) + return state.value() as Record +} + +let channelSeq = 0 +function uniqueName(): string { + return `test:tracing-${process.pid}-${channelSeq++}` +} + +describe('devframeTracingHost', () => { + it('registers by name or instance, idempotently, and ranks sources', async () => { + const ctx = await createCtx() + const name = uniqueName() + const channel = ctx.tracing.register(name, { description: 'first' }) + expect(channel.start).toBe(diagnosticsChannel.channel(`tracing:${name}:start`)) + expect(ctx.tracing.register(name, { description: 'ignored' })).toBe(channel) + + const instanceName = uniqueName() + const existing = diagnosticsChannel.tracingChannel(instanceName) + expect(ctx.tracing.register(existing)).toBe(existing) + + const configName = uniqueName() + ctx.tracing._applyOptions({ channels: [configName, { name, description: 'ignored too' }] }) + ctx.tracing.record(uniqueName()) + + const byName = Object.fromEntries(ctx.tracing.list().map(info => [info.name, info])) + expect(byName['module.require']).toMatchObject({ source: 'builtin', recording: false, count: 0 }) + expect(byName['net.server.listen']).toMatchObject({ source: 'builtin' }) + expect(byName[name]).toMatchObject({ source: 'registered', description: 'first' }) + expect(byName[instanceName]).toMatchObject({ source: 'registered' }) + expect(byName[configName]).toMatchObject({ source: 'config' }) + expect(Object.values(byName).filter(info => info.source === 'adhoc')).toHaveLength(1) + + const state = await channelsState(ctx) + expect(Object.keys(state).sort()).toEqual(Object.keys(byName).sort()) + }) + + it('records sync and async traces as grouped records while recording', async () => { + const ctx = await createCtx() + const name = uniqueName() + const channel = ctx.tracing.register(name) + const seen: DevframeTraceRecord[] = [] + ctx.tracing.onRecord(name, record => seen.push(record)) + + channel.traceSync(() => 'ignored before record', { id: 0 }) + expect(ctx.tracing.records(name)).toEqual([]) + + ctx.tracing.record(name) + expect(channel.hasSubscribers).toBe(true) + + const sync = channel.traceSync((n: number) => n * 2, { id: 1, socket: { write() {} } }, undefined, 21) + expect(sync).toBe(42) + const async = await channel.tracePromise(async () => 'done', { id: 2 }) + expect(async).toBe('done') + expect(() => channel.traceSync(() => { + throw new TypeError('boom') + }, { id: 3 })).toThrow('boom') + + const records = ctx.tracing.records(name) + expect(records.map(record => record.status)).toEqual(['ok', 'ok', 'error']) + expect(records[0]).toMatchObject({ channel: name, context: { id: 1, socket: {} }, result: 42 }) + expect(records[0]!.events.map(event => event.phase)).toEqual(['start', 'end']) + expect(records[0]!.duration).toBeGreaterThanOrEqual(0) + expect(records[1]!.events.map(event => event.phase)).toEqual(['start', 'end', 'asyncStart', 'asyncEnd']) + expect(records[1]).toMatchObject({ result: 'done' }) + expect(records[2]!.error).toMatchObject({ name: 'TypeError', message: 'boom' }) + expect(records[2]!.events.map(event => event.phase)).toEqual(['start', 'error', 'end']) + + // One listener call per lifecycle event, each carrying the whole record. + expect(seen).toHaveLength(2 + 4 + 3) + expect(seen.at(-1)).toMatchObject({ id: records[2]!.id, status: 'error' }) + + ctx.tracing.stop(name) + expect(channel.hasSubscribers).toBe(false) + channel.traceSync(() => 'after stop', { id: 4 }) + expect(ctx.tracing.records(name)).toHaveLength(3) + const state = await channelsState(ctx) + expect(state[name]).toMatchObject({ recording: false, count: 3 }) + expect(state[name]!.streamId).toBeUndefined() + }) + + it('caps the buffer and clears it', async () => { + const ctx = await createCtx() + const name = uniqueName() + const channel = ctx.tracing.register(name) + ctx.tracing.record(name) + for (let i = 0; i < TRACING_RECORD_BUFFER + 5; i++) + channel.traceSync(() => i, { i }) + const records = ctx.tracing.records(name) + expect(records).toHaveLength(TRACING_RECORD_BUFFER) + expect(records[0]!.context).toEqual({ i: 5 }) + + const before = (await channelsState(ctx))[name]! + expect(before.recording).toBe(true) + ctx.tracing.clear(name) + expect(ctx.tracing.records(name)).toEqual([]) + const after = (await channelsState(ctx))[name]! + expect(after.count).toBe(0) + expect(after.recording).toBe(true) + expect(after.streamId).not.toBe(before.streamId) + }) + + it('does not record its own wire RPC', async () => { + const ctx = await createCtx() + const rpcName = uniqueName() + const channel = ctx.tracing.register(rpcName) + ctx.tracing.record(rpcName) + for (const method of ['devframe:tracing:record', 'devframe:tracing:stop', 'devframe:tracing:clear'] as const) + await ctx.rpc.invokeLocal(method, uniqueName()) + expect(ctx.tracing.records(rpcName)).toEqual([]) + expect(channel.hasSubscribers).toBe(true) + }) + + it('streams records to a client, with replay on resubscribe', async () => { + const ctx = await createCtx() + const port = await getPort({ host: '127.0.0.1', random: true }) + const server = createContextRpcServer({ context: ctx, auth: false }) + const { close } = attachWsRpcTransport(server.rpcGroup, { + port, + host: '127.0.0.1', + onConnected: server.onConnected, + onDisconnected: server.onDisconnected, + }) + + const name = uniqueName() + const channel = ctx.tracing.register(name) + try { + const client = bootClient(port) + await client.rpc.$call('devframe:tracing:record', name) + const streamId = (await channelsState(ctx))[name]!.streamId! + channel.traceSync(() => 1, { n: 1 }) + + const reader = client.streaming.subscribe(DEVFRAME_EVENTS.stream.tracing, streamId) + const first = await reader[Symbol.asyncIterator]().next() + expect(first.value).toMatchObject({ channel: name, context: { n: 1 }, status: 'pending' }) + client.close() + + // A fresh client replays the buffered chunks from the start. + const again = bootClient(port) + const replayed = again.streaming.subscribe(DEVFRAME_EVENTS.stream.tracing, streamId) + const chunks: DevframeTraceRecord[] = [] + for await (const chunk of replayed) { + chunks.push(chunk) + if (chunks.length === 2) + break + } + expect(chunks.map(chunk => chunk.status)).toEqual(['pending', 'ok']) + again.close() + } + finally { + await close() + } + }) + + it('is a no-op that warns once where tracingChannel is missing', async () => { + const ctx = await createCtx() + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + const host = new DevframeTracingHostImpl( + { ...ctx, rpc: new RpcFunctionsHostImpl(ctx) }, + { channel: diagnosticsChannel.channel }, + ) + expect(host.supported).toBe(false) + const name = uniqueName() + const channel = host.register(name) + expect(channel.traceSync(() => 'ran')).toBe('ran') + await expect(channel.tracePromise(async () => 'ran')).resolves.toBe('ran') + expect(channel.hasSubscribers).toBe(false) + + host.record(name) + host.record(name) + expect(host.list().find(info => info.name === name)).toMatchObject({ recording: false }) + expect(warn).toHaveBeenCalledTimes(1) + expect(String(warn.mock.calls[0]![0])).toContain('DF0081') + warn.mockRestore() + }) +}) + +interface FakeClient { + rpc: ReturnType any>>> + streaming: ReturnType + close: () => void +} + +function bootClient(port: number): FakeClient { + const clientFns: Record any> = {} + const rpc = createRpcClient any>>( + clientFns, + { channel: createWsRpcChannel({ url: `ws://127.0.0.1:${port}` }) }, + ) + // Mimics the `DevframeRpcClient` surface `createRpcStreamingClientHost` uses. + const fakeRpcClient = { + isTrusted: true, + events: { on: () => () => {} }, + client: { + register(def: { name: string, handler: (...args: any[]) => any }) { + clientFns[def.name] = def.handler + }, + }, + callEvent: (name: string, ...args: any[]) => (rpc as any).$callEvent(name, ...args), + } as any + const streaming = createRpcStreamingClientHost(fakeRpcClient) + return { + rpc, + streaming, + close() { + (rpc as any).$close() + }, + } +} diff --git a/packages/devframe/src/node/__tests__/tracing-serialize.test.ts b/packages/devframe/src/node/__tests__/tracing-serialize.test.ts new file mode 100644 index 000000000..c7edf4b6c --- /dev/null +++ b/packages/devframe/src/node/__tests__/tracing-serialize.test.ts @@ -0,0 +1,73 @@ +import { Socket } from 'node:net' +import { describe, expect, it } from 'vitest' +import { serializeTraceValue } from '../tracing-serialize' + +describe('serializeTraceValue', () => { + it('passes primitives through and stringifies the ones JSON cannot hold', () => { + expect(serializeTraceValue({ a: 1, b: 'x', c: true, d: null, e: 10n, f: Number.NaN })) + .toEqual({ a: 1, b: 'x', c: true, d: null, e: '10n', f: 'NaN' }) + }) + + it('drops functions, symbols and undefined from objects, nulls them in arrays', () => { + expect(serializeTraceValue({ fn() {}, sym: Symbol('s'), u: undefined, list: [() => 1, undefined, 2] })) + .toEqual({ list: [null, null, 2] }) + expect(serializeTraceValue(() => 1)).toBeNull() + }) + + it('caps depth and marks cycles only for true cycles', () => { + const shared = { leaf: 1 } + const cyclic: Record = { shared, again: shared } + cyclic.self = cyclic + expect(serializeTraceValue(cyclic)).toEqual({ + shared: { leaf: 1 }, + again: { leaf: 1 }, + self: '[Circular]', + }) + expect(serializeTraceValue({ a: { b: { c: { d: { e: 1 } } } } }, { maxDepth: 3 })) + .toEqual({ a: { b: { c: '[Object]' } } }) + expect(serializeTraceValue([[[[1]]]], { maxDepth: 2 })).toEqual([['[Array]']]) + }) + + it('truncates long strings and wide objects', () => { + const long = 'x'.repeat(10) + expect(serializeTraceValue(long, { maxString: 4 })).toBe('xxxx… (6 more chars)') + const wide = Object.fromEntries(Array.from({ length: 5 }, (_, i) => [`k${i}`, i])) + expect(serializeTraceValue(wide, { maxKeys: 2 })).toEqual({ 'k0': 0, 'k1': 1, '…': '3 more keys' }) + }) + + it('represents errors, dates, maps, sets and binary data', () => { + const error = new TypeError('boom') + const out = serializeTraceValue({ + error, + date: new Date('2026-01-02T03:04:05.000Z'), + map: new Map([['k', { v: 1 }]]), + set: new Set([1, 2]), + bytes: new Uint8Array(3), + buffer: new ArrayBuffer(8), + }) as Record + expect(out.error).toMatchObject({ name: 'TypeError', message: 'boom' }) + expect((out.error as { stack: string }).stack).toContain('boom') + expect(out.date).toBe('2026-01-02T03:04:05.000Z') + expect(out.map).toEqual([['k', { v: 1 }]]) + expect(out.set).toEqual([1, 2]) + expect(out.bytes).toBe('[Uint8Array 3]') + expect(out.buffer).toBe('[ArrayBuffer 8]') + }) + + it('never throws on a request-like object holding a socket and a throwing getter', () => { + const socket = new Socket() + const request = { + method: 'GET', + url: '/x', + socket, + get poison(): never { + throw new Error('no access') + }, + } + const out = serializeTraceValue(request) as Record + expect(out.method).toBe('GET') + expect(typeof out.socket).toBe('object') + expect(out.poison).toMatchObject({ name: 'Error', message: 'no access' }) + socket.destroy() + }) +}) diff --git a/packages/devframe/src/node/context.ts b/packages/devframe/src/node/context.ts index 6fd6c3721..771d4d6ad 100644 --- a/packages/devframe/src/node/context.ts +++ b/packages/devframe/src/node/context.ts @@ -6,6 +6,7 @@ import { DevframeAgentHost } from './host-agent' import { DevframeDiagnosticsHost } from './host-diagnostics' import { RpcFunctionsHostImpl } from './host-functions' import { DevframeServicesHostImpl } from './host-services' +import { DevframeTracingHostImpl } from './host-tracing' import { DevframeViewHost } from './host-views' import { BUILTIN_AGENT_RPC } from './rpc' import { createScopedNodeContext } from './scope' @@ -53,6 +54,7 @@ export async function createHostContext(options: CreateHostContextOptions): Prom diagnostics: undefined!, agent: undefined!, services: undefined!, + tracing: undefined!, staticConfig: {}, scope: undefined!, } @@ -64,6 +66,7 @@ export async function createHostContext(options: CreateHostContextOptions): Prom context.views = viewsHost context.diagnostics = diagnosticsHost context.services = new DevframeServicesHostImpl(context) + context.tracing = new DevframeTracingHostImpl(context) // Agent host must be constructed after `rpcHost` so it can subscribe // to `onChanged`; it auto-discovers RPC functions flagged with diff --git a/packages/devframe/src/node/diagnostics.ts b/packages/devframe/src/node/diagnostics.ts index 7a5b9a956..19ebfa3aa 100644 --- a/packages/devframe/src/node/diagnostics.ts +++ b/packages/devframe/src/node/diagnostics.ts @@ -220,5 +220,10 @@ export const diagnostics = defineDiagnostics({ `The \`mcp\` option is enabled, but the optional peer "@devframes/agentic" could not be loaded: ${p.reason}`, fix: 'Install `@devframes/agentic` next to devframe (the MCP adapter and the MCP SDK live there), or remove the explicit `mcp` setting.', }, + DF0081: { + why: (p: { runtime: string }) => + `Tracing Channels are unavailable: this runtime (${p.runtime}) does not provide \`node:diagnostics_channel\`'s \`tracingChannel\`, so \`ctx.tracing\` records nothing.`, + fix: 'Run under Node.js 22+ or Bun to record Tracing Channels. Every `ctx.tracing` method is a no-op here.', + }, }, }) diff --git a/packages/devframe/src/node/host-tracing.ts b/packages/devframe/src/node/host-tracing.ts new file mode 100644 index 000000000..16a661b67 --- /dev/null +++ b/packages/devframe/src/node/host-tracing.ts @@ -0,0 +1,297 @@ +import type { + DevframeNodeContext, + DevframeTracePhase, + DevframeTraceRecord, + DevframeTracingChannelInfo, + DevframeTracingChannelSource, + DevframeTracingHost, + DevframeTracingOptions, + RpcStreamingChannel, +} from 'devframe/types' +import type { SharedState } from 'devframe/utils/shared-state' +import type { StreamSink } from 'devframe/utils/streaming-channel' +import type { TracingChannel, TracingChannelSubscribers } from 'node:diagnostics_channel' +import * as diagnosticsChannel from 'node:diagnostics_channel' +import { nanoid } from 'devframe/utils/nanoid' +import { DEVFRAME_EVENTS } from '../events' +import { diagnostics } from './diagnostics' +import { detectServerRuntime } from './runtime' +import { serializeTraceValue } from './tracing-serialize' + +export const TRACING_RECORD_BUFFER = 500 +const COUNT_FLUSH_MS = 100 + +/** Tracing Channels Node.js itself publishes. */ +const BUILTIN_CHANNELS: Record = { + 'module.require': 'Every CommonJS require() call', + 'net.server.listen': 'net.Server listen() calls', +} + +/** Later sources win when the same name arrives twice. */ +const SOURCE_RANK: Record = { + adhoc: 0, + builtin: 1, + config: 2, + registered: 3, +} + +type TracingModule = Pick & Partial> + +interface ChannelEntry { + info: DevframeTracingChannelInfo + channel: TracingChannel + records: DevframeTraceRecord[] + byContext: WeakMap + subscribers?: Partial> + sink?: StreamSink + listeners: Set<(record: DevframeTraceRecord) => void> +} + +export class DevframeTracingHostImpl implements DevframeTracingHost { + readonly supported: boolean + private readonly entries = new Map() + private readonly stream: RpcStreamingChannel + private readonly state: Promise>> + private countTimer: ReturnType | undefined + private warnedUnsupported = false + + constructor( + private readonly context: DevframeNodeContext, + private readonly module: TracingModule = diagnosticsChannel, + ) { + this.supported = typeof module.tracingChannel === 'function' + this.stream = context.rpc.streaming.create(DEVFRAME_EVENTS.stream.tracing, { + replayWindow: TRACING_RECORD_BUFFER, + closedStreamRetention: 0, + }) + this.state = context.rpc.sharedState.get>( + DEVFRAME_EVENTS.sharedState.tracingChannels, + { initialValue: {} }, + ) + for (const [name, description] of Object.entries(BUILTIN_CHANNELS)) + this.add(name, 'builtin', description) + this.registerRpc() + } + + _applyOptions(options: DevframeTracingOptions | undefined): void { + for (const entry of options?.channels ?? []) { + const { name, description } = typeof entry === 'string' ? { name: entry, description: undefined } : entry + this.add(name, 'config', description) + } + } + + register(channel: string | TracingChannel, meta?: { description?: string }): TracingChannel { + const name = typeof channel === 'string' ? channel : baseName(channel) + return this.add(name, 'registered', meta?.description, typeof channel === 'string' ? undefined : channel).channel + } + + list(): DevframeTracingChannelInfo[] { + return Array.from(this.entries.values(), entry => ({ ...entry.info })) + } + + record(name: string): void { + if (!this.supported) { + if (!this.warnedUnsupported) { + this.warnedUnsupported = true + diagnostics.DF0081({ runtime: detectServerRuntime() }) + } + return + } + const entry = this.add(name, 'adhoc') + if (entry.subscribers) + return + entry.sink = this.stream.start() + entry.info.recording = true + entry.info.streamId = entry.sink.id + entry.subscribers = { + start: message => this.onPhase(entry, 'start', message), + end: message => this.onPhase(entry, 'end', message), + asyncStart: message => this.onPhase(entry, 'asyncStart', message), + asyncEnd: message => this.onPhase(entry, 'asyncEnd', message), + error: message => this.onPhase(entry, 'error', message), + } + entry.channel.subscribe(entry.subscribers) + void this.publish() + } + + stop(name: string): void { + const entry = this.entries.get(name) + if (!entry?.subscribers) + return + entry.channel.unsubscribe(entry.subscribers) + entry.subscribers = undefined + entry.sink?.close() + entry.sink = undefined + entry.info.recording = false + entry.info.streamId = undefined + void this.publish() + } + + records(name: string): DevframeTraceRecord[] { + return (this.entries.get(name)?.records ?? []).map(record => ({ ...record })) + } + + clear(name: string): void { + const entry = this.entries.get(name) + if (!entry) + return + entry.records = [] + entry.byContext = new WeakMap() + entry.info.count = 0 + if (entry.sink) { + // A fresh stream drops the replay buffer, so a client that reconnects + // after a clear does not see the cleared records again. + entry.sink.close() + entry.sink = this.stream.start() + entry.info.streamId = entry.sink.id + } + void this.publish() + } + + onRecord(name: string, fn: (record: DevframeTraceRecord) => void): () => void { + const entry = this.add(name, 'adhoc') + entry.listeners.add(fn) + return () => { + entry.listeners.delete(fn) + } + } + + private add(name: string, source: DevframeTracingChannelSource, description?: string, channel?: TracingChannel): ChannelEntry { + let entry = this.entries.get(name) + if (!entry) { + entry = { + info: { name, source, recording: false, count: 0 }, + channel: channel ?? this.createChannel(name), + records: [], + byContext: new WeakMap(), + listeners: new Set(), + } + this.entries.set(name, entry) + } + else if (SOURCE_RANK[source] > SOURCE_RANK[entry.info.source]) { + entry.info.source = source + } + if (description && !entry.info.description) + entry.info.description = description + void this.publish() + return entry + } + + private createChannel(name: string): TracingChannel { + if (this.module.tracingChannel) + return this.module.tracingChannel(name) + return noopTracingChannel(this.module, name) + } + + private onPhase(entry: ChannelEntry, phase: DevframeTracePhase, message: unknown): void { + const at = Date.now() + const keyed = typeof message === 'object' && message !== null + const record = (keyed ? entry.byContext.get(message) : undefined) ?? this.openRecord(entry, at, keyed ? message : undefined) + + record.events.push({ phase, at }) + record.duration = at - record.startedAt + const { result, error, ...rest } = keyed ? (message as { result?: unknown, error?: unknown }) : {} + record.context = serializeTraceValue(keyed ? rest : message) + if (result !== undefined) + record.result = serializeTraceValue(result) + if (phase === 'error') { + record.status = 'error' + const serialized = serializeTraceValue(error) + record.error = isErrorShape(serialized) ? serialized : { name: 'Error', message: String(error) } + } + else if ((phase === 'end' || phase === 'asyncEnd') && record.status === 'pending') { + record.status = 'ok' + } + + const snapshot = { ...record, events: [...record.events] } + entry.sink?.write(snapshot) + for (const fn of entry.listeners) + fn(snapshot) + } + + private openRecord(entry: ChannelEntry, at: number, context: object | undefined): DevframeTraceRecord { + const record: DevframeTraceRecord = { + id: nanoid(), + channel: entry.info.name, + startedAt: at, + status: 'pending', + context: null, + events: [], + } + if (context) + entry.byContext.set(context, record) + entry.records.push(record) + if (entry.records.length > TRACING_RECORD_BUFFER) + entry.records.shift() + entry.info.count = entry.records.length + this.scheduleCountFlush() + return record + } + + /** Counts change on every record; batch them so the state is not spammed. */ + private scheduleCountFlush(): void { + if (this.countTimer) + return + this.countTimer = setTimeout(() => { + this.countTimer = undefined + void this.publish() + }, COUNT_FLUSH_MS) + } + + private async publish(): Promise { + const state = await this.state + state.mutate((value) => { + for (const entry of this.entries.values()) + value[entry.info.name] = { ...entry.info } + }) + } + + private registerRpc(): void { + const rpc = this.context.rpc + rpc.register({ + name: 'devframe:tracing:record', + type: 'action', + handler: async (name: string) => this.record(name), + }) + rpc.register({ + name: 'devframe:tracing:stop', + type: 'action', + handler: async (name: string) => this.stop(name), + }) + rpc.register({ + name: 'devframe:tracing:clear', + type: 'action', + handler: async (name: string) => this.clear(name), + }) + } +} + +/** `tracing::start` → ``. */ +function baseName(channel: TracingChannel): string { + const name = String(channel.start.name) + return name.replace(/^tracing:/, '').replace(/:start$/, '') +} + +function isErrorShape(value: unknown): value is { name: string, message: string, stack?: string } { + return typeof value === 'object' && value !== null && typeof (value as { name?: unknown }).name === 'string' && typeof (value as { message?: unknown }).message === 'string' +} + +/** + * Stand-in for runtimes without `tracingChannel`: the trace helpers call + * the function directly and nothing is published. + */ +function noopTracingChannel(module: TracingModule, name: string): TracingChannel { + return { + start: module.channel(`tracing:${name}:start`), + end: module.channel(`tracing:${name}:end`), + asyncStart: module.channel(`tracing:${name}:asyncStart`), + asyncEnd: module.channel(`tracing:${name}:asyncEnd`), + error: module.channel(`tracing:${name}:error`), + hasSubscribers: false, + subscribe() {}, + unsubscribe() {}, + traceSync: (fn, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), + tracePromise: (fn, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), + traceCallback: (fn, _position, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), + } +} diff --git a/packages/devframe/src/node/scope.ts b/packages/devframe/src/node/scope.ts index 7888606e4..40fa98ee4 100644 --- a/packages/devframe/src/node/scope.ts +++ b/packages/devframe/src/node/scope.ts @@ -56,6 +56,7 @@ export function createScopedNodeContext( views: context.views, diagnostics: context.diagnostics, agent: context.agent, + tracing: context.tracing, scope: context.scope, } } diff --git a/packages/devframe/src/node/tracing-serialize.ts b/packages/devframe/src/node/tracing-serialize.ts new file mode 100644 index 000000000..9e1a24057 --- /dev/null +++ b/packages/devframe/src/node/tracing-serialize.ts @@ -0,0 +1,93 @@ +import type { SerializedValue } from 'devframe/types' + +export interface SerializeTraceValueOptions { + maxDepth?: number + maxString?: number + maxKeys?: number +} + +/** + * Flatten an arbitrary trace payload (request objects, sockets, errors, + * cycles) into a JSON-shaped value. Never throws: anything it cannot + * represent becomes a short placeholder string or is dropped. + */ +export function serializeTraceValue(value: unknown, options: SerializeTraceValueOptions = {}): SerializedValue { + const { maxDepth = 4, maxString = 2000, maxKeys = 50 } = options + const seen = new WeakSet() + + function visit(input: unknown, depth: number): SerializedValue | undefined { + switch (typeof input) { + case 'string': + return input.length > maxString ? `${input.slice(0, maxString)}… (${input.length - maxString} more chars)` : input + case 'number': + return Number.isFinite(input) ? input : String(input) + case 'boolean': + return input + case 'bigint': + return `${input}n` + case 'undefined': + case 'function': + case 'symbol': + return undefined + } + if (input === null) + return null + return visitObject(input as object, depth) + } + + function visitObject(input: object, depth: number): SerializedValue { + if (input instanceof Error) { + return { + name: input.name, + message: input.message, + ...(input.stack ? { stack: input.stack } : {}), + } + } + if (input instanceof Date) + return Number.isNaN(input.getTime()) ? 'Invalid Date' : input.toISOString() + if (ArrayBuffer.isView(input)) + return `[${input.constructor.name} ${input.byteLength}]` + if (input instanceof ArrayBuffer) + return `[ArrayBuffer ${input.byteLength}]` + + if (seen.has(input)) + return '[Circular]' + const isList = Array.isArray(input) || input instanceof Set || input instanceof Map + if (depth >= maxDepth) + return isList ? '[Array]' : '[Object]' + seen.add(input) + try { + return visitChildren(input, depth) + } + finally { + seen.delete(input) + } + } + + function visitChildren(input: object, depth: number): SerializedValue { + if (Array.isArray(input) || input instanceof Set) + return Array.from(input, item => visit(item, depth + 1) ?? null) + if (input instanceof Map) + return Array.from(input, ([k, v]) => [visit(k, depth + 1) ?? null, visit(v, depth + 1) ?? null]) + + const out: { [key: string]: SerializedValue } = {} + const keys = Object.keys(input) + for (const key of keys.slice(0, maxKeys)) { + let raw: unknown + try { + raw = (input as Record)[key] + } + catch (error) { + raw = error + } + const serialized = visit(raw, depth + 1) + if (serialized !== undefined) + out[key] = serialized + } + if (keys.length > maxKeys) + out['…'] = `${keys.length - maxKeys} more keys` + return out + } + + return visit(value, 0) ?? null +} diff --git a/packages/devframe/src/types/context.ts b/packages/devframe/src/types/context.ts index 1d7881c99..6866fbc9e 100644 --- a/packages/devframe/src/types/context.ts +++ b/packages/devframe/src/types/context.ts @@ -3,6 +3,7 @@ import type { DevframeDiagnosticsHost } from './diagnostics' import type { DevframeHost } from './host' import type { DevframeScopedNodeContext, SettingsForNamespace } from './scope' import type { DevframeServicesHost } from './services' +import type { DevframeTracingHost } from './tracing' import type { DevframeViewHost } from './views' export interface DevframeCapabilities { @@ -62,6 +63,11 @@ export interface DevframeNodeContext { * absorb setup-order differences between provider and consumer. */ services: DevframeServicesHost + /** + * Node.js Tracing Channel host: lists known `TracingChannel`s, subscribes + * on demand, and folds their lifecycle events into trace records. + */ + tracing: DevframeTracingHost /** * This context's own {@link ConnectionMeta.configs}: static, boot-time * config a host publishes once through the connection handshake and every diff --git a/packages/devframe/src/types/devframe.ts b/packages/devframe/src/types/devframe.ts index f1a173713..2117f8d47 100644 --- a/packages/devframe/src/types/devframe.ts +++ b/packages/devframe/src/types/devframe.ts @@ -4,6 +4,7 @@ import type { DevframeAuthHandler } from '../node/auth/handler' import type { DevframeNodeContext } from './context' import type { StaticAssetsSource } from './remote-assets' import type { DevframeServiceInput } from './services' +import type { DevframeTracingOptions } from './tracing' /** * Classification of how a devframe is being deployed. Hosted adapters @@ -419,6 +420,12 @@ export interface DevframeDefinition { * `client.services.has(pkg)` and degrade. */ services?: DevframeServiceInput[] + /** + * Node.js Tracing Channels the app publishes, listed for inspection + * tooling. Each entry is registered through `ctx.tracing.register()` + * before `setup(ctx)` runs. Recording stays off until a client asks. + */ + tracing?: DevframeTracingOptions /** * Author's SPA dist, served as the devframe's UI. A local directory, or * a {@link StaticAssetsSource} remote declaration (`{ package, version }`) diff --git a/packages/devframe/src/types/index.ts b/packages/devframe/src/types/index.ts index a406a920d..84713767f 100644 --- a/packages/devframe/src/types/index.ts +++ b/packages/devframe/src/types/index.ts @@ -10,4 +10,5 @@ export * from './rpc' export * from './rpc-augments' export * from './scope' export * from './services' +export * from './tracing' export * from './views' diff --git a/packages/devframe/src/types/rpc-augments.ts b/packages/devframe/src/types/rpc-augments.ts index 05a5d2cf2..77541d925 100644 --- a/packages/devframe/src/types/rpc-augments.ts +++ b/packages/devframe/src/types/rpc-augments.ts @@ -164,6 +164,29 @@ export interface DevframeRpcServerFunctions { * @internal */ 'devframe:streaming:upload-end': (channel: string, id: string, error?: { name: string, message: string }) => Promise + /** + * Subscribe to a Tracing Channel and start folding its events into + * records on a `devframe:tracing` stream (id published as `streamId` in + * `devframe:tracing:channels`). Wired by `DevframeTracingHost`; do not + * register manually. + * + * @internal + */ + 'devframe:tracing:record': (name: string) => Promise + /** + * Unsubscribe from a Tracing Channel. Buffered records stay. Wired by + * `DevframeTracingHost`; do not register manually. + * + * @internal + */ + 'devframe:tracing:stop': (name: string) => Promise + /** + * Drop a Tracing Channel's buffered records. Wired by + * `DevframeTracingHost`; do not register manually. + * + * @internal + */ + 'devframe:tracing:clear': (name: string) => Promise } /** @@ -178,4 +201,10 @@ export interface DevframeRpcSharedStates { * reactivity). Read-only from the browser. */ 'devframe:services': import('./services').DevframeServicesState + /** + * Known Tracing Channels keyed by base name, with their source and + * recording status. Written by the node tracing host. Read-only from the + * browser. + */ + 'devframe:tracing:channels': Record } diff --git a/packages/devframe/src/types/scope.ts b/packages/devframe/src/types/scope.ts index 128fc1d7e..fc442c3b4 100644 --- a/packages/devframe/src/types/scope.ts +++ b/packages/devframe/src/types/scope.ts @@ -11,6 +11,7 @@ import type { RpcStreamingChannelOptions, } from './rpc' import type { DevframeRpcClientFunctions, DevframeRpcServerFunctions, DevframeRpcSharedStates } from './rpc-augments' +import type { DevframeTracingHost } from './tracing' import type { DevframeViewHost } from './views' // Callable guard so `Parameters` / `ReturnType` always have a function to @@ -218,6 +219,7 @@ export interface DevframeScopedNodeContext +} + +/** + * Node-side Tracing Channel host, exposed as `ctx.tracing`. Wraps + * `node:diagnostics_channel`'s `TracingChannel`: keeps the list of known + * channels, subscribes on demand, folds lifecycle events into + * {@link DevframeTraceRecord}s, and advertises both over RPC. + * + * On a runtime without `tracingChannel` every method is a no-op; + * `record()` reports `DF0081` once. + */ +export interface DevframeTracingHost { + /** + * Declare a Tracing Channel and get the Node `TracingChannel` back, so a + * producer can call `tracePromise` / `traceSync` on it. Idempotent: the + * same name returns the same channel. Accepts an existing instance too. + */ + register: (channel: string | TracingChannel, meta?: { description?: string }) => TracingChannel + list: () => DevframeTracingChannelInfo[] + /** Subscribe to the channel and start folding events into records. */ + record: (name: string) => void + /** Unsubscribe. Records stay in the buffer. */ + stop: (name: string) => void + /** Buffered records, oldest first. */ + records: (name: string) => DevframeTraceRecord[] + clear: (name: string) => void + /** Called with the whole record on every lifecycle update. */ + onRecord: (name: string, fn: (record: DevframeTraceRecord) => void) => () => void + /** + * Adapters call this with a definition's or hub's `tracing` field before + * `setup()` runs. Wired by the adapters automatically. + * + * @internal + */ + _applyOptions: (options: DevframeTracingOptions | undefined) => void +} diff --git a/packages/hub/src/node/__tests__/install-devframe.test.ts b/packages/hub/src/node/__tests__/install-devframe.test.ts index 1bd28d691..c95870e75 100644 --- a/packages/hub/src/node/__tests__/install-devframe.test.ts +++ b/packages/hub/src/node/__tests__/install-devframe.test.ts @@ -38,6 +38,9 @@ function createContext(): DevframeHubContext { install: () => Promise.resolve(undefined), ready: () => Promise.resolve(), }, + tracing: { + _applyOptions: () => {}, + }, } const context = partial as DevframeHubContext context.docks = new DevframeDocksHost(context) diff --git a/packages/hub/src/node/build.ts b/packages/hub/src/node/build.ts index 71526a295..ad2fa2129 100644 --- a/packages/hub/src/node/build.ts +++ b/packages/hub/src/node/build.ts @@ -1,5 +1,5 @@ /* eslint-disable no-console */ -import type { ConnectionMeta, DevframeServiceInput, DevframeStorageScope } from 'devframe/types' +import type { ConnectionMeta, DevframeServiceInput, DevframeStorageScope, DevframeTracingOptions } from 'devframe/types' import type { ClientScriptEntry } from '../types/docks' import type { CreateHubContextOptions, DevframeHubContext } from './context' import type { DevframeHubUi, DevframesInput, DockRendererRegistration } from './initiate' @@ -50,6 +50,8 @@ export interface BuildHubOptions { context?: DevframeHubContext /** Host-level wire services, same contract as `initHub({ services })`. */ services?: DevframeServiceInput[] + /** Host-level Tracing Channels, same contract as `initHub({ tracing })`. */ + tracing?: DevframeTracingOptions /** Extra RPC declarations registered at context creation. */ rpcDeclarations?: CreateHubContextOptions['builtinRpcDeclarations'] /** @@ -183,6 +185,7 @@ async function createAndMountContext(options: BuildHubOptions, base: string, cwd const devframes = await resolveDevframesInput(options.devframes ?? []) for (const input of options.services ?? []) void ctx.services.install(input) + ctx.tracing._applyOptions(options.tracing) const setups = await mountDevframes(ctx, devframes, base) await ctx.services.ready() diff --git a/packages/hub/src/node/initiate.ts b/packages/hub/src/node/initiate.ts index 3edb91ed0..0b68cd484 100644 --- a/packages/hub/src/node/initiate.ts +++ b/packages/hub/src/node/initiate.ts @@ -2,7 +2,7 @@ import type { AgenticMcpModule, DevframeInstanceRecord, InstanceShellApi, Resolv import type { DevframeAuthHandler } from 'devframe/node/auth' import type { AuthBannerFunction } from 'devframe/recipes/interactive-auth' import type { WsOriginRegistry } from 'devframe/rpc/transports/ws-server' -import type { ConnectionMeta, DevframeDefinition, DevframeServiceInput, DevframeSseOptions, DevframeStorageScope, DevframeWsOptions, McpRouteOptions, McpSetting } from 'devframe/types' +import type { ConnectionMeta, DevframeDefinition, DevframeServiceInput, DevframeSseOptions, DevframeStorageScope, DevframeTracingOptions, DevframeWsOptions, McpRouteOptions, McpSetting } from 'devframe/types' import type { Buffer } from 'node:buffer' import type { IncomingMessage, Server as NodeHttpServer, ServerResponse } from 'node:http' import type { Duplex } from 'node:stream' @@ -176,6 +176,11 @@ export interface InitHubOptions { * `services: [createShikiService({ themes })]`. */ services?: DevframeServiceInput[] + /** + * Host-level Node.js Tracing Channels to list, on top of whatever the + * mounted devframes declare in their own `tracing` field. + */ + tracing?: DevframeTracingOptions /** * Extra RPC declarations registered at context creation, alongside the * hub built-ins, forwarded to `createHubContext`'s @@ -463,6 +468,7 @@ export function initHub(options: InitHubOptions): HubInstance { // collection alongside every devframe's own declared services. for (const input of options.services ?? []) void ctx.services.install(input) + ctx.tracing._applyOptions(options.tracing) const setups = await mountDevframes(ctx, devframes, base) // Construct every collected service once, then run the setups, so a diff --git a/packages/hub/src/node/install-devframe.ts b/packages/hub/src/node/install-devframe.ts index 258b41f0b..706eb585d 100644 --- a/packages/hub/src/node/install-devframe.ts +++ b/packages/hub/src/node/install-devframe.ts @@ -153,6 +153,7 @@ export async function prepareDevframe( // the `ctx.services.ready()` barrier the hub fires before running setups. for (const input of d.services ?? []) void ctx.services.install(input, { resolveFrom: d.importMetaUrl }) + ctx.tracing._applyOptions(d.tracing) return () => Promise.resolve(d.setup(ctx)) } diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts index 4178d6ddf..ee8bdfd1b 100644 --- a/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts @@ -8,6 +8,7 @@ export interface BuildHubOptions { devframes?: DevframesInput; context?: DevframeHubContext; services?: DevframeServiceInput[]; + tracing?: DevframeTracingOptions; rpcDeclarations?: CreateHubContextOptions['builtinRpcDeclarations']; configure?: (_: DevframeHubContext) => void | Promise; ui?: DevframeHubUi; diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts index 75b0a5ff4..f4616b9e7 100644 --- a/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts @@ -39,6 +39,7 @@ export interface InitHubOptions { base: string; devframes?: DevframesInput; services?: DevframeServiceInput[]; + tracing?: DevframeTracingOptions; rpcDeclarations?: CreateHubContextOptions['builtinRpcDeclarations']; context?: DevframeHubContext; configure?: (_: DevframeHubContext) => void | Promise; diff --git a/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts index d3f0cf78c..3762bed73 100644 --- a/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts @@ -33,6 +33,12 @@ export declare const DEVFRAME_EVENTS: { readonly streamingEnd: "devframe:streaming:end"; readonly streamingUploadCancel: "devframe:streaming:upload-cancel"; }; + readonly sharedState: { + readonly tracingChannels: "devframe:tracing:channels"; + }; + readonly stream: { + readonly tracing: "devframe:tracing"; + }; readonly inPageChannel: { readonly panelStateUpdated: "devframe:in-page:panel-state:updated"; readonly panelStatePatch: "devframe:in-page:panel-state:patch"; diff --git a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts index 9d0ebbbfd..552144922 100644 --- a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts @@ -162,6 +162,7 @@ export interface DevframeDefinition { build?: boolean; }; services?: DevframeServiceInput[]; + tracing?: DevframeTracingOptions; clientAssets?: StaticAssetsSource; rpc?: DevframeRpcOptions; setup: (_: DevframeNodeContext, _?: DevframeSetupInfo) => void | Promise; @@ -207,6 +208,7 @@ export interface DevframeNodeContext { diagnostics: DevframeDiagnosticsHost; agent: DevframeAgentHost; services: DevframeServicesHost; + tracing: DevframeTracingHost; staticConfig: Partial; scope: { (_: NS): DevframeScopedNodeContext>; @@ -291,9 +293,13 @@ export interface DevframeRpcServerFunctions { name: string; message: string; }) => Promise; + 'devframe:tracing:record': (_: string) => Promise; + 'devframe:tracing:stop': (_: string) => Promise; + 'devframe:tracing:clear': (_: string) => Promise; } export interface DevframeRpcSharedStates { 'devframe:services': DevframeServicesState; + 'devframe:tracing:channels': Record; } export interface DevframeScopedNodeContext = Record> { readonly namespace: NS; @@ -307,6 +313,7 @@ export interface DevframeScopedNodeContext { @@ -386,6 +393,52 @@ export interface DevframeSetupInfo { export interface DevframeSseOptions { route?: string; } +export interface DevframeTraceEvent { + phase: DevframeTracePhase; + at: number; +} +export interface DevframeTraceRecord { + id: string; + channel: string; + startedAt: number; + duration?: number; + status: 'pending' | 'ok' | 'error'; + context: SerializedValue; + result?: SerializedValue; + error?: { + name: string; + message: string; + stack?: string; + }; + events: DevframeTraceEvent[]; +} +export interface DevframeTracingChannelInfo { + name: string; + description?: string; + source: DevframeTracingChannelSource; + recording: boolean; + streamId?: string; + count: number; +} +export interface DevframeTracingChannelInput { + name: string; + description?: string; +} +export interface DevframeTracingHost { + register: (_: string | TracingChannel, _?: { + description?: string; + }) => TracingChannel; + list: () => DevframeTracingChannelInfo[]; + record: (_: string) => void; + stop: (_: string) => void; + records: (_: string) => DevframeTraceRecord[]; + clear: (_: string) => void; + onRecord: (_: string, _: (_: DevframeTraceRecord) => void) => () => void; + _applyOptions: (_: DevframeTracingOptions | undefined) => void; +} +export interface DevframeTracingOptions { + channels?: Array; +} export interface DevframeViewHost { buildStaticDirs: { baseUrl: string; @@ -549,6 +602,8 @@ export type DevframeSnapshotRpcEntry = string | { }; export type DevframeSnapshotRpcInputs = readonly (readonly unknown[])[] | ((_: DevframeNodeContext) => readonly (readonly unknown[])[] | Promise); export type DevframeStorageScope = 'workspace' | 'project' | 'global'; +export type DevframeTracePhase = 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error'; +export type DevframeTracingChannelSource = 'builtin' | 'registered' | 'config' | 'adhoc'; export type McpAuthorization = string | ((_: Request) => boolean | Promise) | false; export type McpSetting = boolean | 'auto' | McpRouteOptions; export type RemoteAssetsProvider = 'jsdelivr' | 'unpkg' | RemoteAssetsProviderCustom; @@ -563,6 +618,9 @@ export type ScopedClientFunctions = { [K in keyof DevframeRpc export type ScopedRpcFn = `${NS}:${T}` extends keyof Registry ? Extract : AnyRpcFn; export type ScopedServerFunctions = { [K in keyof DevframeRpcServerFunctions as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcServerFunctions[K]; }; export type ScopedSharedStates = { [K in keyof DevframeRpcSharedStates as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcSharedStates[K]; }; +export type SerializedValue = string | number | boolean | null | SerializedValue[] | { + [key: string]: SerializedValue; +}; export type SettingsForNamespace = NS extends keyof DevframeSettingsRegistry ? DevframeSettingsRegistry[NS] extends Record ? DevframeSettingsRegistry[NS] : Record : Record; export type StaticAssetsSource = string | RemoteAssets; // #endregion diff --git a/tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts index 4c08e1e91..36fe0f26e 100644 --- a/tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts @@ -371,6 +371,12 @@ export declare const diagnostics: import("nostics").Diagnostics<{ }) => string; readonly fix: "Install `@devframes/agentic` next to devframe (the MCP adapter and the MCP SDK live there), or remove the explicit `mcp` setting."; }; + readonly DF0081: { + readonly why: (p: { + runtime: string; + }) => string; + readonly fix: "Run under Node.js 22+ or Bun to record Tracing Channels. Every `ctx.tracing` method is a no-op here."; + }; }, readonly [(d: import("nostics").Diagnostic, { method }?: { method?: "log" | "warn" | "error"; }) => void], never>; diff --git a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts index 2604d37fd..03a24c285 100644 --- a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts @@ -61,6 +61,14 @@ export { DevframeSnapshotRpcEntry } export { DevframeSnapshotRpcInputs } export { DevframeSseOptions } export { DevframeStorageScope } +export { DevframeTraceEvent } +export { DevframeTracePhase } +export { DevframeTraceRecord } +export { DevframeTracingChannelInfo } +export { DevframeTracingChannelInput } +export { DevframeTracingChannelSource } +export { DevframeTracingHost } +export { DevframeTracingOptions } export { DevframeViewHost } export { DevframeWsOptions } export { DevframeWsPeer } @@ -91,6 +99,7 @@ export { ScopedClientFunctions } export { ScopedRpcFn } export { ScopedServerFunctions } export { ScopedSharedStates } +export { SerializedValue } export { SettingsForNamespace } export { StaticAssetsSource } // #endregion \ No newline at end of file From 9ab7b007a4c1289c77bb88a1b0e51858533133f4 Mon Sep 17 00:00:00 2001 From: "Anthony Fu (via agent)" Date: Thu, 19 Nov 2026 01:40:20 +0000 Subject: [PATCH 2/4] 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. --- docs/content/1.guide/24.tracing-channels.md | 51 ++- docs/content/6.errors/DF0081.md | 4 +- docs/content/8.references/4.node-api.md | 1 + .../src/node/__tests__/host-tracing.test.ts | 60 ++++ packages/devframe/src/node/host-tracing.ts | 304 +++++++----------- packages/devframe/src/node/index.ts | 1 + .../devframe/src/node/tracing-recorder.ts | 258 +++++++++++++++ packages/devframe/src/types/tracing.ts | 63 +++- .../tsnapi/devframe/index.snapshot.d.ts | 26 ++ .../tsnapi/devframe/node.snapshot.d.ts | 1 + .../tsnapi/devframe/node.snapshot.js | 1 + .../tsnapi/devframe/types.snapshot.d.ts | 3 + 12 files changed, 585 insertions(+), 188 deletions(-) create mode 100644 packages/devframe/src/node/tracing-recorder.ts diff --git a/docs/content/1.guide/24.tracing-channels.md b/docs/content/1.guide/24.tracing-channels.md index 4a53244e2..46ce9dcba 100644 --- a/docs/content/1.guide/24.tracing-channels.md +++ b/docs/content/1.guide/24.tracing-channels.md @@ -87,6 +87,55 @@ interface DevframeTraceRecord { 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`: @@ -104,4 +153,4 @@ for await (const record of rpc.streaming.subscribe('devframe:tracing', streamId) ## Runtimes -Node.js and Bun provide `tracingChannel`. On a runtime without it, every `ctx.tracing` method is a no-op, `register()` returns a stand-in whose `traceSync` / `tracePromise` run the function directly, and the first `record()` reports [`DF0081`](/errors/DF0081) once. +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 [`DF0081`](/errors/DF0081) once. diff --git a/docs/content/6.errors/DF0081.md b/docs/content/6.errors/DF0081.md index da84425fe..4b16c41da 100644 --- a/docs/content/6.errors/DF0081.md +++ b/docs/content/6.errors/DF0081.md @@ -9,7 +9,7 @@ description: 'The runtime does not provide `node:diagnostics_channel`''s `tracin ## Cause -`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 is a no-op there. The warning fires once per process, the first time something calls `record()`. +`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 is a no-op there. The warning fires once per recorder, the first time something calls `record()` on it. ## Example @@ -24,4 +24,4 @@ Run the dev server under Node.js 22+ or Bun to record Tracing Channels. No code ## Source -- [`packages/devframe/src/node/host-tracing.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-tracing.ts): `DevframeTracingHostImpl.record()` reports this once when the module loaded at construction has no `tracingChannel` function. +- [`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. diff --git a/docs/content/8.references/4.node-api.md b/docs/content/8.references/4.node-api.md index 8283d294f..edd6f7455 100644 --- a/docs/content/8.references/4.node-api.md +++ b/docs/content/8.references/4.node-api.md @@ -144,6 +144,7 @@ The methods on `ctx.tracing`: [Tracing Channels](/guide/tracing-channels). | `records` | `(name) => DevframeTraceRecord[]` | Buffered records, oldest first, at most 500 per channel. | | `clear` | `(name) => void` | Drop the buffer and, while recording, start a fresh stream. | | `onRecord` | `(name, fn) => unsubscribe` | Run `fn` with the whole record on every lifecycle update. | +| `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). | ## Service tiers diff --git a/packages/devframe/src/node/__tests__/host-tracing.test.ts b/packages/devframe/src/node/__tests__/host-tracing.test.ts index 3d8b93e7f..c961e59da 100644 --- a/packages/devframe/src/node/__tests__/host-tracing.test.ts +++ b/packages/devframe/src/node/__tests__/host-tracing.test.ts @@ -15,6 +15,7 @@ import { createHostContext } from '../context' import { RpcFunctionsHostImpl } from '../host-functions' import { DevframeTracingHostImpl, TRACING_RECORD_BUFFER } from '../host-tracing' import { createContextRpcServer } from '../rpc-core' +import { createTracingRecorder } from '../tracing-recorder' vi.stubGlobal('WebSocket', WebSocket) @@ -194,6 +195,65 @@ describe('devframeTracingHost', () => { } }) + it('shows an attached recorder without recording through ctx', async () => { + const ctx = await createCtx() + const name = uniqueName() + const tool = createTracingRecorder() + const channel = tool.register(name, { description: 'tool query' }) + tool.record(name) + channel.traceSync(() => 1, { before: true }) + + const detach = ctx.tracing.attach(tool) + const seen: DevframeTraceRecord[] = [] + ctx.tracing.onRecord(name, record => seen.push(record)) + let state = await channelsState(ctx) + expect(state[name]).toMatchObject({ source: 'registered', description: 'tool query', recording: true, count: 1 }) + expect(state[name]!.streamId).toBeTypeOf('string') + expect(ctx.tracing.records(name)).toHaveLength(1) + + // The tool's own subscription is the only one; ctx does not subscribe. + channel.traceSync(() => 2, { after: true }) + expect(seen).toHaveLength(2) + expect(ctx.tracing.records(name)).toHaveLength(2) + + // Wire actions reach the owner. + await ctx.rpc.invokeLocal('devframe:tracing:stop', name) + expect(channel.hasSubscribers).toBe(false) + state = await channelsState(ctx) + expect(state[name]).toMatchObject({ recording: false }) + expect(state[name]!.streamId).toBeUndefined() + await ctx.rpc.invokeLocal('devframe:tracing:clear', name) + expect(tool.records(name)).toEqual([]) + + detach() + state = await channelsState(ctx) + expect(state[name]).toBeUndefined() + expect(ctx.tracing.list().some(info => info.name === name)).toBe(false) + }) + + it('keeps control in a source that has no record() / stop()', async () => { + const ctx = await createCtx() + const name = uniqueName() + let emit: (event: any) => void = () => {} + const record: DevframeTraceRecord = { id: 'r1', channel: name, startedAt: 0, status: 'ok', context: null, events: [] } + ctx.tracing.attach({ + list: () => [{ name, source: 'registered', recording: true, count: 1 }], + records: () => [record], + subscribe: (fn) => { + emit = fn + return () => {} + }, + }) + const seen: DevframeTraceRecord[] = [] + ctx.tracing.onRecord(name, r => seen.push(r)) + ctx.tracing.record(name) + ctx.tracing.stop(name) + expect((await channelsState(ctx))[name]).toMatchObject({ recording: true }) + emit({ type: 'record', record }) + expect(seen).toEqual([record]) + expect(ctx.tracing.records(name)).toEqual([record]) + }) + it('is a no-op that warns once where tracingChannel is missing', async () => { const ctx = await createCtx() const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) diff --git a/packages/devframe/src/node/host-tracing.ts b/packages/devframe/src/node/host-tracing.ts index 16a661b67..53b3b62ae 100644 --- a/packages/devframe/src/node/host-tracing.ts +++ b/packages/devframe/src/node/host-tracing.ts @@ -1,24 +1,23 @@ import type { DevframeNodeContext, - DevframeTracePhase, DevframeTraceRecord, DevframeTracingChannelInfo, - DevframeTracingChannelSource, DevframeTracingHost, DevframeTracingOptions, + DevframeTracingSource, + DevframeTracingSourceEvent, RpcStreamingChannel, } from 'devframe/types' import type { SharedState } from 'devframe/utils/shared-state' import type { StreamSink } from 'devframe/utils/streaming-channel' -import type { TracingChannel, TracingChannelSubscribers } from 'node:diagnostics_channel' +import type { TracingChannel } from 'node:diagnostics_channel' +import type { TracingModule } from './tracing-recorder' import * as diagnosticsChannel from 'node:diagnostics_channel' -import { nanoid } from 'devframe/utils/nanoid' import { DEVFRAME_EVENTS } from '../events' -import { diagnostics } from './diagnostics' -import { detectServerRuntime } from './runtime' -import { serializeTraceValue } from './tracing-serialize' +import { TRACING_RECORD_BUFFER, TracingRecorder } from './tracing-recorder' + +export { TRACING_RECORD_BUFFER } -export const TRACING_RECORD_BUFFER = 500 const COUNT_FLUSH_MS = 100 /** Tracing Channels Node.js itself publishes. */ @@ -27,39 +26,29 @@ const BUILTIN_CHANNELS: Record = { 'net.server.listen': 'net.Server listen() calls', } -/** Later sources win when the same name arrives twice. */ -const SOURCE_RANK: Record = { - adhoc: 0, - builtin: 1, - config: 2, - registered: 3, -} - -type TracingModule = Pick & Partial> - -interface ChannelEntry { - info: DevframeTracingChannelInfo - channel: TracingChannel - records: DevframeTraceRecord[] - byContext: WeakMap - subscribers?: Partial> - sink?: StreamSink - listeners: Set<(record: DevframeTraceRecord) => void> -} - +/** + * `ctx.tracing`: a local {@link TracingRecorder} plus any attached sources, + * relayed over one shared state and one streaming channel. Devframe only + * records the local recorder's channels; attached sources record themselves. + */ export class DevframeTracingHostImpl implements DevframeTracingHost { readonly supported: boolean - private readonly entries = new Map() + private readonly local: TracingRecorder + private readonly sources: DevframeTracingSource[] = [] + /** Channel name → the source that owns it. Attached sources win over the local one. */ + private owners = new Map() + private readonly sinks = new Map>() + private readonly listeners = new Map void>>() private readonly stream: RpcStreamingChannel private readonly state: Promise>> private countTimer: ReturnType | undefined - private warnedUnsupported = false constructor( private readonly context: DevframeNodeContext, - private readonly module: TracingModule = diagnosticsChannel, + module: TracingModule = diagnosticsChannel, ) { - this.supported = typeof module.tracingChannel === 'function' + this.local = new TracingRecorder(module) + this.supported = this.local.supported this.stream = context.rpc.streaming.create(DEVFRAME_EVENTS.stream.tracing, { replayWindow: TRACING_RECORD_BUFFER, closedStreamRetention: 0, @@ -69,163 +58,134 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { { initialValue: {} }, ) for (const [name, description] of Object.entries(BUILTIN_CHANNELS)) - this.add(name, 'builtin', description) + this.local.add(name, 'builtin', description) + this.local.subscribe(event => this.onSourceEvent(this.local, event)) + this.refresh() this.registerRpc() } _applyOptions(options: DevframeTracingOptions | undefined): void { - for (const entry of options?.channels ?? []) { - const { name, description } = typeof entry === 'string' ? { name: entry, description: undefined } : entry - this.add(name, 'config', description) - } + this.local.applyOptions(options) } register(channel: string | TracingChannel, meta?: { description?: string }): TracingChannel { - const name = typeof channel === 'string' ? channel : baseName(channel) - return this.add(name, 'registered', meta?.description, typeof channel === 'string' ? undefined : channel).channel + return this.local.register(channel, meta) } list(): DevframeTracingChannelInfo[] { - return Array.from(this.entries.values(), entry => ({ ...entry.info })) + return Array.from(this.collect().infos.values(), info => ({ ...info, streamId: this.sinks.get(info.name)?.id })) } record(name: string): void { - if (!this.supported) { - if (!this.warnedUnsupported) { - this.warnedUnsupported = true - diagnostics.DF0081({ runtime: detectServerRuntime() }) - } - return - } - const entry = this.add(name, 'adhoc') - if (entry.subscribers) - return - entry.sink = this.stream.start() - entry.info.recording = true - entry.info.streamId = entry.sink.id - entry.subscribers = { - start: message => this.onPhase(entry, 'start', message), - end: message => this.onPhase(entry, 'end', message), - asyncStart: message => this.onPhase(entry, 'asyncStart', message), - asyncEnd: message => this.onPhase(entry, 'asyncEnd', message), - error: message => this.onPhase(entry, 'error', message), - } - entry.channel.subscribe(entry.subscribers) - void this.publish() + const source = this.owners.get(name) + if (source && source !== this.local) + source.record?.(name) + else + this.local.record(name) } stop(name: string): void { - const entry = this.entries.get(name) - if (!entry?.subscribers) - return - entry.channel.unsubscribe(entry.subscribers) - entry.subscribers = undefined - entry.sink?.close() - entry.sink = undefined - entry.info.recording = false - entry.info.streamId = undefined - void this.publish() + const source = this.owners.get(name) + if (source && source !== this.local) + source.stop?.(name) + else + this.local.stop(name) } records(name: string): DevframeTraceRecord[] { - return (this.entries.get(name)?.records ?? []).map(record => ({ ...record })) + return (this.owners.get(name) ?? this.local).records(name) } clear(name: string): void { - const entry = this.entries.get(name) - if (!entry) - return - entry.records = [] - entry.byContext = new WeakMap() - entry.info.count = 0 - if (entry.sink) { - // A fresh stream drops the replay buffer, so a client that reconnects - // after a clear does not see the cleared records again. - entry.sink.close() - entry.sink = this.stream.start() - entry.info.streamId = entry.sink.id - } - void this.publish() + const source = this.owners.get(name) + if (source && source !== this.local) + source.clear?.(name) + else + this.local.clear(name) } onRecord(name: string, fn: (record: DevframeTraceRecord) => void): () => void { - const entry = this.add(name, 'adhoc') - entry.listeners.add(fn) + if (!this.owners.has(name)) + this.local.add(name, 'adhoc') + let set = this.listeners.get(name) + if (!set) + this.listeners.set(name, set = new Set()) + set.add(fn) return () => { - entry.listeners.delete(fn) + set.delete(fn) } } - private add(name: string, source: DevframeTracingChannelSource, description?: string, channel?: TracingChannel): ChannelEntry { - let entry = this.entries.get(name) - if (!entry) { - entry = { - info: { name, source, recording: false, count: 0 }, - channel: channel ?? this.createChannel(name), - records: [], - byContext: new WeakMap(), - listeners: new Set(), - } - this.entries.set(name, entry) + attach(source: DevframeTracingSource): () => void { + if (source === this.local || this.sources.includes(source)) + return () => {} + this.sources.push(source) + const unsubscribe = source.subscribe(event => this.onSourceEvent(source, event)) + this.refresh() + return () => { + const index = this.sources.indexOf(source) + if (index === -1) + return + this.sources.splice(index, 1) + unsubscribe() + this.refresh() + } + } + + private onSourceEvent(source: DevframeTracingSource, event: DevframeTracingSourceEvent): void { + if (event.type === 'channels') { + this.refresh() + return } - else if (SOURCE_RANK[source] > SOURCE_RANK[entry.info.source]) { - entry.info.source = source + if (this.owners.get(event.type === 'record' ? event.record.channel : event.channel) !== source) + return + if (event.type === 'clear') { + // A fresh stream drops the replay buffer, so a client that reconnects + // after a clear does not see the cleared records again. + const sink = this.sinks.get(event.channel) + if (sink) { + sink.close() + this.sinks.set(event.channel, this.stream.start()) + } + this.refresh() + return } - if (description && !entry.info.description) - entry.info.description = description - void this.publish() - return entry + this.sinks.get(event.record.channel)?.write(event.record) + for (const fn of this.listeners.get(event.record.channel) ?? []) + fn(event.record) + this.scheduleCountFlush() } - private createChannel(name: string): TracingChannel { - if (this.module.tracingChannel) - return this.module.tracingChannel(name) - return noopTracingChannel(this.module, name) + /** Every channel with its owner. Attached sources override the local one, later ones win. */ + private collect(): { owners: Map, infos: Map } { + const owners = new Map() + const infos = new Map() + for (const source of [this.local, ...this.sources]) { + for (const info of source.list()) { + owners.set(info.name, source) + infos.set(info.name, info) + } + } + return { owners, infos } } - private onPhase(entry: ChannelEntry, phase: DevframeTracePhase, message: unknown): void { - const at = Date.now() - const keyed = typeof message === 'object' && message !== null - const record = (keyed ? entry.byContext.get(message) : undefined) ?? this.openRecord(entry, at, keyed ? message : undefined) + /** Rebuild ownership, open or close one stream per recording channel, and publish. */ + private refresh(): void { + const { owners, infos } = this.collect() + this.owners = owners - record.events.push({ phase, at }) - record.duration = at - record.startedAt - const { result, error, ...rest } = keyed ? (message as { result?: unknown, error?: unknown }) : {} - record.context = serializeTraceValue(keyed ? rest : message) - if (result !== undefined) - record.result = serializeTraceValue(result) - if (phase === 'error') { - record.status = 'error' - const serialized = serializeTraceValue(error) - record.error = isErrorShape(serialized) ? serialized : { name: 'Error', message: String(error) } + for (const [name, sink] of this.sinks) { + if (!infos.get(name)?.recording) { + sink.close() + this.sinks.delete(name) + } } - else if ((phase === 'end' || phase === 'asyncEnd') && record.status === 'pending') { - record.status = 'ok' + for (const info of infos.values()) { + if (info.recording && !this.sinks.has(info.name)) + this.sinks.set(info.name, this.stream.start()) } - const snapshot = { ...record, events: [...record.events] } - entry.sink?.write(snapshot) - for (const fn of entry.listeners) - fn(snapshot) - } - - private openRecord(entry: ChannelEntry, at: number, context: object | undefined): DevframeTraceRecord { - const record: DevframeTraceRecord = { - id: nanoid(), - channel: entry.info.name, - startedAt: at, - status: 'pending', - context: null, - events: [], - } - if (context) - entry.byContext.set(context, record) - entry.records.push(record) - if (entry.records.length > TRACING_RECORD_BUFFER) - entry.records.shift() - entry.info.count = entry.records.length - this.scheduleCountFlush() - return record + void this.publish(infos) } /** Counts change on every record; batch them so the state is not spammed. */ @@ -234,15 +194,21 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { return this.countTimer = setTimeout(() => { this.countTimer = undefined - void this.publish() + this.refresh() }, COUNT_FLUSH_MS) } - private async publish(): Promise { + private async publish(infos: Map): Promise { const state = await this.state + const next: Record = {} + for (const [name, info] of infos) + next[name] = { ...info, streamId: this.sinks.get(name)?.id } state.mutate((value) => { - for (const entry of this.entries.values()) - value[entry.info.name] = { ...entry.info } + for (const name of Object.keys(value)) { + if (!(name in next)) + delete value[name] + } + Object.assign(value, next) }) } @@ -265,33 +231,3 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { }) } } - -/** `tracing::start` → ``. */ -function baseName(channel: TracingChannel): string { - const name = String(channel.start.name) - return name.replace(/^tracing:/, '').replace(/:start$/, '') -} - -function isErrorShape(value: unknown): value is { name: string, message: string, stack?: string } { - return typeof value === 'object' && value !== null && typeof (value as { name?: unknown }).name === 'string' && typeof (value as { message?: unknown }).message === 'string' -} - -/** - * Stand-in for runtimes without `tracingChannel`: the trace helpers call - * the function directly and nothing is published. - */ -function noopTracingChannel(module: TracingModule, name: string): TracingChannel { - return { - start: module.channel(`tracing:${name}:start`), - end: module.channel(`tracing:${name}:end`), - asyncStart: module.channel(`tracing:${name}:asyncStart`), - asyncEnd: module.channel(`tracing:${name}:asyncEnd`), - error: module.channel(`tracing:${name}:error`), - hasSubscribers: false, - subscribe() {}, - unsubscribe() {}, - traceSync: (fn, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), - tracePromise: (fn, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), - traceCallback: (fn, _position, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), - } -} diff --git a/packages/devframe/src/node/index.ts b/packages/devframe/src/node/index.ts index c5fb151a4..9babb924f 100644 --- a/packages/devframe/src/node/index.ts +++ b/packages/devframe/src/node/index.ts @@ -16,3 +16,4 @@ export * from './context' // pulling in the implementation's `@internal` members. export type { RpcFunctionsHost } from './host-functions' export * from './storage' +export { createTracingRecorder } from './tracing-recorder' diff --git a/packages/devframe/src/node/tracing-recorder.ts b/packages/devframe/src/node/tracing-recorder.ts new file mode 100644 index 000000000..6a50229e3 --- /dev/null +++ b/packages/devframe/src/node/tracing-recorder.ts @@ -0,0 +1,258 @@ +import type { + DevframeTracePhase, + DevframeTraceRecord, + DevframeTracingChannelInfo, + DevframeTracingChannelSource, + DevframeTracingOptions, + DevframeTracingRecorder, + DevframeTracingSourceEvent, +} from 'devframe/types' +import type { TracingChannel, TracingChannelSubscribers } from 'node:diagnostics_channel' +import * as diagnosticsChannel from 'node:diagnostics_channel' +import { nanoid } from 'devframe/utils/nanoid' +import { diagnostics } from './diagnostics' +import { detectServerRuntime } from './runtime' +import { serializeTraceValue } from './tracing-serialize' + +export const TRACING_RECORD_BUFFER = 500 + +/** Later sources win when the same name arrives twice. */ +const SOURCE_RANK: Record = { + adhoc: 0, + builtin: 1, + config: 2, + registered: 3, +} + +export type TracingModule = Pick & Partial> + +interface ChannelEntry { + info: DevframeTracingChannelInfo + channel: TracingChannel + records: DevframeTraceRecord[] + byContext: WeakMap + subscribers?: Partial> + listeners: Set<(record: DevframeTraceRecord) => void> +} + +/** + * Subscribes to Tracing Channels and folds their lifecycle events into + * records. Has no wire: `ctx.tracing` uses one internally, and a tool can + * keep its own and attach it with `ctx.tracing.attach()`. + */ +export class TracingRecorder implements DevframeTracingRecorder { + readonly supported: boolean + private readonly entries = new Map() + private readonly listeners = new Set<(event: DevframeTracingSourceEvent) => void>() + private warnedUnsupported = false + + constructor(private readonly module: TracingModule = diagnosticsChannel) { + this.supported = typeof module.tracingChannel === 'function' + } + + register(channel: string | TracingChannel, meta?: { description?: string }): TracingChannel { + const name = typeof channel === 'string' ? channel : baseName(channel) + return this.add(name, 'registered', meta?.description, typeof channel === 'string' ? undefined : channel).channel + } + + applyOptions(options: DevframeTracingOptions | undefined): void { + for (const entry of options?.channels ?? []) { + const { name, description } = typeof entry === 'string' ? { name: entry, description: undefined } : entry + this.add(name, 'config', description) + } + } + + has(name: string): boolean { + return this.entries.has(name) + } + + list(): DevframeTracingChannelInfo[] { + return Array.from(this.entries.values(), entry => ({ ...entry.info })) + } + + record(name: string): void { + if (!this.supported) { + if (!this.warnedUnsupported) { + this.warnedUnsupported = true + diagnostics.DF0081({ runtime: detectServerRuntime() }) + } + return + } + const entry = this.add(name, 'adhoc') + if (entry.subscribers) + return + entry.info.recording = true + entry.subscribers = { + start: message => this.onPhase(entry, 'start', message), + end: message => this.onPhase(entry, 'end', message), + asyncStart: message => this.onPhase(entry, 'asyncStart', message), + asyncEnd: message => this.onPhase(entry, 'asyncEnd', message), + error: message => this.onPhase(entry, 'error', message), + } + entry.channel.subscribe(entry.subscribers) + this.emit({ type: 'channels' }) + } + + stop(name: string): void { + const entry = this.entries.get(name) + if (!entry?.subscribers) + return + entry.channel.unsubscribe(entry.subscribers) + entry.subscribers = undefined + entry.info.recording = false + this.emit({ type: 'channels' }) + } + + records(name: string): DevframeTraceRecord[] { + return (this.entries.get(name)?.records ?? []).map(record => ({ ...record })) + } + + clear(name: string): void { + const entry = this.entries.get(name) + if (!entry) + return + entry.records = [] + entry.byContext = new WeakMap() + entry.info.count = 0 + this.emit({ type: 'clear', channel: name }) + this.emit({ type: 'channels' }) + } + + onRecord(name: string, fn: (record: DevframeTraceRecord) => void): () => void { + const entry = this.add(name, 'adhoc') + entry.listeners.add(fn) + return () => { + entry.listeners.delete(fn) + } + } + + subscribe(listener: (event: DevframeTracingSourceEvent) => void): () => void { + this.listeners.add(listener) + return () => { + this.listeners.delete(listener) + } + } + + add(name: string, source: DevframeTracingChannelSource, description?: string, channel?: TracingChannel): ChannelEntry { + let entry = this.entries.get(name) + let changed = false + if (!entry) { + entry = { + info: { name, source, recording: false, count: 0 }, + channel: channel ?? this.createChannel(name), + records: [], + byContext: new WeakMap(), + listeners: new Set(), + } + this.entries.set(name, entry) + changed = true + } + else if (SOURCE_RANK[source] > SOURCE_RANK[entry.info.source]) { + entry.info.source = source + changed = true + } + if (description && !entry.info.description) { + entry.info.description = description + changed = true + } + if (changed) + this.emit({ type: 'channels' }) + return entry + } + + private emit(event: DevframeTracingSourceEvent): void { + for (const listener of this.listeners) + listener(event) + } + + private createChannel(name: string): TracingChannel { + if (this.module.tracingChannel) + return this.module.tracingChannel(name) + return noopTracingChannel(this.module, name) + } + + private onPhase(entry: ChannelEntry, phase: DevframeTracePhase, message: unknown): void { + const at = Date.now() + const keyed = typeof message === 'object' && message !== null + const record = (keyed ? entry.byContext.get(message) : undefined) ?? this.openRecord(entry, at, keyed ? message : undefined) + + record.events.push({ phase, at }) + record.duration = at - record.startedAt + const { result, error, ...rest } = keyed ? (message as { result?: unknown, error?: unknown }) : {} + record.context = serializeTraceValue(keyed ? rest : message) + if (result !== undefined) + record.result = serializeTraceValue(result) + if (phase === 'error') { + record.status = 'error' + const serialized = serializeTraceValue(error) + record.error = isErrorShape(serialized) ? serialized : { name: 'Error', message: String(error) } + } + else if ((phase === 'end' || phase === 'asyncEnd') && record.status === 'pending') { + record.status = 'ok' + } + + const snapshot = { ...record, events: [...record.events] } + for (const fn of entry.listeners) + fn(snapshot) + this.emit({ type: 'record', record: snapshot }) + } + + private openRecord(entry: ChannelEntry, at: number, context: object | undefined): DevframeTraceRecord { + const record: DevframeTraceRecord = { + id: nanoid(), + channel: entry.info.name, + startedAt: at, + status: 'pending', + context: null, + events: [], + } + if (context) + entry.byContext.set(context, record) + entry.records.push(record) + if (entry.records.length > TRACING_RECORD_BUFFER) + entry.records.shift() + entry.info.count = entry.records.length + return record + } +} + +/** + * Create a standalone Tracing Channel recorder. A tool keeps one as its own + * tracing instance, records through it, and optionally shows it in devframe + * with `ctx.tracing.attach(recorder)`. + */ +export function createTracingRecorder(options?: DevframeTracingOptions): DevframeTracingRecorder { + const recorder = new TracingRecorder() + recorder.applyOptions(options) + return recorder +} + +/** `tracing::start` → ``. */ +function baseName(channel: TracingChannel): string { + const name = String(channel.start.name) + return name.replace(/^tracing:/, '').replace(/:start$/, '') +} + +function isErrorShape(value: unknown): value is { name: string, message: string, stack?: string } { + return typeof value === 'object' && value !== null && typeof (value as { name?: unknown }).name === 'string' && typeof (value as { message?: unknown }).message === 'string' +} + +/** + * Stand-in for runtimes without `tracingChannel`: the trace helpers call + * the function directly and nothing is published. + */ +function noopTracingChannel(module: TracingModule, name: string): TracingChannel { + return { + start: module.channel(`tracing:${name}:start`), + end: module.channel(`tracing:${name}:end`), + asyncStart: module.channel(`tracing:${name}:asyncStart`), + asyncEnd: module.channel(`tracing:${name}:asyncEnd`), + error: module.channel(`tracing:${name}:error`), + hasSubscribers: false, + subscribe() {}, + unsubscribe() {}, + traceSync: (fn, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), + tracePromise: (fn, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), + traceCallback: (fn, _position, _context, thisArg, ...args) => Reflect.apply(fn, thisArg, args), + } +} diff --git a/packages/devframe/src/types/tracing.ts b/packages/devframe/src/types/tracing.ts index 931048d58..8ed94f86c 100644 --- a/packages/devframe/src/types/tracing.ts +++ b/packages/devframe/src/types/tracing.ts @@ -81,6 +81,56 @@ export interface DevframeTracingOptions { channels?: Array } +/** What a {@link DevframeTracingSource} tells its listeners. */ +export type DevframeTracingSourceEvent + = | { type: 'record', record: DevframeTraceRecord } + | { type: 'channels' } + | { type: 'clear', channel: string } + +/** + * Anything that owns Tracing Channels and their records, outside of + * `ctx.tracing`. A tool that keeps its own tracing instance attaches it with + * `ctx.tracing.attach(source)`: devframe then shows the source's channels and + * relays its records, but never subscribes to them itself. The source records. + * + * `createTracingRecorder()` from `devframe/node` returns one. Any object with + * this shape works too, so a tool does not need devframe at runtime. + */ +export interface DevframeTracingSource { + /** Channels this source owns. `streamId` is ignored; devframe sets it. */ + list: () => DevframeTracingChannelInfo[] + /** Buffered records of one channel, oldest first. */ + records: (name: string) => DevframeTraceRecord[] + /** + * Push updates. Emit `record` on every record change, `channels` when the + * channel list or a channel's `recording` / `description` changes, and + * `clear` when a channel's buffer is dropped. + */ + subscribe: (listener: (event: DevframeTracingSourceEvent) => void) => () => void + /** Called when a client asks devframe to record. Omit to keep control in the tool. */ + record?: (name: string) => void + /** Called when a client asks devframe to stop. */ + stop?: (name: string) => void + /** Called when a client asks devframe to clear. */ + clear?: (name: string) => void +} + +/** + * A standalone Tracing Channel recorder, made with `createTracingRecorder()`. + * It has the same recording methods as `ctx.tracing`, without the wire, and + * is a {@link DevframeTracingSource} that `ctx.tracing.attach()` accepts. + */ +export interface DevframeTracingRecorder extends Required { + /** `false` where the runtime has no `tracingChannel`; every method is a no-op. */ + readonly supported: boolean + /** Declare a Tracing Channel and get Node's `TracingChannel` back. */ + register: (channel: string | TracingChannel, meta?: { description?: string }) => TracingChannel + /** Subscribe to the channel and start folding events into records. */ + record: (name: string) => void + /** Called with the whole record on every lifecycle update. */ + onRecord: (name: string, fn: (record: DevframeTraceRecord) => void) => () => void +} + /** * Node-side Tracing Channel host, exposed as `ctx.tracing`. Wraps * `node:diagnostics_channel`'s `TracingChannel`: keeps the list of known @@ -98,7 +148,11 @@ export interface DevframeTracingHost { */ register: (channel: string | TracingChannel, meta?: { description?: string }) => TracingChannel list: () => DevframeTracingChannelInfo[] - /** Subscribe to the channel and start folding events into records. */ + /** + * Subscribe to the channel and start folding events into records. For a + * channel of an attached source, this calls the source's `record()`, or + * does nothing when the source has none. + */ record: (name: string) => void /** Unsubscribe. Records stay in the buffer. */ stop: (name: string) => void @@ -107,6 +161,13 @@ export interface DevframeTracingHost { clear: (name: string) => void /** Called with the whole record on every lifecycle update. */ onRecord: (name: string, fn: (record: DevframeTraceRecord) => void) => () => void + /** + * Show the channels and records of a tool's own tracing instance. Devframe + * relays them over the wire but does not record them; the source does. + * When two sources own the same name, the one attached last wins. + * Returns a function that detaches the source. + */ + attach: (source: DevframeTracingSource) => () => void /** * Adapters call this with a definition's or hub's `tracing` field before * `setup()` runs. Wired by the adapters automatically. diff --git a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts index 552144922..abd998f2d 100644 --- a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts @@ -434,11 +434,28 @@ export interface DevframeTracingHost { records: (_: string) => DevframeTraceRecord[]; clear: (_: string) => void; onRecord: (_: string, _: (_: DevframeTraceRecord) => void) => () => void; + attach: (_: DevframeTracingSource) => () => void; _applyOptions: (_: DevframeTracingOptions | undefined) => void; } export interface DevframeTracingOptions { channels?: Array; } +export interface DevframeTracingRecorder extends Required { + readonly supported: boolean; + register: (_: string | TracingChannel, _?: { + description?: string; + }) => TracingChannel; + record: (_: string) => void; + onRecord: (_: string, _: (_: DevframeTraceRecord) => void) => () => void; +} +export interface DevframeTracingSource { + list: () => DevframeTracingChannelInfo[]; + records: (_: string) => DevframeTraceRecord[]; + subscribe: (_: (_: DevframeTracingSourceEvent) => void) => () => void; + record?: (_: string) => void; + stop?: (_: string) => void; + clear?: (_: string) => void; +} export interface DevframeViewHost { buildStaticDirs: { baseUrl: string; @@ -604,6 +621,15 @@ export type DevframeSnapshotRpcInputs = readonly (readonly unknown[])[] | ((_: D export type DevframeStorageScope = 'workspace' | 'project' | 'global'; export type DevframeTracePhase = 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error'; export type DevframeTracingChannelSource = 'builtin' | 'registered' | 'config' | 'adhoc'; +export type DevframeTracingSourceEvent = { + type: 'record'; + record: DevframeTraceRecord; +} | { + type: 'channels'; +} | { + type: 'clear'; + channel: string; +}; export type McpAuthorization = string | ((_: Request) => boolean | Promise) | false; export type McpSetting = boolean | 'auto' | McpRouteOptions; export type RemoteAssetsProvider = 'jsdelivr' | 'unpkg' | RemoteAssetsProviderCustom; diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts index f2acbe767..2c346bbfc 100644 --- a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts @@ -21,6 +21,7 @@ export interface CreateStorageOptions { // #region Functions export declare function createHostContext(_: CreateHostContextOptions): Promise; export declare function createStorage(_: CreateStorageOptions): SharedState; +export declare function createTracingRecorder(_?: DevframeTracingOptions): DevframeTracingRecorder; // #endregion // #region Other diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.js b/tests/__snapshots__/tsnapi/devframe/node.snapshot.js index faf693f71..cb071f434 100644 --- a/tests/__snapshots__/tsnapi/devframe/node.snapshot.js +++ b/tests/__snapshots__/tsnapi/devframe/node.snapshot.js @@ -4,4 +4,5 @@ // #region Other export { createHostContext } export { createStorage } +export { createTracingRecorder } // #endregion \ No newline at end of file diff --git a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts index 03a24c285..5f258d77f 100644 --- a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts @@ -69,6 +69,9 @@ export { DevframeTracingChannelInput } export { DevframeTracingChannelSource } export { DevframeTracingHost } export { DevframeTracingOptions } +export { DevframeTracingRecorder } +export { DevframeTracingSource } +export { DevframeTracingSourceEvent } export { DevframeViewHost } export { DevframeWsOptions } export { DevframeWsPeer } From 7e75d8c7d2a5524ae0768a48ae5f770a53dbc304 Mon Sep 17 00:00:00 2001 From: Anthony Fu Date: Thu, 19 Nov 2026 11:03:15 +0900 Subject: [PATCH 3/4] Delete .pi/skills/npm-antfu-design-antfu-design --- .pi/skills/npm-antfu-design-antfu-design | 1 - 1 file changed, 1 deletion(-) delete mode 120000 .pi/skills/npm-antfu-design-antfu-design diff --git a/.pi/skills/npm-antfu-design-antfu-design b/.pi/skills/npm-antfu-design-antfu-design deleted file mode 120000 index df6625d31..000000000 --- a/.pi/skills/npm-antfu-design-antfu-design +++ /dev/null @@ -1 +0,0 @@ -../../node_modules/@antfu/design/skills/antfu-design \ No newline at end of file From 96582a1fbab89644404d3503a840446e38173e55 Mon Sep 17 00:00:00 2001 From: "Anthony Fu (via agent)" Date: Thu, 19 Nov 2026 02:23:24 +0000 Subject: [PATCH 4/4] refactor(devframe): simplify tracing host and recorder --- .../src/node/__tests__/host-tracing.test.ts | 5 ++- packages/devframe/src/node/host-tracing.ts | 35 ++++++++----------- .../devframe/src/node/tracing-recorder.ts | 24 ++++--------- packages/devframe/src/types/tracing.ts | 2 -- .../tsnapi/devframe/index.snapshot.d.ts | 1 - .../tsnapi/devframe/node.snapshot.d.ts | 2 +- .../tsnapi/devframe/node.snapshot.js | 2 +- .../tsnapi/devframe/types.snapshot.d.ts | 1 - 8 files changed, 25 insertions(+), 47 deletions(-) diff --git a/packages/devframe/src/node/__tests__/host-tracing.test.ts b/packages/devframe/src/node/__tests__/host-tracing.test.ts index e0d253823..ad3fd020e 100644 --- a/packages/devframe/src/node/__tests__/host-tracing.test.ts +++ b/packages/devframe/src/node/__tests__/host-tracing.test.ts @@ -13,9 +13,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { WebSocket } from 'ws' import { createHostContext } from '../context' import { RpcFunctionsHostImpl } from '../host-functions' -import { DevframeTracingHostImpl, TRACING_RECORD_BUFFER } from '../host-tracing' +import { DevframeTracingHostImpl } from '../host-tracing' import { createContextRpcServer } from '../rpc-core' -import { createTracingRecorder } from '../tracing-recorder' +import { createTracingRecorder, TRACING_RECORD_BUFFER } from '../tracing-recorder' vi.stubGlobal('WebSocket', WebSocket) @@ -310,7 +310,6 @@ describe('devframeTracingHost', () => { }, { channel: diagnosticsChannel.channel }, ) - expect(host.supported).toBe(false) const name = uniqueName() const channel = host.register(name) expect(channel.traceSync(() => 'ran')).toBe('ran') diff --git a/packages/devframe/src/node/host-tracing.ts b/packages/devframe/src/node/host-tracing.ts index 4f57bbff1..a9c1f3da1 100644 --- a/packages/devframe/src/node/host-tracing.ts +++ b/packages/devframe/src/node/host-tracing.ts @@ -16,8 +16,6 @@ import * as diagnosticsChannel from 'node:diagnostics_channel' import { DEVFRAME_EVENTS } from '../events' import { TRACING_RECORD_BUFFER, TracingRecorder } from './tracing-recorder' -export { TRACING_RECORD_BUFFER } - const COUNT_FLUSH_MS = 100 /** Tracing Channels Node.js itself publishes. */ @@ -32,7 +30,6 @@ const BUILTIN_CHANNELS: Record = { * records the local recorder's channels; attached sources record themselves. */ export class DevframeTracingHostImpl implements DevframeTracingHost { - readonly supported: boolean private readonly local: TracingRecorder private readonly sources: DevframeTracingSource[] = [] /** Channel name → the source that owns it. Attached sources win over the local one. */ @@ -48,7 +45,6 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { module: TracingModule = diagnosticsChannel, ) { this.local = new TracingRecorder(module) - this.supported = this.local.supported this.stream = context.rpc.streaming.create(DEVFRAME_EVENTS.stream.tracing, { replayWindow: TRACING_RECORD_BUFFER, closedStreamRetention: 0, @@ -76,32 +72,24 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { return Array.from(this.collect().infos.values(), info => ({ ...info, streamId: this.sinks.get(info.name)?.id })) } + /** + * An attached source without `record` / `stop` / `clear` keeps control: + * the call does nothing, and devframe never records its channel itself. + */ record(name: string): void { - const source = this.owners.get(name) - if (source && source !== this.local) - source.record?.(name) - else - this.local.record(name) + this.ownerOf(name).record?.(name) } stop(name: string): void { - const source = this.owners.get(name) - if (source && source !== this.local) - source.stop?.(name) - else - this.local.stop(name) + this.ownerOf(name).stop?.(name) } records(name: string): DevframeTraceRecord[] { - return (this.owners.get(name) ?? this.local).records(name) + return this.ownerOf(name).records(name) } clear(name: string): void { - const source = this.owners.get(name) - if (source && source !== this.local) - source.clear?.(name) - else - this.local.clear(name) + this.ownerOf(name).clear?.(name) } onRecord(name: string, fn: (record: DevframeTraceRecord) => void): () => void { @@ -117,7 +105,7 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { } attach(source: DevframeTracingSource): () => void { - if (source === this.local || this.sources.includes(source)) + if (this.sources.includes(source)) return () => {} this.sources.push(source) const unsubscribe = source.subscribe(event => this.onSourceEvent(source, event)) @@ -159,6 +147,11 @@ export class DevframeTracingHostImpl implements DevframeTracingHost { this.scheduleCountFlush() } + /** Unknown names fall to the local recorder, which adds them as `adhoc`. */ + private ownerOf(name: string): DevframeTracingSource { + return this.owners.get(name) ?? this.local + } + /** Every channel with its owner. Attached sources override the local one, later ones win. */ private collect(): { owners: Map, infos: Map } { const owners = new Map() diff --git a/packages/devframe/src/node/tracing-recorder.ts b/packages/devframe/src/node/tracing-recorder.ts index fa55d94db..84340a39c 100644 --- a/packages/devframe/src/node/tracing-recorder.ts +++ b/packages/devframe/src/node/tracing-recorder.ts @@ -32,7 +32,6 @@ interface ChannelEntry { records: DevframeTraceRecord[] byContext: WeakMap subscribers?: Partial> - listeners: Set<(record: DevframeTraceRecord) => void> } /** @@ -68,10 +67,6 @@ export class TracingRecorder implements DevframeTracingRecorder { } } - has(name: string): boolean { - return this.entries.has(name) - } - list(): DevframeTracingChannelInfo[] { return Array.from(this.entries.values(), entry => ({ ...entry.info })) } @@ -127,11 +122,11 @@ export class TracingRecorder implements DevframeTracingRecorder { } onRecord(name: string, fn: (record: DevframeTraceRecord) => void): () => void { - const entry = this.add(name, 'adhoc') - entry.listeners.add(fn) - return () => { - entry.listeners.delete(fn) - } + this.add(name, 'adhoc') + return this.subscribe((event) => { + if (event.type === 'record' && event.record.channel === name) + fn(event.record) + }) } subscribe(listener: (event: DevframeTracingSourceEvent) => void): () => void { @@ -155,7 +150,6 @@ export class TracingRecorder implements DevframeTracingRecorder { channel: channel ?? this.createChannel(name), records: [], byContext: new WeakMap(), - listeners: new Set(), } this.entries.set(name, entry) changed = true @@ -217,8 +211,6 @@ export class TracingRecorder implements DevframeTracingRecorder { ...record, events: [...record.events], } - for (const fn of entry.listeners) - fn(snapshot) this.emit({ type: 'record', record: snapshot }) } @@ -246,10 +238,8 @@ export class TracingRecorder implements DevframeTracingRecorder { * tracing instance, records through it, and optionally shows it in devframe * with `ctx.tracing.attach(recorder)`. */ -export function createTracingRecorder(options?: DevframeTracingOptions): DevframeTracingRecorder { - const recorder = new TracingRecorder() - recorder.applyOptions(options) - return recorder +export function createTracingRecorder(): DevframeTracingRecorder { + return new TracingRecorder() } /** `tracing::start` → ``. */ diff --git a/packages/devframe/src/types/tracing.ts b/packages/devframe/src/types/tracing.ts index 514b72242..481fcc5c8 100644 --- a/packages/devframe/src/types/tracing.ts +++ b/packages/devframe/src/types/tracing.ts @@ -125,8 +125,6 @@ export interface DevframeTracingRecorder extends Required readonly supported: boolean /** Declare a Tracing Channel and get Node's `TracingChannel` back. */ register: (channel: string | TracingChannel, meta?: { description?: string }) => TracingChannel - /** Subscribe to the channel and start folding events into records. */ - record: (name: string) => void /** Called with the whole record on every lifecycle update. */ onRecord: (name: string, fn: (record: DevframeTraceRecord) => void) => () => void } diff --git a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts index 06568da7c..466986ee2 100644 --- a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts @@ -455,7 +455,6 @@ export interface DevframeTracingRecorder extends Required register: (_: string | TracingChannel, _?: { description?: string; }) => TracingChannel; - record: (_: string) => void; onRecord: (_: string, _: (_: DevframeTraceRecord) => void) => () => void; } export interface DevframeTracingSource { diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts index 962d3d131..9b3009acd 100644 --- a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts @@ -31,5 +31,5 @@ export type RpcFunctionsHost = RpcFunctionsCollectorBase; export declare function createStorage(_: CreateStorageOptions): SharedState; -export declare function createTracingRecorder(_?: DevframeTracingOptions): DevframeTracingRecorder; +export declare function createTracingRecorder(): DevframeTracingRecorder; // #endregion \ No newline at end of file diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.js b/tests/__snapshots__/tsnapi/devframe/node.snapshot.js index d09feb563..fe0e5c098 100644 --- a/tests/__snapshots__/tsnapi/devframe/node.snapshot.js +++ b/tests/__snapshots__/tsnapi/devframe/node.snapshot.js @@ -4,5 +4,5 @@ // #region Functions export async function createHostContext(_) {} export function createStorage(_) {} -export function createTracingRecorder(_) {} +export function createTracingRecorder() {} // #endregion \ No newline at end of file diff --git a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts index 7afe6054d..6dd07e686 100644 --- a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts @@ -455,7 +455,6 @@ export interface DevframeTracingRecorder extends Required register: (_: string | TracingChannel, _?: { description?: string; }) => TracingChannel; - record: (_: string) => void; onRecord: (_: string, _: (_: DevframeTraceRecord) => void) => () => void; } export interface DevframeTracingSource {