Repository navigation
feat(devframe): add ctx.tracing for Node.js Tracing Channels - #428
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
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.
|
👁️🗨️ Review this pull request with grouped, summarized diffs at: raw result💭 analyzed by {
"headSha": "96582a1fbab89644404d3503a840446e38173e55",
"result": {
"overallSummary": "PR 1 of 3 on tracing: introduces `ctx.tracing`, a host-side wrapper over Node.js `TracingChannel` (register/list/record/stop/records/clear/onRecord/attach) that folds lifecycle events into buffered, JSON-serializable `DevframeTraceRecord`s and exposes them over a new shared state and streaming channel, so any future UI or app can inspect what a devframe traces. It wires this into every context-creation path, defines the wire contract and types, and ships docs plus tests; a companion snapshot update tracks the new public surface.",
"groups": [
{
"key": "tracing-core",
"label": "ctx.tracing core feature",
"summary": "Adds `ctx.tracing`, the host-side API for listing, recording and streaming Node.js Tracing Channel events into `DevframeTraceRecord`s, plus the serializer that turns arbitrary trace payloads into wire-safe JSON, and the wiring that plugs it into every node/hub context, adapter and the public type/RPC surface.",
"category": "core",
"filePaths": [],
"critical": true,
"children": [
{
"key": "tracing-implementation",
"label": "Tracing host & serializer",
"category": "core",
"filePaths": [
"packages/devframe/src/node/host-tracing.ts",
"packages/devframe/src/node/tracing-recorder.ts",
"packages/devframe/src/node/tracing-serialize.ts",
"packages/devframe/src/node/diagnostics.ts"
],
"critical": true,
"fileNotes": [
{
"path": "packages/devframe/src/node/host-tracing.ts",
"text": "Owns the wire (shared state + one stream per recording channel) and the ownership logic between the local recorder and any attached `DevframeTracingSource`; subtlety: a fresh stream id is issued on every record()/clear() because reusing a retained id silently replaces the record."
},
{
"path": "packages/devframe/src/node/tracing-recorder.ts",
"text": "Standalone recorder (`createTracingRecorder`) shared by ctx.tracing and tools; folds TracingChannel lifecycle events sharing a context object into one ring-buffered record, and is a safe no-op with a one-time DF0086 warning when `tracingChannel` is unavailable."
},
{
"path": "packages/devframe/src/node/tracing-serialize.ts",
"text": "Serializer that never throws: caps depth/width/string length, marks true cycles, and special-cases errors, dates, maps, sets and binary data so sockets/requests cross the wire safely."
}
]
},
{
"key": "tracing-wiring",
"label": "Context, adapter & type wiring",
"summary": "Hooks `tracing` into every context-creation path (`createHostContext`, scoped contexts, `createBuild`/`createEmbedded`/`initDevframe`, hub `initHub`/`buildHub`/`prepareDevframe`), adds `tracing.channels` to `DevframeDefinition`/hub options, and defines the public types plus the `devframe:tracing:*` RPC/shared-state contract.",
"category": "api",
"filePaths": [
"packages/devframe/src/node/context.ts",
"packages/devframe/src/node/scope.ts",
"packages/devframe/src/node/index.ts",
"packages/devframe/src/events.ts",
"packages/devframe/src/adapters/build.ts",
"packages/devframe/src/adapters/embedded.ts",
"packages/devframe/src/adapters/initiate.ts",
"packages/devframe/src/types/context.ts",
"packages/devframe/src/types/devframe.ts",
"packages/devframe/src/types/index.ts",
"packages/devframe/src/types/rpc-augments.ts",
"packages/devframe/src/types/scope.ts",
"packages/devframe/src/types/tracing.ts",
"packages/hub/src/node/build.ts",
"packages/hub/src/node/initiate.ts",
"packages/hub/src/node/install-devframe.ts"
]
}
]
},
{
"key": "tests",
"label": "Tracing tests",
"summary": "Unit tests for the new tracing host, recorder, serializer and attach() behavior, plus updates to existing hub/mcp tests that now see the new `devframe:tracing:channels` shared state.",
"category": "tests",
"filePaths": [
"packages/devframe/src/node/__tests__/host-tracing.test.ts",
"packages/devframe/src/node/__tests__/tracing-serialize.test.ts",
"packages/hub/src/node/__tests__/install-devframe.test.ts",
"packages/agentic/src/mcp/__tests__/mcp-server.test.ts"
]
},
{
"key": "docs",
"label": "Tracing documentation",
"summary": "New guide page, error reference (DF0086) and reference-doc updates (terms, events, node-api, hub-api) documenting `ctx.tracing`, its wire contract and the `attach()` pattern for a tool's own recorder.",
"category": "docs",
"filePaths": [
"docs/app/app.config.ts",
"docs/content/1.guide/24.tracing-channels.md",
"docs/content/6.errors/DF0086.md",
"docs/content/6.errors/index.md",
"docs/content/8.references/1.terms.md",
"docs/content/8.references/3.events.md",
"docs/content/8.references/4.node-api.md",
"docs/content/8.references/6.hub-api.md"
]
},
{
"key": "generated-snapshots",
"label": "Generated API snapshots",
"summary": "Regenerated `tsnapi` snapshot files reflecting the new tracing types, `DEVFRAME_EVENTS` entries, `DF0086` diagnostic and `createTracingRecorder` export.",
"category": "tests",
"filePaths": [
"tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts",
"tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts",
"tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts",
"tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts",
"tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts",
"tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts",
"tests/__snapshots__/tsnapi/devframe/node.snapshot.js",
"tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts"
]
}
],
"schemaVersion": 1,
"source": "llm",
"generatedAt": "2026-11-19T02:24:59.809Z",
"model": "vercel-ai-gateway/anthropic/claude-sonnet-5",
"locale": "en"
}
} |
Move the tracing diagnostic to DF0086: main took DF0081 for MCP content blocks.
antfu
enabled auto-merge
November 19, 2026 02:24
antfu
approved these changes
Nov 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Node.js publishes
TracingChannelevents (start,end,asyncStart,asyncEnd,error) around units of work, and so can any library or app. devframe had no way to list those channels or show what they trace. This is PR 1 of 3 from plan 009 (#426): the core primitive and its wire contract. PR 2 adds the inspect tab, PR 3 traces devframe's own RPC and shared-state writes.What
ctx.tracingon every node context (scoped contexts included):register,list,record,stop,records,clear,onRecord.register()returns Node'sTracingChannel, so a producer declares and traces with one call.module.require,net.server.listen),register()calls, a newtracing.channelsfield onDevframeDefinitionand oninitHub/buildHuboptions, and ad-hocrecord()names.DevframeTraceRecord. A ring buffer keeps 500 records per channel.devframe:tracing:channels, streaming channeldevframe:tracing(one stream per recording channel, id published asstreamId), RPC actionsdevframe:tracing:record|stop|clear. Names live inDEVFRAME_EVENTSand the events reference.DF0086reports once wheretracingChannelis missing; every method is a no-op there andregister()returns a pass-through stand-in.ctx.tracing.attach(source)shows a tool's own tracing instance. The tool makes it withcreateTracingRecorder()fromdevframe/node, or any object of theDevframeTracingSourceshape. Devframe shows the source's channels and passes on its records. It does not record them itself:record,stopandclearcall the source's own methods.One deviation from the plan: each recording gets a fresh stream id instead of reusing the channel name, because
streaming.start({ id })with an id that is still retained silently replaces the record. The plan doc gets this note in #426.Created with the help of an agent.