minitrail 0.2.1

Lightweight file-based OTel tracing for AI agent frameworks — with built-in viewer

minitrail

Work in progress — use at your own risk.

Lightweight, file-based OpenTelemetry tracing for AI agent frameworks — with an optional built-in web viewer.

minitrail captures every LLM call your agents make and writes one JSON file per trace to disk. No collector, no database, no infrastructure. Optionally generates live human-readable Markdown reports with token counts and cost breakdowns.

Features

• One-call setup — from minitrail import setup; provider = setup() before your framework imports
• File-per-trace JSON export — each trace is a self-contained JSON file under logs/json/
• Live Markdown export — human-readable .md files with messages, token counts, cost tables, and extracted images
• Built-in web viewer — minitrail serve launches a FastAPI app with an interactive span waterfall
• Auto-instrumentation — automatically patches LangChain, LlamaIndex, CrewAI, and Haystack via OpenInference
• Cost tracking — built-in pricing for Anthropic, OpenAI, Amazon Nova, Mistral, and Meta Llama models

Installation

pip install "minitrail"               # Strands Agents
pip install "minitrail[langchain]"    # LangChain / LangGraph
pip install "minitrail[crewai]"       # CrewAI
pip install "minitrail[llama-index]"  # LlamaIndex
pip install "minitrail[all]"          # all supported frameworks

Quick start

setup() must be called before importing your framework so the instrumentor can patch it.

from minitrail import setup

provider = setup(
    service_name="my-agent",
    logs_dir="logs",
    markdown=True,          # also write human-readable Markdown
)

# --- import your framework AFTER setup() ---
from langchain.chat_models import init_chat_model
# ... your agent code ...

provider.force_flush()
provider.shutdown()

Traces are written to:

logs/
  json/                  # machine-readable JSON (always)
  human_readable/        # Markdown + images (when markdown=True)
    images/

Viewing traces

When markdown=True is set, traces are written as Markdown files under logs/human_readable/. These can be read directly in any text editor, terminal, or Markdown viewer — no server required.

For an interactive experience with span waterfall, collapsible details, and per-model cost breakdowns, launch the built-in web viewer:

minitrail serve logs/
minitrail serve logs/ --port 9000

Or run as a module:

python -m minitrail serve logs/

API reference

setup()

setup(
    service_name: str = "minitrail",
    logs_dir: str = "logs",
    markdown: bool = False,
    frameworks: list[str] | None = None,
    instrument: bool = True,
) -> TracerProvider

Parameter	Description
service_name	Value for the service.name OTel resource attribute
logs_dir	Root directory for trace output
markdown	Also write human-readable .md files
frameworks	List of frameworks to instrument (e.g. ["langchain"]). None = auto-detect all
instrument	Set to False to skip framework instrumentation

Returns the configured TracerProvider. Call provider.force_flush() and provider.shutdown() when done.

Exporters

For advanced use, the exporters can be used directly with any OpenTelemetry TracerProvider:

• FilePerTraceExporter(directory) — writes one JSON file per trace
• MarkdownTraceExporter(directory) — writes live Markdown reports

Examples

The examples/ directory contains complete working examples with LangGraph, CrewAI, and Strands Agents. All examples use Amazon Bedrock (Nova Pro + Claude Opus) and require AWS credentials.

Running from the repo

python -m venv .venv && source .venv/bin/activate

Strands Agents:

pip install -e . strands-agents
python examples/example_strands.py

LangGraph:

pip install -e ".[langchain]" langchain langchain-aws langgraph
python examples/example_langgraph.py

CrewAI:

pip install -e . "crewai[bedrock]" openinference-instrumentation-crewai
python examples/example_crewai.py

Then view the traces. Look into ./logs/human_readable or use the web UI:

minitrail serve ./logs

License

MIT