Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

Python

Strukturierte Logs aus deinen Python-Services, mit einem logging-Handler. Nur die Standardbibliothek.

Server, Worker, Skripte

Das Paket lyrelog braucht Python 3.11 oder neuer und hat keine Abhängigkeiten.

Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin schlägt uv add lyrelog fehl: Auf PyPI gibt es kein solches Paket.

Installation

uv add lyrelog

Starten

Einmal, beim Start. lyrelog.init startet den Standard-Client (ein früherer wird geflusht und ersetzt) und gibt ihn zurück; die Funktionen auf Modulebene verwenden ihn.

import lyrelog

lyrelog.init(
    api_key="lyr_srv_...",   # a server key: it can append events, never read them
    release="2.0.1",         # goes to resource.app_version
    app_id="orders-api",
)

Verwende einen Server-Schlüssel, lyr_srv_..., von der Seite API keys des Projekts (Send events from a server). Er ist geheim: Bewahre ihn in der Umgebung deines Servers auf, nie in einer App oder einer Webseite. Seine Events sind verifiziert, und das Tageslimit für die Adresse eines einzelnen Absenders gilt für sie nicht. Ein Ingest-Schlüssel, lyr_ing_..., funktioniert auch, aber seine Events sind nicht verifiziert.

Events gehen an https://ingest.lyrelog.com. Gib endpoint nur an, wenn du sie woandershin schicken willst. Das ist die Basis-URL (ein eingefügter Pfad .../v1/events:batch wird entfernt) und muss mit https:// beginnen, oder mit http:// für localhost.

Ein leerer api_key ergibt einen Client, der Events annimmt und nichts sendet, damit eine fehlende Umgebungsvariable in der Entwicklung die App nicht abstürzen lässt. Ein fehlender Schlüssel oder ein ungültiger Endpoint wird einmal als Warnung auf dem Logger lyrelog gemeldet.

lyrelog.Client(endpoint, api_key, ...) ist dasselbe ohne den Standard-Client auf Modulebene, für ein zweites Projekt oder für Tests: Jede Funktion unten ist auch eine Methode darauf. lyrelog.get_client() gibt den Standard-Client zurück, oder None vor init.

Events loggen

Eine Funktion pro Level: trace, debug, info, notice, warning, error, critical oder lyrelog.log(level, message, ...).

lyrelog.info("checkout_done", attrs={"items": 3, "latency_ms": 412})
lyrelog.error("payment_declined", category="checkout", attrs={"code": 51}, payload={"response": raw})

Ein Log-Aufruf blockiert nie und wirft nie: Alles Ungewöhnliche, was du übergibst (Objekte, NaN, Zyklen), wird in etwas Gültiges umgewandelt. Nach shutdown() tun Log-Aufrufe nichts mehr.

Logger für jeden Bereich

billing = lyrelog.logger("billing")
billing.warning("refund_denied", attrs={"order_id": order.id}, user_id=order.user_id)

Ein Logger folgt zum Zeitpunkt des Aufrufs dem Standard-Client, du kannst ihn also schon beim Import erstellen, vor init.

Nutzer

lyrelog.set_user("u_123")   # attached to every following event, process-wide
lyrelog.info("checkout_done", user_id=request_user)   # for this event only

Ein Server bedient viele Personen gleichzeitig, setz deshalb lieber user_id= bei jedem Aufruf statt set_user.

Der Logging-Handler

Am schnellsten geht es mit install_logging: Es hängt einen LoggingHandler an den Root-Logger (und mit uvicorn=True, dem Standard, auch an uvicorn und uvicorn.error) und senkt den Root-Logger auf level, falls er darüber liegt, damit INFO-Records durchkommen. Ein erneuter Aufruf ersetzt den vorherigen Handler, und uninstall_logging() entfernt ihn; uvicorn.access bleibt außen vor (Requests zeichnest du besser in einer Middleware auf).

import logging
import lyrelog

lyrelog.install_logging(logging.INFO)

