TraceLab Python SDK

Record traces from your LLM application or agent and send them to a TraceLab backend. Inspect inputs, outputs, nested operations, errors, latency, and usage in the TraceLab workspace.

Requires Python 3.11+ and a running TraceLab backend with a project API key. This package contains the instrumentation client; run the backend and workspace separately.

Install

Install the released SDK from PyPI:

python -m pip install tracelab-sdk

For a local or unpublished build, install its wheel directly:

python -m pip install ./tracelab_sdk-0.1.0-py3-none-any.whl

Connect your application

Set the address of your TraceLab backend and a key issued by that deployment:

export TRACELAB_URL="http://127.0.0.1:8000"
export TRACELAB_API_KEY="YOUR_PROJECT_KEY"

For a shared deployment, use its HTTPS address instead of localhost. Keep the project key in your server environment.

Wrap your existing model function with a trace and an LLM span:

import os

from tracelab import TraceLabClient

client = TraceLabClient(
    base_url=os.environ["TRACELAB_URL"],
    api_key=os.environ["TRACELAB_API_KEY"],
    service_name="my-agent",
    spool_dir=".tracelab-spool",
)


def traced_answer(question, call_model):
    with client.trace(
        "answer-question",
        workflow_version="v1",
        input={"question": question},
    ) as trace:
        with trace.span("generate-answer", "llm", input=question) as span:
            answer = call_model(question)
            span.set_output(answer)
        trace.set_output(answer)
    return answer

Call traced_answer(question, your_existing_model_function) with a function that returns a JSON-serializable result. Reuse the client across requests and call client.close() at application shutdown. Each trace exports when its context closes.

Open the workspace connected to the same project key to inspect the run. Exceptions are recorded and re-raised to your application.

Record tools, usage, and evaluations

• Nest trace.span("lookup-order", "tool") inside a trace to record a tool call. Set its input and output explicitly; nested spans retain their parent relationships.
• Call span.set_usage(input_tokens=12, output_tokens=7) with the actual provider-reported counts. An optional cost_usd records a cost you supply; the SDK does not calculate prices.
• Use an evaluator span to record a check you implement. Set its output to a JSON object such as {"passed": False, "score": 0}, and call span.set_error("explanation") to mark a failed check without raising.
• Set workflow_version to identify prompt or application versions for comparisons. The package does not include the sample support agent, its dataset, or its experiment runner.

Instrumentation and evaluation are explicit. The SDK does not automatically capture model calls, score answers, or send regression alerts.

Export behavior

Exports are synchronous, with bounded retries for transient failures. Retry time adds to the duration of closing a trace. An export failure emits a warning and preserves your application's result or original exception.

With spool_dir set, failed HTTP exports are saved to private JSON files. Retry them after restoring connectivity:

client.retry_exports()

Acknowledged files are removed; unsuccessful ones are retained. Common credential fields and email addresses are redacted before export and spooling. This is conservative filtering, not a comprehensive PII detector.

License

The Python SDK is licensed under MIT.