Metadata-Version: 2.4
Name: tracelm
Version: 0.4.2
Summary: Lightweight distributed LLM execution tracer and profiler
Author: Tapesh Chandra Das
License: MIT
Project-URL: Homepage, https://github.com/td-02/tracelm
Project-URL: Documentation, https://github.com/td-02/tracelm/blob/main/docs/ARCHITECTURE.md
Project-URL: Repository, https://github.com/td-02/tracelm
Project-URL: Issues, https://github.com/td-02/tracelm/issues
Keywords: llm,tracing,observability,profiling,rag,fastapi
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 :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == "fastapi"
Provides-Extra: requests
Requires-Dist: requests; extra == "requests"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk; extra == "otel"
Dynamic: license-file

# TraceLM

TraceLM is a lightweight execution tracer and profiler for LLM pipelines, RAG systems, and FastAPI-based AI services.

It focuses on the tracing primitives that matter when you want to understand execution flow clearly: span trees, `traceparent` propagation, sampling, profiling, and local inspection.

## Why TraceLM

TraceLM exists for developers who want observability without pulling in a full telemetry stack on day one.

- Trace multi-step LLM workflows with explicit spans
- Validate trace structure before profiling
- Continue traces across service boundaries with W3C `traceparent`
- Inspect latency, critical path, token usage, and cost from the CLI
- Export traces to Chrome Trace or OpenTelemetry-compatible JSON

It is intentionally small, local-first, and easy to read.

## Installation

```bash
pip install tracelm
```

Try it immediately:

```bash
tracelm demo
```

Optional integrations:

```bash
pip install "tracelm[fastapi]"
pip install "tracelm[requests]"
pip install "tracelm[otel]"
```

## Quick Start

The fastest path is the built-in demo:

```bash
tracelm demo
tracelm latest
tracelm export latest --format chrome
```

That gives you a real trace, a readable summary, and an exportable file without writing any code.

If you want to trace your own script, create a small instrumented file:

```python
from tracelm.decorator import node
```

Then run it:

```bash
tracelm run test_app.py
tracelm latest
```

Typical output:

```text
Trace Summary
-------------
Trace ID: 55df12035a754aa080875618bc5794c3
Total Latency: 0.204
Total Spans: 3
Slowest Span: step2
Critical Path: __root__ -> step2
Tokens In: 0
Tokens Out: 0
Total Cost: 0
Anomalies: {'latency_spikes': ['step2']}

Duration Histogram (ms)
-----------------------
0.000-0.100: 1
0.100-0.500: 1
...

Execution Tree
--------------
__root__ (0.204 ms)
+-- step1 (0.082 ms)
\-- step2 (0.101 ms)
```

## Features

- Hierarchical span tracing with a synthetic root span model
- W3C `traceparent` parsing and continuation
- FastAPI middleware integration
- Requests-based outbound propagation
- Head-based probabilistic sampling
- Critical path and slowest-span analysis
- Duration histogram generation
- Token and cost aggregation
- Trace comparison from the CLI
- Chrome Trace export
- OpenTelemetry JSON export and SDK bridge
- SQLite-backed local trace storage

## FastAPI Integration

```python
from fastapi import FastAPI
from tracelm.integrations.fastapi import TraceLMMiddleware

app = FastAPI()
app.add_middleware(TraceLMMiddleware, sample_rate=1.0)


@app.get("/")
def compute():
    return {"status": "ok"}
```

Import the requests integration to propagate trace context on outbound HTTP calls:

```python
import tracelm.integrations.requests
```

## CLI Commands

Run a Python file under tracing:

```bash
tracelm run test_app.py
```

Apply head sampling:

```bash
tracelm run test_app.py --sample-rate 0.1
```

Analyze a stored trace:

```bash
tracelm analyze <trace_id>
```

Analyze the most recent trace:

```bash
tracelm latest
```

List stored traces:

```bash
tracelm list
```

Compare two traces:

```bash
tracelm compare <trace_id_1> <trace_id_2>
```

Export to Chrome Trace:

```bash
tracelm export <trace_id> --format chrome
```

You can also use `latest` anywhere a trace ID is expected:

```bash
tracelm export latest --format chrome
```

Export to OTEL JSON:

```bash
tracelm export <trace_id> --format otel
```

## Design Notes

TraceLM keeps a strict execution model:

- One local root span for CLI-created traces
- Or one continuation entry span when joining an external trace
- DAG validation before profiling
- Async-safe context propagation with `ContextVar`

This keeps behavior predictable and makes failures explicit.

## Scope

TraceLM is currently:

- Single-process
- Developer-focused
- Local-first
- CLI-centered

It is useful for understanding and instrumenting pipelines before adopting heavier observability infrastructure.

## Documentation

- Architecture: `docs/ARCHITECTURE.md`
- Contribution guide: `CONTRIBUTING.md`

## License

MIT