Wenn du den Handler selbst hinzufügst, denk daran, dass der Root-Logger standardmäßig bei WARNING aufhört: Ein Handler auf INFO bekommt nichts unterhalb von WARNING, bis der Root-Logger es durchlässt.

import logging
import lyrelog

logging.basicConfig(level=logging.INFO)   # or logging.getLogger().setLevel(logging.INFO)
logging.getLogger().addHandler(lyrelog.LoggingHandler(level=logging.INFO))

log = logging.getLogger("app.orders")
log.info("order %s shipped", order_id, extra={"items": 3, "user_id": uid})
log.exception("email_failed")   # inside an except: the traceback goes in the payload
loggingLyrelog
Name des Loggers (app.matches, uvicorn.error)category
DEBUG ... CRITICALDieselben; unter DEBUG ist trace, zwischen INFO und WARNING ist notice
Die formatierte Nachrichtmessage; mit Argumenten geht das Template zum Gruppieren nach attrs.msg_template
Felder aus extra=attrs, außer user_id (der Nutzer des Events) und payload (behalten als payload.data)
exc_infopayload.exception und attrs.error_type, attrs.error_message
Datei, Zeile, Funktionpayload.source

Der Handler leitet nie den eigenen Logger des SDK weiter, es kann also keine Schleife entstehen. Dieser Logger heißt lyrelog: Um zu sehen, was das SDK selbst meldet (einen abgelehnten Schlüssel, einen falschen Endpoint, verworfene Events), gib ihm einen Handler, zum Beispiel logging.getLogger("lyrelog").setLevel(logging.DEBUG) zusammen mit basicConfig. Für Events, die du in Diagrammen auswerten willst, sind direkte Aufrufe mit einem stabilen Namen besser: Eine formatierte Nachricht ist Fließtext.

FastAPI

import logging
import os
import time

import lyrelog
from fastapi import FastAPI, Request

lyrelog.init(
    api_key="lyr_srv_...",   # a server key, or read it from your own settings
    platform="api",          # instead of "python", to tell it apart from a worker
    release=os.environ.get("GIT_SHA"),
    app_id="orders-api",
)
# uvicorn.error carries the tracebacks of unhandled exceptions. Uvicorn's loggers don't
# propagate to the root logger (propagate=False), so a root handler never sees them:
# uvicorn=True attaches the handler to them too. Uvicorn replaces its loggers' handlers when
# it applies its config, so call this after that: here, at import of the app module that
# `uvicorn app:app` runs, or in the app's lifespan startup.
lyrelog.install_logging(logging.INFO, uvicorn=True)

app = FastAPI()
http = lyrelog.logger("http")


@app.middleware("http")
async def record_request(request: Request, call_next):
    start = time.perf_counter()
    status = 500
    try:
        response = await call_next(request)
        status = response.status_code
        return response
    finally:
        route = request.scope.get("route")   # set by the router once it matched
        http.log(
            "error" if status >= 500 else "warning" if status >= 400 else "info",
            "http_request_served",
            attrs={
                "method": request.method,
                "route": getattr(route, "path", "unmatched"),   # /matches/{match_id}, not the id
                "status": status,
                "duration_ms": round((time.perf_counter() - start) * 1000, 1),
            },
        )

Das Routen-Template hält IDs aus dem Attribut heraus, sodass das Dashboard nach Route zählen kann. Die Middleware erfasst unbehandelte Exceptions nicht selbst: Uvicorn loggt jede davon mit ihrem Traceback auf uvicorn.error, und install_logging leitet diesen Record mit error_type, error_message und dem Traceback weiter. Würdest du sie hier zusätzlich erfassen, käme jede doppelt an. Mit gunicorn oder uvicorn --workers bekommt jeder Worker-Prozess seinen eigenen Sender.

Django

Starte den Client einmal, in settings.py oder in deiner AppConfig.ready(), und schick logging-Records über Djangos Einstellung LOGGING:

