Logging

There are two ways to send logs to Auralogs from Python, and you can freely mix them.

1. Direct API

Call auralogs methods directly:

from auralog import auralog

auralog.debug("hit cache", metadata={"key": "user:42"})
auralog.info("user signed in", metadata={"user_id": "123"})
auralog.warn("slow query", metadata={"duration_ms": 1240})
auralog.error("payment failed", metadata={"order_id": "abc"})
auralog.fatal("db connection lost")

# Attach a traceback to any error/fatal:
try:
    risky()
except Exception as e:
    auralog.error("task crashed", metadata={"task": "ingest"}, exc_info=e)

2. Stdlib logging bridge (recommended for existing codebases)

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

import logging
from auralog import init, AuralogHandler

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

# Attach once on the root logger
logging.getLogger().addHandler(AuralogHandler())
logging.getLogger().setLevel(logging.INFO)

# Normal logging.* calls flow to Auralogs
logging.info("payment processed", extra={"order_id": "abc"})
logger = logging.getLogger("myapp.billing")
logger.warning("slow request", extra={"duration_ms": 1240})

Level mapping

stdlib level	Auralogs level
DEBUG	debug
INFO	info
WARNING	warn
ERROR	error
CRITICAL	fatal

Metadata

Anything you pass in extra={...} is forwarded as metadata. Reserved LogRecord fields (like message, name, asctime) are filtered out automatically so they don’t pollute your data.

Combining with global metadata

If you’ve configured global_metadata, it is shallow-merged with per-call extra={...} (or the direct API’s metadata={...}) before the entry is sent. Per-call keys win on collision:

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

logging.warning("rate limited", extra={"route": "/api/checkout"})
# wire metadata: {"user_id": "u_42", "route": "/api/checkout"}

This is also how AuralogHandler-routed library logs (Django, FastAPI, SQLAlchemy, etc.) and uncaught errors get attribution — they pick up global_metadata automatically since they have no per-call object of their own.

Tracebacks

logging.exception() and logger.error(..., exc_info=True) automatically attach the current traceback to the Auralogs log entry.

When to use which

• Greenfield project: direct API. Explicit call sites, no stdlib config to learn.
• Existing codebase, lots of logging usage: handler. Zero rewrites, catches library logs too.
• Both: fine. Use auralog.info(...) at critical paths, let the handler catch the long tail.