auralogs 1.0.0

Auralogs Python SDK — agentic logging and application awareness.

auralogs

Python SDK for Auralogs — agentic logging and application awareness.

Auralogs acts as an on-call engineer — powered by your choice of model (Claude, OpenAI, or any MCP-compatible LLM) — monitoring your logs and errors, alerting you when something's wrong, and opening fix PRs automatically.

Install

pip install auralogs

Quick start

from auralogs import init, auralogs

init(api_key="aura_your_key", environment="production")

auralogs.info("user signed in", metadata={"user_id": "123"})
auralogs.error("payment failed", metadata={"order_id": "abc"})

Python 3.10+.

Bridge the stdlib logging module (recommended for existing codebases)

Python's logging module is used everywhere — including frameworks (Django, Flask, FastAPI) and libraries (requests, SQLAlchemy, Celery). AuralogsHandler captures those logs without requiring code changes:

import logging
from auralogs import init, AuralogsHandler

init(api_key="aura_your_key", environment="production")

logging.getLogger().addHandler(AuralogsHandler())
logging.getLogger().setLevel(logging.INFO)

# Any existing logging.* calls — including from third-party libraries — flow to auralogs
logging.info("payment processed", extra={"order_id": "abc"})

Restricting which extra fields ship (metadata_allowlist)

By default AuralogsHandler forwards every key from the underlying LogRecord.__dict__ minus a curated denylist of stdlib fields. If your codebase passes sensitive values via extra={...} (auth tokens, raw PII, internal IDs) and you'd rather opt-in than opt-out, pass an explicit allowlist:

logging.getLogger().addHandler(
    AuralogsHandler(metadata_allowlist={"user_id", "tenant", "request_id"})
)

# Only "user_id" reaches the wire — "auth_token" is dropped.
logging.info("user fetched", extra={"user_id": "u_1", "auth_token": "secret"})

When metadata_allowlist is set, only the named keys are included; default behavior (denylist of stdlib fields) is preserved when it is omitted.

Configuration

Option	Type	Default	Description
api_key	str	required	Your Auralogs project API key
environment	str	"production"	e.g. "production", "staging", "dev"
endpoint	str	https://ingest.auralogs.ai	Ingest endpoint override
flush_interval	float	5.0	Seconds between batched flushes (errors flush immediately)
capture_errors	bool	True	Capture uncaught exceptions (main thread, threads, asyncio)
trace_id	str	auto-generated	Custom trace ID for distributed tracing
global_metadata	dict[str, Any] or Callable[[], dict[str, Any]]	None	Baseline metadata merged into every emitted log entry. Per-call metadata keys win on collision (shallow merge). Synchronous suppliers only.
max_queue_size	int	1000	Maximum buffered (non-error) log entries held in memory between flushes. When the buffer is full, the oldest entries are dropped first so an unreachable ingest endpoint can't OOM the host process. Errors bypass the buffer.
allow_insecure_endpoint	bool	False	Permit a non-https:// endpoint. Off by default so a misconfigured endpoint=http://... can't silently downgrade every POST to plaintext. Opt in for local development ingests only.

Attaching session-scoped fields to every log (global_metadata)

To pin fields like user_id, tenant, or a feature-flag snapshot onto every log entry — including framework-bridge captures (AuralogsHandler) and uncaught-error captures — pass global_metadata to init. Two forms are supported:

Static dict — for values that don't change over the process lifetime:

init(api_key="aura_your_key", global_metadata={"service": "billing", "region": "us-east"})

Callable supplier — invoked at every emit, so values can change over time. This is the canonical recipe for attaching the current user to every log:

from contextvars import ContextVar
from auralogs import init, auralogs

current_user: ContextVar[str | None] = ContextVar("current_user", default=None)

def session_metadata() -> dict[str, object]:
    return {"user_id": current_user.get()}

init(api_key="aura_your_key", global_metadata=session_metadata)

# Anywhere a request handler sets the user, every subsequent log carries it:
current_user.set("u_123")
auralogs.info("checkout completed")
# -> metadata = {"user_id": "u_123"}

Per-call metadata still wins on collision, so impersonation and admin actions can override:

auralogs.info("admin override", metadata={"user_id": "admin_7"})  # admin_7, not u_123

Caveats:

• The supplier runs on every emit — keep it O(1) cheap. Don't hit a database or do I/O.
• Synchronous only. If your supplier is an async def, or returns a coroutine/awaitable, the entry is emitted without global_metadata and a one-time warning is logged. Cache async state into a ContextVar or thread-local from the sync side.
• If the supplier raises, the entry is still emitted (without global_metadata) — logging never crashes the host.
• Non-JSON-serializable values are dropped (with a one-time warning); the entry still ships with per-call metadata.

Attaching a traceback

try:
    risky()
except Exception as e:
    auralogs.error("task crashed", metadata={"task": "ingest"}, exc_info=e)

Graceful shutdown

auralogs flushes pending logs on interpreter exit automatically via atexit. For deterministic flush (serverless handlers, short-lived scripts):

from auralogs import shutdown
shutdown()

Thread and async safety

• Threads: The transport uses a threading.Lock around the in-memory batch. Safe for multi-threaded apps (Django under Gunicorn, FastAPI workers, Celery).
• Background flushing: A daemon thread flushes every flush_interval seconds; errors send immediately on a separate endpoint.
• Asyncio: Error capture installs a handler on the active event loop when init() runs inside one. Call init() from your framework's startup hook so it installs against your app's loop.

Verify this package

Every release is published with sigstore provenance attestations via GitHub Actions. The attestation proves the distribution was built from a specific commit in this repository — without having to trust PyPI or the maintainer.

Inspect the attestation on pypi.org/project/auralogs under "Provenance".

Documentation

Full docs at docs.auralogs.ai.

Security

Found a vulnerability? See SECURITY.md for how to report it.

License

MIT © James Thomas