Metadata-Version: 2.4
Name: tracelink
Version: 0.6.6
Summary: Python SDK for TraceLink local tracing and cross-service context propagation
Author-email: qinquan-ai <qin16778@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/qinquan-ai/tracelink
Project-URL: Documentation, https://github.com/qinquan-ai/tracelink#readme
Project-URL: Issues, https://github.com/qinquan-ai/tracelink/issues
Project-URL: Changelog, https://github.com/qinquan-ai/tracelink/blob/main/CHANGELOG.md
Keywords: tracing,debug,logging,ndjson,skill,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.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.10
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 Python SDK

English | [简体中文](https://github.com/qinquan-ai/tracelink/blob/main/sdks/python/README.zh-CN.md)

The Python SDK builds protocol-compatible spans, keeps async context with
`contextvars`, writes optional local files, exports events to the shared
TraceLink Receiver, and integrates incoming FastAPI/Starlette requests.

It does not ship a Python Receiver, Dashboard, or CLI. Start those from the npm
package with `npx tracelink dashboard`.

## Install

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

## Optional Coding-Assistant Skill

The PyPI package provides the Python SDK but does not install the repository's
coding-assistant Skill. Install that separately with the
[Skills CLI](https://github.com/vercel-labs/skills):

```bash
npx skills add qinquan-ai/tracelink --skill tracelink
```

The CLI detects supported AI agents and either selects or prompts for the
installation target. Installation is project-local by default; pass `--global`
to make the skill available across projects.

The Skill helps a coding assistant add TraceLink instrumentation and analyze
existing debug data. It does not provide AI-agent runtime integration or
agent-specific tracing semantics.

## Trace And Export

```python
from tracelink import tracer

exporter = tracer.configure(
    enabled=True,
    http_endpoint="http://127.0.0.1:5174/__debug_log",
    scope_sync_endpoint="http://127.0.0.1:5174/__debug_log/scopes",
    file_enabled=False,
)

async def load_order():
    tracer.db("orders.py:load", "load order", scope="checkout")

await tracer.span(
    "BE-ENTRY",
    "routes.py:checkout",
    "checkout",
    load_order,
    scope="checkout",
)

exporter.flush(timeout=5.0)
```

Without `enabled=True`, startup follows `TRACELINK_ENABLED`, then the `DEBUG` or
`DEV` environment variables. `TRACELINK_SCOPES` initializes the local Scope
policy (`*` or a comma-separated list).

## Custom Exporter

```python
from tracelink import HttpExporter, tracer

off = tracer.add_exporter(HttpExporter())
off()
```

`HttpExporter` uses a bounded background queue and standard-library HTTP. Its
network failures never escape into application code. `FileExporter` writes
`.tracelink/trace.ndjson` and `.tracelink/trace.log` locally. It is enabled by
default; set `file_enabled=False` when a Receiver in the same project owns those
files, otherwise the SDK and Receiver can write duplicate rows.

## FastAPI

```python
from fastapi import FastAPI
from tracelink import TraceMiddleware

app = FastAPI()
app.add_middleware(TraceMiddleware)
```

The Extension extracts `x-trace-id`, `x-parent-span-id`, and `x-debug-scopes`,
installs request-local context, and restores the previous values after the
request. The caller's active span becomes the backend entry's parent. Middleware
does not create application spans; instrument route or service boundaries
explicitly.

## Outgoing HTTP

```python
from tracelink import create_trace_headers

requests.get(url, headers=create_trace_headers())
```

The helper is explicit and client-agnostic; TraceLink does not patch Requests,
HTTPX, or aiohttp globally.

## Context Guarantees

`ContextVar` preserves nested calls, `await`, and concurrent asyncio tasks.
Fresh OS threads do not automatically inherit context; copy or pass it
explicitly when creating a thread.

## Development

From the repository root:

```bash
npm run verify:python
```

This runs pytest, Ruff, strict mypy, builds an isolated wheel, installs it into
a temporary directory, and imports the installed artifact.
