auralogger 0.1.10

Open-Source Developer package repository for AuraLogger, a real-time logging and observability SDK and CLI for streaming, storing, searching, and filtering application logs—beautifully visualized and accessible anywhere in the world across terminal, web, and any screen.

Auralogger for Python (SDK + CLI)

a real-time logging and observability SDK and CLI for streaming, storing, searching, and filtering application logs—beautifully visualized and accessible anywhere in the world across terminal, web, and any screen.

---

Quick start

Run CLI commands from the directory that contains your .env or .env.local (or wherever you export AURALOGGER_* in the shell or CI). The CLI loads .env files from the current working directory — cd into the app first.

Use a project virtualenv (python -m venv .venv) so the CLI and library version match the repo you are in. Auralogger is project-scoped (credentials per app), not a global “install once and forget which folder you are in” tool.

1) Install

From PyPI:

pip install auralogger

auralogger

2) Run init (credentials + server snippet)

Get private credentials from auralogger.com, then run this in your app repo (where .env should live):

auralogger init

auralogger init walks you through anything missing, prints a copy-paste block for your .env (project token, user secret, session — each line skipped if already set), then prints a small Python module you can drop into your repo (for example your_auralog_file.py) with a ready-made auralog(...) helper .

3) Sanity-check connectivity

Before you sprinkle auralog everywhere, confirm the path works:

auralogger server-check

Optional: send a handful of test logs through the same path your app uses:

auralogger test-serverlog

If token or user secret is missing after .env is loaded, the CLI will prompt before running checks.

4) Send logs from code

Run auralogger init once and paste the printed module, or follow the shapes below.

Encryption is optional per project. If your project has no encryption enabled, you only need AURALOGGER_PROJECT_TOKEN (and optionally AURALOGGER_PROJECT_SESSION). If your project is encrypted, configure with AURALOGGER_PROJECT_TOKEN, AURALOGGER_USER_SECRET, and optionally AURALOGGER_PROJECT_SESSION.

Session precedence when calling Auralogger.configure(...): explicit session argument → AURALOGGER_PROJECT_SESSION from env → proj_auth response.

No encryption (recommended first): token only

import os
from typing import Any, Dict, Literal, Optional
from auralogger import Auralogger

def ensureConfigured() -> None:
    project_token = os.environ.get("AURALOGGER_PROJECT_TOKEN", "").strip()
    project_session = os.environ.get("AURALOGGER_PROJECT_SESSION", "").strip()
    # Silent opt-out: empty token keeps local-only logging.
    # Session: env → proj_auth fallback when session arg is empty.
    Auralogger.configure(project_token, session=project_session)

def auralog(
    type: Literal["debug", "info", "warn", "error"],
    message: str,
    location: Optional[str] = None,
    data: Optional[Dict[str, Any]] = None,
) -> None:
    ensureConfigured()
    Auralogger.log(type, message, location, data)

Encrypted projects: token + user secret (+ optional session)

import os
from typing import Any, Dict, Literal, Optional
from auralogger import Auralogger

def ensureConfigured() -> None:
    project_token = os.environ.get('AURALOGGER_PROJECT_TOKEN', '').strip()
    user_secret = os.environ.get('AURALOGGER_USER_SECRET', '').strip()
    project_session = os.environ.get('AURALOGGER_PROJECT_SESSION', '').strip()
    # Silent opt-out: missing creds keep local-only logging.
    # Session: env → proj_auth fallback when session arg is empty.
    Auralogger.configure(project_token, user_secret, session=project_session)
    # Auralogger.configure()  — omit credentials to print locally only (no streaming).

def auralog(
    type: Literal['debug', 'info', 'warn', 'error'],
    message: str,
    location: Optional[str] = None,
    data: Optional[Dict[str, Any]] = None,
) -> None:
    ensureConfigured()
    Auralogger.log(
        type,
        message,
        location,
        data,
    )

from your_auralog_file import auralog

auralog(
    "info",
    "Request completed",
    "api/orders#create",
    {"order_id": "ord_123", "status": 201},
)
# expected: [info] Request completed @ api/orders#create {"order_id": "ord_123", "status": 201}

auralog("warn", "Cache miss")
# expected: [warn] Cache miss

auralog("error", "Payment gateway timeout", data={"provider": "stripe"})
# expected: [error] Payment gateway timeout {"provider": "stripe"}

