tracelink 0.5.1

Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly

tracelink

Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly.

Install

pip install tracelink

With FastAPI/Starlette support:

pip install tracelink[fastapi]

Quick Start

from tracelink import debug_tracer

debug_tracer.start_scope('delete-work')
debug_tracer.entry('router.py:delete', 'user clicked delete', {'user_id': 123}, scope='delete-work')
debug_tracer.end_scope('delete-work')

Send to the TraceLink board (0.5.0)

The Python sender has HTTP parity with the Node sender: point it at the same standalone receiver + dashboard (started from the JS package via npx @qin16778/tracelink board, default port 5174) and Python and Node traces land on one board, correlated by traceId.

from tracelink import debug_tracer

# non-blocking, fail-safe HTTP sink -> the board
debug_tracer.configure(http_endpoint="http://127.0.0.1:5174/__debug_log")

First-run checklist (or you'll see nothing on the board):

• Start the board first. The receiver lives in the JS package; run npx @qin16778/tracelink board before your Python process emits.
• Enable tracing. It's on when a dev/debug env is set; otherwise force it with TRACELINK_ENABLED=1 or debug_tracer.set_enabled(True).
• Flush short scripts. Delivery is fire-and-forget on a daemon thread; for a short-lived script call sink.flush() before exit (the sink returned by configure()), so the last events land.

AI-agent spans (0.5.0)

from tracelink import debug_tracer

async def body():
    debug_tracer.blocked('agent.py:sub', 'write outside sandbox denied',
                         reason='permission denied', data={'path': '/etc/passwd'})

await debug_tracer.span('X-AGENT', 'agent.py:run', 'agent.run', body, scope='agent-run-py')

Spans auto-nest via contextvars (correct across await); the close event carries real durationMs + async, and blocked / intent set outcome. See the cross-language flagship demo: examples/ai-agent.

Features

• AI-agent native: debug_tracer.span() with auto traceId/parentSpanId nesting (contextvars), durationMs, async, and outcome (call / blocked / intent).
• Severity levels: level (debug / info / warn / error) for board filtering + coloring.
• Scope-filtered: group related log entries by scope name
• AI-friendly NDJSON: each entry is one JSON line, easy for AI agents to parse
• Zero dependencies: core uses only Python stdlib
• FastAPI/Starlette middleware: plug-and-play HTTP middleware
• Shared board: POST to the JS receiver so Python + Node traces render on one dashboard

CLI

tracelink --port 8080

Links

• Homepage
• Documentation
• Issues