Python
Strukturierte Logs aus deinen Python-Services, mit einem logging-Handler. Nur die Standardbibliothek.
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 lyrelogStarten
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 onlyEin 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 payloadlogging | Lyrelog |
|---|---|
Name des Loggers (app.matches, uvicorn.error) | category |
DEBUG ... CRITICAL | Dieselben; unter DEBUG ist trace, zwischen INFO und WARNING ist notice |
| Die formatierte Nachricht | message; 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_info | payload.exception und attrs.error_type, attrs.error_message |
| Datei, Zeile, Funktion | payload.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 sServerless 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_threadFrameworks 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
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 sflush 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 environmentZur 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
| Option | Standard | Bedeutung |
|---|---|---|
endpoint | https://ingest.lyrelog.com | Die Basis-URL; ein eingefügter Pfad /v1/... wird entfernt |
api_key | erforderlich | Der Server-Schlüssel des Projekts (lyr_srv_...) oder ein Ingest-Schlüssel. Leer: Es wird nichts gesendet |
environment | LYRELOG_ENVIRONMENT, sonst production | Jeder gültige Name |
platform | python | api, worker... |
release | keiner | resource.app_version |
app_id | keiner | resource.app_id: der Name des Service |
minimum_level | "debug" | Events darunter werden verworfen, bevor sie in die Warteschlange kommen |
flush_interval | 5.0 s | Wie oft der Worker sendet |
max_queue | 10_000 | Darüber hinaus fallen die ältesten weg |
max_queue_bytes | 16 MiB | Dieselbe Grenze, in Bytes |
redact_keys | DEFAULT_REDACT_KEYS | Die zu schwärzenden Schlüsselnamen; ersetzt die Standardliste |
before_send | keiner | Ändert ein Event, oder gib None zurück, um es zu verwerfen |
session_timeout | 30 min | Inaktivität, nach der eine neue Session beginnt. Nur bei lyrelog.Client, nicht bei init |
Zustellung und Limits
| Batches | Bis 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. |
| Wiederholungen | 1 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. |
| Monatskontingent | Wenn 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 Forks | Thread-sicher. Nach os.fork bekommt der Kindprozess eine neue Warteschlange, einen neuen Worker, eine neue Installation und eine neue Session. |
| Kontext | os_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. |
| Limits | Werden 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. |