Important: the logging helper reads **os.environ only** — it does not load .env files by itself. In Django, FastAPI, Celery, etc., load env in your normal startup path (or rely on your host injecting variables).

5) Fetch logs in the terminal

auralogger get-logs -maxcount 20

Each run performs one HTTP request and prints the logs array from that response. Use **-maxcount** (capped at 100 in the CLI) and **-nextpage** to continue from the cursor returned by the previous response (the CLI prints it as “More results: …”). Full filter grammar, every field, and examples are in CLI commands (reference) below.

---

CLI commands (reference)

Subcommands for the auralogger entrypoint, then **get-logs** filters (same grammar as the Node CLI). Environment variable spellings: [user-docs/environment.md](user-docs/environment.md).

Invocation

auralogger <command> [arguments...]

Run auralogger --help to see all commands and options.

Commands (only get-logs takes extra filter tokens)

Command	Arguments	What it does
init	—	Prompts for missing AURALOGGER_PROJECT_TOKEN / AURALOGGER_USER_SECRET, prints copy-paste .env lines (token, user secret, session), then a Python server integration snippet with configure(...) and auralog(...).
server-check	—	One server-side test log over WebSocket; prompts for missing token or user secret if needed.
test-serverlog	—	Calls Auralogger.configure(...), sends 5 logs via aura_log, then closes the cached socket.
get-logs	[filters...]	POST to project logs with token + user secret (env or prompt). If styles are not in env, the CLI resolves them for that run so terminal colors match the dashboard when possible.

get-logs filter grammar

-<field> [--<operator>] <json-value>

• The token after the field name must be valid JSON.
• **maxcount** and **nextpage**: value must be a JSON number.
• All other fields: value must be a JSON array.

Paging: one CLI invocation → one request → one page of logs. There is no automatic multi-page loop inside the CLI.

Fields and operators

Field	Allowed operators	Default operator	Value shape
type	in, not-in	in	JSON array of type strings
message	contains, not-contains	contains	JSON array of substrings
location	in, not-in	in	JSON array of location strings
time	since, from-to	since	JSON array (e.g. ["10m"] for since; use from-to with a pair when supported)
order	eq	eq	JSON array: ["newest-first"] or ["oldest-first"]
maxcount	eq	eq	JSON number, clamped to 0..100
nextpage	eq	eq	JSON number (cursor returned by the previous response)
session	eq	eq	JSON array of session strings. If AURALOGGER_PROJECT_SESSION is set and you omit -session, the CLI prepends this filter for you.
data.<path>	eq	eq	JSON array — filter on nested data using a dot path (e.g. data.userId)

If you omit --<operator>, the default operator for that field is used (for example -type '["error"]' is the same as -type --in '["error"]').

Examples

auralogger get-logs -type '["error","warn"]' -maxcount 50
auralogger get-logs -message '["timeout"]' -nextpage 18423 -maxcount 30
auralogger get-logs -type --not-in '["info","debug"]' -time --since '["10m"]'
auralogger get-logs -data.userId '["06431f39-55e2-4289-80c8-5d0340a8b66e"]'
auralogger get-logs -order '["oldest-first"]' -maxcount 25

Common parse errors (filters)

• Expected 'get-logs'
• Expected field at position N
• Missing value for field '…'
• Invalid JSON for field '…'
• Field '…' expects a JSON array token
• Field 'maxcount' expects a JSON number token (and similarly for nextpage)
• Invalid op '…' for field '…'
• Unknown filter field: …

---

Browser and frontends

This package is for Python on the server. For React, Vue, Next, Vite, or any code bundled for the browser, use the **auralogger-cli** npm package and its client entry — project token only there, never AURALOGGER_USER_SECRET in frontend bundles.

---

When something does not work

• Wrong directory — Run the CLI from the folder that contains .env, or export variables in the shell.
• Logs never reach the dashboard — Confirm AURALOGGER_PROJECT_TOKEN and AURALOGGER_USER_SECRET are set for the process (or passed explicitly in your configure step). Set AURALOGGER_PROJECT_SESSION in env or pass session= to configure(); when omitted, the SDK falls back to the session from proj_auth. Logs always print locally — if they're not reaching the dashboard, check credentials and network; send/socket failures surface as stderr messages.
• **get-logs looks plain** — Optional style env vars are documented in [user-docs/environment.md](user-docs/environment.md); the CLI can still resolve styling for a run when those are unset.

---

Requirements

Python 3.8+.