Skip to content

feat(devframe): add ctx.tracing for Node.js Tracing Channels - #428

Merged
antfu merged 5 commits into
mainfrom
feat/tracing-host
Nov 19, 2026
Merged

antfu merged 5 commits into
mainfrom
feat/tracing-host

Conversation

@antfubot

@antfubot antfubot commented Oct 5, 2026 •

Copy link
Copy Markdown
Collaborator

Why

Node.js publishes TracingChannel events (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.tracing on every node context (scoped contexts included): register, list, record, stop, records, clear, onRecord. register() returns Node's TracingChannel, so a producer declares and traces with one call.
  • Known channels come from Node's built-ins (module.require, net.server.listen), register() calls, a new tracing.channels field on DevframeDefinition and on initHub / buildHub options, and ad-hoc record() names.
  • Subscription is on demand, so the app pays no tracing cost until something records. Lifecycle events sharing one context object fold into one DevframeTraceRecord. A ring buffer keeps 500 records per channel.
  • A serializer that never throws turns contexts holding sockets, requests, errors or cycles into JSON-shaped values.
  • Core owns the wire: shared state devframe:tracing:channels, streaming channel devframe:tracing (one stream per recording channel, id published as streamId), RPC actions devframe:tracing:record|stop|clear. Names live in DEVFRAME_EVENTS and the events reference.
  • DF0086 reports once where tracingChannel is missing; every method is a no-op there and register() returns a pass-through stand-in.
  • ctx.tracing.attach(source) shows a tool's own tracing instance. The tool makes it with createTracingRecorder() from devframe/node, or any object of the DevframeTracingSource shape. Devframe shows the source's channels and passes on its records. It does not record them itself: record, stop and clear call the source's own methods.
  • Docs: new guide page, terms, events, node-api and hub-api references, error page.

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.

@vercel

vercel Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
devframe Ignored Ignored Preview Nov 19, 2026 2:23am UTC

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.
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/devframes/devframe/428?from=github-actions[bot]

raw result

💭 analyzed by vercel-ai-gateway/anthropic/claude-sonnet-5
🕰️ 2026-11-19 02:24 UTC
🔗 head 96582a1
🤖 automated by pulls.review

{
  "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
antfu enabled auto-merge November 19, 2026 02:24
@antfu
antfu added this pull request to the merge queue Nov 19, 2026
@antfu
antfu removed this pull request from the merge queue due to a manual request Nov 19, 2026
@antfu
antfu merged commit fef9fb3 into main Nov 19, 2026
16 checks passed
@antfu
antfu deleted the feat/tracing-host branch November 19, 2026 02:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants