zoroval

The Zoroval Python SDK. It sends your LLM app's traces to Zoroval, grouped as whole conversations, so you can find and fix what goes wrong for your users.

• One init() line. OpenAI (Chat Completions and Responses) and Anthropic (Messages) are traced automatically: sync, async and streaming, with tool-call ids.
• One trace per conversation: wrap a chat in zoroval.conversation(chat_id).
• Safe for production: it never raises into your code, never blocks a request, caps its memory in bytes, and exits within 5 seconds even when the network is down.
• Works beside Langfuse, OpenTelemetry, OpenInference and OpenLLMetry, in either install order, without duplicate spans.
• Apache-2.0.

Status: 0.1.0, not yet published. The gateway it talks to is being built.

Install and set up

pip install zoroval
zoroval login      # opens the browser; writes ZOROVAL_INGEST_KEY to your git-ignored .env
zoroval doctor     # sends a test trace and checks it arrived

Using a coding agent? Point it at get-started.md. The setup skill is in skills/setup/SKILL.md.

Use

import zoroval
from openai import OpenAI

zoroval.init()  # reads ZOROVAL_INGEST_KEY
client = OpenAI()

def handle_message(chat_id: str, user_id: str, text: str) -> str:
    with zoroval.conversation(chat_id, user_id=user_id):
        with zoroval.turn(input=text) as turn:
            reply = client.chat.completions.create(model="gpt-5", messages=history(chat_id, text))
            answer = reply.choices[0].message.content
            turn.set_output(answer)
            return answer

Agents and batch jobs that are not chats use zoroval.trace():

@zoroval.tool
def search_orders(customer_id: str) -> list: ...

@zoroval.step
def plan(goal: str) -> list: ...

with zoroval.trace("nightly-report", user_id="ops"):
    plan("summarize yesterday")

A @zoroval.tool run links to the model's tool-call id: pass call_id= to zoroval.tool(...), or let the SDK match the one pending call with the same name (and arguments, when several are pending). Ambiguous calls stay unlinked; the SDK never pairs by position.

API

Environment variables: ZOROVAL_INGEST_KEY, ZOROVAL_INGEST_URL, ZOROVAL_SERVICE_NAME (or OTEL_SERVICE_NAME), ZOROVAL_ENVIRONMENT, ZOROVAL_RELEASE, ZOROVAL_CAPTURE_CONTENT, ZOROVAL_SAMPLE_RATE, ZOROVAL_ENABLED.

Privacy

• Prompts and outputs are captured by default. capture_content=False keeps model names, usage, timings, errors and tool-call ids, and drops content.
• redact=fn gets each captured value and returns the value to send. If fn raises, that field is dropped, never sent raw. Changed spans carry zoroval.redacted=true.
• Both controls also cover spans from other tools (OpenInference, Langfuse, OpenLLMetry, OTel GenAI). Their content attributes (for example input.value, llm.input_messages.*, langfuse.observation.input, gen_ai.prompt.*, gen_ai.input.messages) are dropped, or passed through redact as the raw attribute value, and GenAI span events are dropped. Your other exporters still get the original spans.
• GenAI log events from the OTel contrib instrumentors are sent only when capture_content=True and no redact hook is set.
• @zoroval.step and @zoroval.tool capture all arguments and the return value. Use capture_input=False on functions that take secrets, or capture_content=False.
• Images and files in messages are replaced by placeholders.
• Only GenAI spans leave the process. Your app's HTTP, database and other spans are never sent to Zoroval.
• When Zoroval attaches to your existing OpenTelemetry provider, its LLM spans also reach your other exporters, with content. Use capture_content=False or a filter on that side if needed.

How it behaves under load and failure

Coexistence

Development

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e '.[dev]' openinference-instrumentation-openai python-dotenv
.venv/bin/python -m pytest

Tests run against a fake Zoroval gateway (testing/fake_gateway.py) and fake OpenAI and Anthropic servers (testing/fake_llm.py). No real API calls.

License

Apache-2.0. See LICENSE.