Python
Des logs structurés depuis vos services Python, avec un handler logging. Uniquement la bibliothèque standard.
Le package lyrelog nécessite Python 3.11 ou plus récent et n'a aucune dépendance.
Préversion interne : ce package n'est pas encore publié. D'ici là, uv add lyrelog échoue : il
n'existe aucun package sur PyPI.
Installation
uv add lyrelogDémarrage
Une seule fois, au démarrage. lyrelog.init démarre le client par défaut (en vidant et en
remplaçant le précédent, s'il y en a un) et le renvoie ; les fonctions du module l'utilisent.
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",
)Utilisez une clé serveur, lyr_srv_..., créée sur la page API keys du projet (Send events from a
server). C'est un secret : gardez-la dans l'environnement de votre serveur, jamais dans une app ou
une page web. Ses événements sont vérifiés, et le quota journalier par adresse
d'expéditeur ne s'applique pas. Une clé d'ingestion, lyr_ing_..., fonctionne aussi, mais ses
événements ne sont pas vérifiés.
Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer
ailleurs. C'est l'URL de base (un chemin .../v1/events:batch collé par erreur est retiré), et elle
doit être en https://, ou en http:// pour localhost.
Une api_key vide donne un client qui accepte les événements et n'envoie rien : une variable
d'environnement absente en développement ne fait donc pas planter l'app. Une clé manquante ou un
endpoint invalide est signalé une fois par un avertissement sur le logger lyrelog.
lyrelog.Client(endpoint, api_key, ...) fait la même chose sans le client par défaut du module,
pour un second projet ou pour les tests : chaque fonction ci-dessous en est une méthode.
lyrelog.get_client() renvoie le client par défaut, ou None avant init.
Enregistrer des événements
Une fonction par niveau : trace, debug, info, notice, warning, error, critical, ou
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})Un appel de log ne bloque jamais et ne lève jamais d'exception : tout ce que vous passez d'inhabituel
(objets, NaN, cycles) est transformé en quelque chose de valide. Après shutdown(), les appels de
log ne font plus rien.
Un logger par domaine
billing = lyrelog.logger("billing")
billing.warning("refund_denied", attrs={"order_id": order.id}, user_id=order.user_id)Un logger suit le client par défaut au moment de l'appel : vous pouvez donc le créer à l'import,
avant init.
Utilisateurs
lyrelog.set_user("u_123") # attached to every following event, process-wide
lyrelog.info("checkout_done", user_id=request_user) # for this event onlyUn serveur traite de nombreuses personnes à la fois : passez user_id= à chaque appel plutôt que d'utiliser
set_user.
Le handler logging
Le plus rapide est install_logging, qui ajoute un LoggingHandler au logger racine (et, avec
uvicorn=True, la valeur par défaut, à uvicorn et uvicorn.error) et abaisse le logger racine à
level s'il est au-dessus, pour que les enregistrements INFO passent. Le rappeler remplace le
handler précédent, et uninstall_logging() le retire ; uvicorn.access est laissé de côté
(enregistrez plutôt les requêtes dans un middleware).
import logging
import lyrelog
lyrelog.install_logging(logging.INFO)Si vous ajoutez le handler vous-même, n'oubliez pas que le logger racine s'arrête par défaut à
WARNING : un handler réglé sur INFO ne reçoit rien en dessous de WARNING tant que le logger
racine ne le laisse pas passer.
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 |
|---|---|
Nom du logger (app.matches, uvicorn.error) | category |
DEBUG ... CRITICAL | Les mêmes ; en dessous de DEBUG, c'est trace, entre INFO et WARNING, c'est notice |
| Le message formaté | message ; avec des arguments, le modèle va dans attrs.msg_template pour regrouper |
Champs extra= | attrs, sauf user_id (l'utilisateur de l'événement) et payload (conservé dans payload.data) |
exc_info | payload.exception et attrs.error_type, attrs.error_message |
| Fichier, ligne, fonction | payload.source |
Le handler ne transmet jamais le logger propre au SDK : il ne peut donc pas boucler. Ce logger
s'appelle lyrelog : pour voir ce que le SDK signale lui-même (une clé refusée, un mauvais
endpoint, des événements supprimés), donnez-lui un handler, par exemple
logging.getLogger("lyrelog").setLevel(logging.DEBUG) avec basicConfig. Pour les événements que
vous voulez voir en graphique, préférez des appels directs avec un nom stable : un message formaté,
c'est de la prose.
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),
},
)Le modèle de route garde les identifiants hors de l'attribut : le tableau de bord peut ainsi compter
par route. Le middleware ne capture pas lui-même les exceptions non gérées : uvicorn enregistre
chacune avec sa traceback sur uvicorn.error, et install_logging transmet cet enregistrement avec
error_type, error_message et la traceback. Les capturer ici aussi les enregistrerait donc deux
fois. Avec gunicorn ou uvicorn --workers, chaque processus worker a son propre thread d'envoi.
Django
Démarrez le client une seule fois, dans settings.py ou dans votre AppConfig.ready(), et envoyez
les enregistrements logging via le réglage LOGGING de Django :
# 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},
},
}Un worker ou un script
Une tâche qui s'exécute pour de nombreuses personnes définit l'utilisateur sur chaque événement, et arrête le client avant de se terminer :
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 et scripts courts
Le worker envoie toutes les 5 s, et une dernière fois à la sortie (atexit). Une fonction gelée
entre deux requêtes (AWS Lambda, Cloud Functions) peut n'atteindre ni l'un ni l'autre : appelez
lyrelog.flush() avant de répondre, et vérifiez sa valeur de retour si vous avez besoin de savoir.
def handler(event, context):
try:
return process(event)
finally:
lyrelog.flush(timeout=2)atexit ne s'exécute pas après os._exit(), ni quand le processus reçoit SIGTERM sans
gestionnaire. Uvicorn et gunicorn gèrent SIGTERM et se terminent normalement ; dans votre propre
processus de longue durée, arrêtez le client dans un gestionnaire :
import signal
import sys
import lyrelog
def on_sigterm(signum, frame):
lyrelog.shutdown(timeout=2)
sys.exit(0)
signal.signal(signal.SIGTERM, on_sigterm)Exceptions non interceptées
Le SDK n'installe pas de hook pour les exceptions non interceptées. Pour les enregistrer, définissez-en un vous-même, pour le thread principal et pour les autres 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_threadLes frameworks interceptent eux-mêmes les exceptions levées pendant les requêtes : pour celles-ci, utilisez le middleware ci-dessus ou le logger du framework.
Exceptions
try:
sync()
except Exception:
lyrelog.capture_exception(category="jobs")Sans argument, l'appel capture l'exception en cours de traitement ; passez-en une pour en capturer une
autre. Il enregistre exception au niveau error avec attrs.error_type et attrs.error_message
(les mêmes dans tous les SDK), et le type, le message et la traceback dans le payload. message= et
level= changent le nom et le niveau de l'événement, et user_id= définit son utilisateur. La
méthode capture_exception d'un logger utilise sa catégorie.
Environnements et plateforme
environment vient de la variable d'environnement LYRELOG_ENVIRONMENT, sinon production.
platform vaut python. Vous pouvez définir l'un ou l'autre dans init :
lyrelog.init(api_key=..., environment="staging", platform="worker")N'importe quel nom convient : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères. Tout
autre texte est normalisé pour vous.
Consentement
Le consentement concerne les apps qui tournent sur l'appareil de quelqu'un. Un SDK serveur envoie ce qu'on lui donne ; il n'y a pas d'option de consentement.
Masquage et filtrage
Une valeur devient "[redacted]", dans les attributs et le payload, quand le nom de sa clé, en
minuscules et sans -, _, . ni espaces, est ou se termine par l'un de authorization,
cookie, password, passwd, secret, token, apikey, privatekey, credential,
credentials, accesskey ou signature. Ainsi X-Api-Key, csrf_token, Set-Cookie et
user_token sont masqués ; token_count et max_tokens ne le sont pas.
redact_keys=[...] remplace cette liste par la vôtre (comparée de la même façon), et
redact_keys=[] désactive le masquage. Pour garder la liste par défaut et ajouter un nom, passez
redact_keys=[*lyrelog.DEFAULT_REDACT_KEYS, "card_number"].
Pour modifier ou supprimer vous-même des événements, passez before_send à init : une fonction
qui reçoit chaque événement et le renvoie, modifié ou non, ou renvoie None pour le supprimer.
def before_send(event):
if event["message"] == "health_check":
return None
return event
lyrelog.init(api_key="lyr_srv_...", before_send=before_send)Vider la file et arrêter
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 attend que tout ce qui a été enregistré avant l'appel soit envoyé, dans la limite de son
timeout (5 s par défaut), et renvoie True si la file s'est vidée, False si des événements
attendent encore (le serveur a demandé d'attendre avec Retry-After, ou il était injoignable) ou
ont été perdus. Chaque requête au serveur expire au bout de 15 s.
client.stats() (sur le client que renvoie init) indique queued, dropped (file pleine),
delivered, rejected (lignes refusées par le serveur), discarded (lots supprimés après un 4xx
ou un 3xx), filtered (supprimés par before_send), failed (événements qui n'ont pas pu être
mis en forme, ou dont le before_send a levé une exception), reentrant (enregistrés depuis
l'intérieur du SDK, par exemple un gestionnaire de signal) et disabled (une clé refusée, pas de
clé ou un endpoint invalide).
En développement et dans les tests
Laissez api_key vide : le client accepte les événements, n'envoie rien et affiche un
avertissement une fois sur le logger lyrelog.
lyrelog.init(api_key=os.environ.get("LYRELOG_KEY", ""))Sans init, les fonctions du module et les loggers ne font rien.
Événements vérifiés
Un événement vérifié est un événement qui ne peut pas avoir été envoyé par quelqu'un qui aurait copié la clé d'ingestion publique depuis une app ou une page web. Ce que cela prouve, et ce que cela ne prouve pas, est expliqué dans Événements vérifiés.
Envoyez avec une clé serveur, lyr_srv_.... Chaque événement qu'elle envoie est vérifié
(verified_by vaut server) et ne compte pas dans le
quota journalier d'une adresse. Un
propriétaire la crée sur la page API keys du projet, Send events from a server, après
s'être connecté récemment (dans les 10 dernières minutes), et elle n'est affichée qu'une fois. C'est
un secret : gardez-la hors du dépôt et lisez-la depuis l'environnement ou le gestionnaire de
secrets du serveur.
import os
lyrelog.init(api_key=os.environ["LYRELOG_KEY"]) # lyr_srv_..., set in the server's environmentPour contrôler, ouvrez l'explorer : dans Filter, choisissez Verified by et Server key (les autres valeurs sont App Attest et Not verified). Un événement ouvert l'indique sous Context, dans sa ligne Sender : Verified, server key, ou Not verified, public key.
Les événements envoyés avec une clé d'ingestion, lyr_ing_..., ou une clé d'accès complet,
lyr_adm_..., arrivent non vérifiés : n'importe qui détenant une clé publique aurait pu envoyer les
mêmes, et ils comptent dans le quota journalier. Un événement vérifié prouve qui l'a envoyé, pas que
ce qu'il dit est vrai.
Voir Événements vérifiés pour savoir qui vérifie quoi et comment fonctionne le quota journalier.
Configuration
| Option | Par défaut | Signification |
|---|---|---|
endpoint | https://ingest.lyrelog.com | L'URL de base ; un chemin /v1/... collé est retiré |
api_key | obligatoire | La clé serveur du projet (lyr_srv_...), ou une clé d'ingestion. Vide : rien n'est envoyé |
environment | LYRELOG_ENVIRONMENT, sinon production | N'importe quel nom valide |
platform | python | api, worker... |
release | aucun | resource.app_version |
app_id | aucun | resource.app_id : le nom du service |
minimum_level | "debug" | Les événements en dessous sont supprimés avant la mise en file d'attente |
flush_interval | 5.0 s | La fréquence d'envoi du worker |
max_queue | 10_000 | Au-delà, les plus anciens sont supprimés |
max_queue_bytes | 16 MiB | La même limite, en octets |
redact_keys | DEFAULT_REDACT_KEYS | Les noms de clés à masquer ; remplace la liste par défaut |
before_send | aucun | Modifier un événement, ou renvoyer None pour le supprimer |
session_timeout | 30 min | La durée d'inactivité qui démarre une nouvelle session. Uniquement sur lyrelog.Client, pas sur init |
Envoi et limites
| Lots | Jusqu'à 500 événements ou 512 KiB, gzip. Un lot plein part aussitôt, sinon à chaque flush_interval. Un événement de plus de 1 MiB est supprimé et compté. |
| Nouvelles tentatives | Backoff avec equal jitter (1 s, doublé à chaque tentative jusqu'à 5 min), en respectant Retry-After (une heure au plus) ; les mêmes octets sont renvoyés. Tout autre code 4xx supprime le lot ; un 3xx le supprime avec un avertissement (les redirections ne sont pas suivies). Une clé refusée (401, 403) arrête l'envoi jusqu'au redémarrage du processus et garde les événements en mémoire. |
| Quota mensuel | Quand une organisation Free a utilisé les événements de son mois, le serveur répond 429. Les événements restent en mémoire et partent dès que le serveur les accepte de nouveau, dans la limite de max_queue. Le SDK écrit un seul avertissement sur le logger lyrelog avec le message du serveur, et n'en écrit un autre qu'après l'acceptation d'un lot. |
| Plafonds | Au-delà de max_queue, les plus anciens sont supprimés, et un avertissement lyrelog_events_dropped avec leur nombre part avec le lot suivant. |
| Threads et forks | Thread-safe. Après os.fork, l'enfant reçoit une file, un worker, une installation et une session neufs. |
| Contexte | os_name (platform.system()), os_version (platform.release()), device_model (platform.machine()), un identifiant d'installation par processus, et un identifiant de session par processus qui change après 30 minutes sans événement. |
| Limites | Tout est ajusté avant la mise en file d'attente : les objets imbriqués au-delà de 4 niveaux deviennent une chaîne JSON, les points dans les noms d'attributs deviennent _, un payload de plus de 64 KiB devient {"lyrelog_truncated": true, "bytes": N, "preview": "..."}, les tracebacks gardent leurs 48 derniers KiB. |