argus

Auto-instrumenting observability SDK for LLM inference.

One call at startup. Every provider call in the process is captured after that — including calls made by code you did not write, because the instrumentation replaces the method on the provider's class, not on a client instance you hand it.

Install

uv add llm-argus
pip install llm-argus

The distribution is llm-argus; the import is argus.

Provider packages are extras, not dependencies — instrumenting Groq should not require OpenAI's package to be installed:

uv add "llm-argus[groq]"     # or llm-argus[openai], llm-argus[all]

Unreleased work can be installed straight from the repository:

uv add "llm-argus @ git+https://github.com/shrirang3/argus@main#subdirectory=packages/argus"

Use

import argus

argus.init(endpoint="http://ingestion:8001/v1/events", service="chat-app")

# ...unchanged application code...
resp = await client.chat.completions.create(model=..., messages=...)   # logged

await argus.shutdown()   # in your shutdown hook — drains the buffer

Both arguments fall back to environment variables (ARGUS_ENDPOINT, ARGUS_SERVICE), so in a container the integration is import argus plus argus.init().

To correlate calls into conversations:

with argus.conversation(conversation_id):
    ...

Without it, events are still recorded — conversation_id is simply NULL.

What it guarantees

The wrapper is a decorator, never a replacement:

1. Calls through. The provider's own method does the work.
2. Re-raises the original exception. Never swallowed, never re-wrapped.
3. Returns the response untouched. The application cannot tell it is there.

The transport is non-blocking: emit() appends to a bounded in-memory buffer and returns. A background task batches and POSTs. On failure it degrades in stages — retry with backoff, then spill to disk, and only then drop, oldest first, counted. argus.stats() exposes those counters so data loss is visible rather than silent.

What it instruments today

Anthropic and the OpenAI Responses API are not wired yet.

Configuration

Every field of argus.Config is overridable by environment variable, because the knobs that need turning — buffer size, flush interval — are the ones you discover under load, in a deployed container, without a code change:

ARGUS_ENDPOINT, ARGUS_SERVICE, ARGUS_ENABLED, ARGUS_QUEUE_MAXSIZE, ARGUS_BATCH_SIZE, ARGUS_FLUSH_INTERVAL, ARGUS_TIMEOUT, ARGUS_MAX_RETRIES, ARGUS_SPILL_PATH.

Requirements

Python 3.11+, and a collector listening at endpoint that accepts the EventBatch payload in argus.schema. The reference collector, worker, Postgres schema and dashboard live in the argus repository.

The drain task starts on the running asyncio event loop, so a fully synchronous (WSGI) application will buffer events without sending them.

License

MIT