Metadata-Version: 2.4
Name: tracelink
Version: 0.5.0
Summary: Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly
Author-email: qinquan-ai <qin16778@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/qinquan-ai/Trace_Link
Project-URL: Documentation, https://github.com/qinquan-ai/Trace_Link#readme
Project-URL: Issues, https://github.com/qinquan-ai/Trace_Link/issues
Project-URL: Changelog, https://github.com/qinquan-ai/Trace_Link/blob/main/CHANGELOG.md
Keywords: tracing,debug,logging,ndjson,skill,ai-agent,scope,fastapi,starlette
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fastapi
Requires-Dist: starlette>=0.27; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Dynamic: license-file

# tracelink

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

## Install

```bash
pip install tracelink
```

With FastAPI/Starlette support:

```bash
pip install tracelink[fastapi]
```

## Quick Start

```python
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`.

```python
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)

```python
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`](https://github.com/qinquan-ai/Trace_Link/tree/main/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

```bash
tracelink --port 8080
```

## Links

- [Homepage](https://github.com/qinquan-ai/Trace_Link)
- [Documentation](https://github.com/qinquan-ai/Trace_Link#readme)
- [Issues](https://github.com/qinquan-ai/Trace_Link/issues)