# settings.py
import lyrelog

lyrelog.init(api_key="lyr_srv_...", platform="api", app_id="shop")

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"lyrelog": {"class": "lyrelog.LoggingHandler", "level": "INFO"}},
    "root": {"handlers": ["lyrelog"], "level": "INFO"},
    "loggers": {
        # Django's request errors carry the traceback of a 500.
        "django.request": {"handlers": ["lyrelog"], "level": "WARNING", "propagate": False},
    },
}

Ein Worker oder ein Skript

Ein Job, der für viele Personen läuft, setzt den Nutzer bei jedem Event und stoppt den Client, bevor er endet:

import os
import time

import lyrelog

lyrelog.init(api_key=os.environ.get("LYRELOG_KEY", ""), platform="worker", app_id="digest")
jobs = lyrelog.logger("jobs")


def send_digest(user):
    started = time.perf_counter()
    try:
        deliver(user)
    except Exception:
        jobs.capture_exception(attrs={"job": "digest"}, user_id=user.id)
        return
    jobs.info("digest_sent", attrs={"duration_ms": round((time.perf_counter() - started) * 1000)},
              user_id=user.id)


if __name__ == "__main__":
    for user in due_users():
        send_digest(user)
    lyrelog.shutdown()   # sends what's left, up to 5 s

Serverless und kurze Skripte

Der Worker sendet alle 5 s und ein letztes Mal beim Beenden (atexit). Eine Funktion, die zwischen Requests eingefroren wird (AWS Lambda, Cloud Functions), erreicht womöglich keins von beidem: Ruf vor dem Return lyrelog.flush() auf und prüf den Rückgabewert, wenn du es genau wissen musst.

def handler(event, context):
    try:
        return process(event)
    finally:
        lyrelog.flush(timeout=2)

atexit läuft nicht nach os._exit() und auch nicht, wenn der Prozess SIGTERM ohne Handler bekommt. Uvicorn und gunicorn behandeln SIGTERM und beenden sich normal; in deinem eigenen langlebigen Prozess stoppst du den Client in einem Handler:

import signal
import sys

import lyrelog


def on_sigterm(signum, frame):
    lyrelog.shutdown(timeout=2)
    sys.exit(0)


signal.signal(signal.SIGTERM, on_sigterm)

Nicht abgefangene Exceptions

Das SDK installiert keinen Hook für nicht abgefangene Exceptions. Um sie aufzuzeichnen, setz selbst einen, für den Hauptthread und für andere Threads:

import sys
import threading

import lyrelog


def report(exc_type, exc, tb):
    lyrelog.capture_exception(exc, level="critical")
    lyrelog.flush(timeout=2)
    sys.__excepthook__(exc_type, exc, tb)


def report_thread(args):
    if args.exc_value is not None and not issubclass(args.exc_type, SystemExit):
        name = args.thread.name if args.thread else ""
        lyrelog.capture_exception(args.exc_value, attrs={"thread": name}, level="critical")
    threading.__excepthook__(args)


sys.excepthook = report
threading.excepthook = report_thread

Frameworks fangen Exceptions innerhalb von Requests selbst ab: Dafür verwendest du die Middleware oben oder den Logger des Frameworks.

Exceptions

try:
    sync()
except Exception:
    lyrelog.capture_exception(category="jobs")

Ohne Argument erfasst es die Exception, die gerade behandelt wird; übergib eine, um eine andere zu erfassen. Es loggt exception auf error mit attrs.error_type und attrs.error_message (in jedem SDK gleich) sowie Typ, Nachricht und Traceback im Payload. message= und level= ändern Name und Level des Events, und user_id= setzt seinen Nutzer. Das capture_exception eines Loggers verwendet dessen Kategorie.

Umgebungen und Plattform

environment kommt aus der Umgebungsvariable LYRELOG_ENVIRONMENT, sonst production. platform ist python. Beides kannst du in init setzen:

lyrelog.init(api_key=..., environment="staging", platform="worker")

