Configuration

from auralog import init

init(
    api_key="aura_your_api_key",
    environment="production",               # default
    endpoint="https://ingest.auralog.ai",   # default
    flush_interval=5.0,                     # seconds
    capture_errors=True,                    # default
)

Options

Option	Type	Default	Description
api_key	str	required	Your Auralogs ingest key. Copy it from the startup modal or create another in project settings.
environment	str	"production"	e.g. "production", "staging", "dev". Used for filtering in the dashboard.
endpoint	str	https://ingest.auralog.ai	Ingest endpoint override (useful for self-hosted or local dev).
flush_interval	float	5.0	Seconds between batched flushes of the log buffer. Errors flush immediately regardless.
capture_errors	bool	True	If True, uncaught exceptions (main thread, threads, asyncio loops) are auto-reported.
global_metadata	dict[str, Any] | Callable[[], dict[str, Any]]	None	Baseline metadata merged into every log entry — including entries from AuralogHandler and uncaught-error capture. See Global metadata below.

Global metadata

Available since auralogs 0.2.0.

Use global_metadata to attach session-scoped fields — user_id, org id, feature-flag snapshot, build SHA — to every log entry without threading them through every call site. The merged metadata flows through direct API calls and entries emitted via AuralogHandler (the stdlib logging bridge) and uncaught-error capture, so attribution is consistent across all three.

Static form

If the value never changes for the lifetime of the SDK instance, pass a dict:

init(
    api_key="aura_...",
    global_metadata={"app": "checkout-service", "region": "us-east-1"},
)

Callable form

For values that change at runtime — the canonical case being a per-request ContextVar user — pass a zero-arg callable. It is invoked at every log emission, so it always reflects current host state:

from contextvars import ContextVar
from auralog import init

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

init(
    api_key="aura_...",
    global_metadata=lambda: {"user_id": current_user.get()},
)

Now every direct call, every entry routed through AuralogHandler, and every uncaught error carries user_id — searchable in the dashboard via user_id:abc and visible to your AI provider during analysis.

Merge semantics

When a per-call metadata argument is also provided, the two are shallow-merged with per-call winning on collision:

# global_metadata=lambda: {"user_id": "u_42", "region": "us"}
auralog.info("impersonating session", metadata={"user_id": "u_99"})
# final metadata: {"user_id": "u_99", "region": "us"}

This lets a specific log line legitimately reference a different user (impersonation, admin actions) without mutating global state.

Failure modes

The SDK never crashes the host. If the supplier:

• raises — the entry ships without global_metadata (per-call metadata is preserved). A single warning fires per Logger instance via the auralogs stdlib logger at WARNING; subsequent failures of the same kind are silent.
• returns a coroutine or awaitable — same. Async suppliers are not supported; cache async state in a ContextVar (or similar) accessible synchronously. Returned coroutines are explicitly closed to suppress “coroutine was never awaited” runtime warnings.
• returns a non-JSON-serializable value — same. The entry still ships with just per-call metadata.

Performance

The supplier runs on every log emission. Keep it O(1) — read from a ContextVar or cached object, not a database or remote call.

Keyword-only

init takes keyword arguments only — this keeps call sites explicit and forward-compatible as we add options.

# ✅ works
init(api_key="k", environment="prod")

# ❌ TypeError
init("k", "prod")

Idempotent

Calling init again replaces the previous configuration and flushes the prior transport — useful in long-lived workers where you want to rotate the API key without restarting the process.

Reading from the environment

The SDK doesn’t read AURALOG_API_KEY automatically — do it explicitly so it’s obvious where the key comes from:

import os
from auralog import init

init(
    api_key=os.environ["AURALOG_API_KEY"],
    environment=os.environ.get("APP_ENV", "dev"),
)