Jeder Name funktioniert: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen. Anderer Text wird für dich normalisiert.

Einwilligung betrifft Apps, die auf dem Gerät einer Person laufen. Ein Server-SDK sendet, was es bekommt; eine Option für die Einwilligung gibt es nicht.

Schwärzen und Filtern

Ein Wert wird zu "[redacted]", in Attributen und im Payload, wenn sein Schlüsselname, kleingeschrieben und ohne -, _, . oder Leerzeichen, einer der folgenden ist oder auf einen davon endet: authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential, credentials, accesskey oder signature. X-Api-Key, csrf_token, Set-Cookie und user_token werden also geschwärzt, token_count und max_tokens nicht.

redact_keys=[...] ersetzt diese Liste durch deine (genauso abgeglichen), und redact_keys=[] schaltet das Schwärzen ab. Um die Standardliste zu behalten und einen Namen hinzuzufügen, übergib redact_keys=[*lyrelog.DEFAULT_REDACT_KEYS, "card_number"].

Um Events selbst zu ändern oder zu verwerfen, übergib before_send an init: eine Funktion, die jedes Event bekommt und es zurückgibt, geändert oder nicht, oder None, um es zu verwerfen.

def before_send(event):
    if event["message"] == "health_check":
        return None
    return event


lyrelog.init(api_key="lyr_srv_...", before_send=before_send)

Flush und Stopp

sent = lyrelog.flush()   # rarely needed: it sends every 5 s and at exit
lyrelog.shutdown()       # also runs at exit: one last attempt, up to 5 s

flush wartet, bis alles, was vor dem Aufruf geloggt wurde, gesendet ist, höchstens bis zu seinem timeout (standardmäßig 5 s), und gibt True zurück, wenn die Warteschlange leer ist, False, wenn noch Events warten (der Server hat mit Retry-After um Aufschub gebeten oder war nicht erreichbar) oder verloren gegangen sind. Jeder Request an den Server hat nach 15 s ein Timeout.

client.stats() (auf dem Client, den init zurückgibt) meldet queued, dropped (Warteschlange voll), delivered, rejected (Zeilen, die der Server abgelehnt hat), discarded (Batches, die nach einem 4xx- oder 3xx-Status verworfen wurden), filtered (von before_send verworfen), failed (Events, die sich nicht formen ließen oder deren before_send geworfen hat), reentrant (aus dem SDK selbst heraus geloggt, zum Beispiel aus einem Signal-Handler) und disabled (ein abgelehnter Schlüssel, kein Schlüssel oder ein ungültiger Endpoint).

In Entwicklung und Tests

Lass api_key leer: Der Client nimmt Events an, sendet nichts und warnt einmal auf dem Logger lyrelog.

lyrelog.init(api_key=os.environ.get("LYRELOG_KEY", ""))

Ohne init tun die Funktionen und Logger auf Modulebene nichts.

Verifizierte Events

Ein verifiziertes Event kann nicht von jemandem gesendet worden sein, der den öffentlichen Ingest-Schlüssel aus einer App oder einer Webseite kopiert hat. Was das beweist und was nicht, steht unter Verifizierte Events.

Sende mit einem Server-Schlüssel, lyr_srv_.... Jedes Event, das er sendet, ist verifiziert (verified_by ist server) und zählt nicht zum Tagesanteil einer Adresse. Ein Inhaber erstellt ihn auf der Seite API keys des Projekts unter Send events from a server, nach einer frischen Anmeldung (innerhalb von 10 Minuten), und er wird nur einmal angezeigt. Er ist geheim: Check ihn nicht ins Repository ein, sondern lies ihn aus der Umgebung oder dem Secret-Store des Servers.

import os

lyrelog.init(api_key=os.environ["LYRELOG_KEY"])  # lyr_srv_..., set in the server's environment

Zur Kontrolle öffnest du den Explorer: Wähl unter Filter erst Verified by und dann Server key (die anderen Werte sind App Attest und Not verified). Ein geöffnetes Event zeigt es unter Context in seiner Zeile Sender: Verified, server key oder Not verified, public key.

Events, die mit einem Ingest-Schlüssel, lyr_ing_..., oder einem Vollzugriffs-Schlüssel, lyr_adm_..., gesendet werden, kommen unverifiziert an: Jeder mit einem öffentlichen Schlüssel hätte dasselbe senden können, und sie zählen zum Tagesanteil. Ein verifiziertes Event beweist, wer es gesendet hat, nicht, dass sein Inhalt stimmt.

Unter Verifizierte Events steht, wer was verifiziert und wie der Tagesanteil funktioniert.

Konfiguration

OptionStandardBedeutung
endpointhttps://ingest.lyrelog.comDie Basis-URL; ein eingefügter Pfad /v1/... wird entfernt
api_keyerforderlichDer Server-Schlüssel des Projekts (lyr_srv_...) oder ein Ingest-Schlüssel. Leer: Es wird nichts gesendet
environmentLYRELOG_ENVIRONMENT, sonst productionJeder gültige Name
platformpythonapi, worker...
releasekeinerresource.app_version
app_idkeinerresource.app_id: der Name des Service
minimum_level"debug"Events darunter werden verworfen, bevor sie in die Warteschlange kommen
flush_interval5.0 sWie oft der Worker sendet
max_queue10_000Darüber hinaus fallen die ältesten weg
max_queue_bytes16 MiBDieselbe Grenze, in Bytes
redact_keysDEFAULT_REDACT_KEYSDie zu schwärzenden Schlüsselnamen; ersetzt die Standardliste
before_sendkeinerÄndert ein Event, oder gib None zurück, um es zu verwerfen
session_timeout30 minInaktivität, nach der eine neue Session beginnt. Nur bei lyrelog.Client, nicht bei init

Zustellung und Limits

BatchesBis zu 500 Events oder 512 KiB, gzip. Ein voller Batch geht sofort raus, sonst alle flush_interval. Ein Event über 1 MiB wird verworfen und gezählt.
Wiederholungen1 s, verdoppelt bis 5 min, mit Equal Jitter, unter Beachtung von Retry-After (höchstens eine Stunde); dieselben Bytes werden erneut gesendet. Jeder andere 4xx-Status verwirft den Batch; ein 3xx-Status verwirft ihn mit einer Warnung (Weiterleitungen werden nicht verfolgt). Ein abgelehnter Schlüssel (401, 403) stoppt das Senden bis zum Neustart des Prozesses und behält die Events im Speicher.
MonatskontingentWenn eine Free-Organisation die Events ihres Monats aufgebraucht hat, antwortet der Server mit 429. Die Events bleiben im Speicher und gehen raus, sobald der Server sie wieder annimmt, bis zu max_queue. Das SDK loggt eine Warnung auf dem Logger lyrelog mit der Nachricht des Servers und warnt erst wieder, nachdem ein Batch angenommen wurde.
ObergrenzenÜber max_queue hinaus fallen die ältesten weg, und eine Warnung lyrelog_events_dropped mit der Anzahl geht mit dem nächsten Batch raus.
Threads und ForksThread-sicher. Nach os.fork bekommt der Kindprozess eine neue Warteschlange, einen neuen Worker, eine neue Installation und eine neue Session.
Kontextos_name (platform.system()), os_version (platform.release()), device_model (platform.machine()), eine Installations-ID pro Prozess und eine Session-ID pro Prozess, die nach 30 Minuten ohne Event wechselt.
LimitsWerden vor dem Einreihen angewendet: Verschachtelte Objekte tiefer als 4 Ebenen werden zu einem JSON-String, Punkte in Attributnamen werden zu _, ein Payload über 64 KiB wird zu {"lyrelog_truncated": true, "bytes": N, "preview": "..."}, Tracebacks behalten ihre letzten 48 KiB.