Python
Logs estructurados desde tus servicios Python, con un handler de logging. Solo la biblioteca estándar.
El paquete lyrelog necesita Python 3.11 o posterior y no tiene dependencias.
Vista previa interna: este paquete aún no está publicado. Hasta entonces, uv add lyrelog
falla: no hay ningún paquete en PyPI.
Instalación
uv add lyrelogPrimeros pasos
Una sola vez, al arrancar. lyrelog.init inicia el cliente predeterminado (enviando lo pendiente
de cualquier cliente anterior y sustituyéndolo) y lo devuelve; las funciones a nivel de módulo lo
usan.
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",
)Usa una clave de servidor, lyr_srv_..., de la página API keys del proyecto (Send events
from a server). Es un secreto: guárdala en el entorno de tu servidor, nunca en una app ni en una
página web. Sus eventos están verificados y no se les aplica la cuota diaria de
una dirección. Una clave de ingesta, lyr_ing_..., también funciona, pero sus eventos no
están verificados.
Los eventos van a https://ingest.lyrelog.com. Pasa endpoint solo para enviarlos a otro sitio.
Es la URL base (si pegas una ruta .../v1/events:batch, se quita) y debe ser https://, o
http:// para localhost.
Con un api_key vacío obtienes un cliente que acepta eventos y no envía nada, así que si falta
una variable de entorno en desarrollo la app no se cae. La falta de clave o un endpoint incorrecto
se notifican una vez como aviso en el logger lyrelog.
lyrelog.Client(endpoint, api_key, ...) es lo mismo sin el cliente predeterminado del módulo,
para un segundo proyecto o para tests: cada función de abajo es un método suyo.
lyrelog.get_client() devuelve el cliente predeterminado, o None antes de init.
Registrar eventos
Una función por nivel: trace, debug, info, notice, warning, error, critical, o
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})Una llamada de registro nunca bloquea ni lanza excepciones: cualquier cosa rara que pases (objetos, NaN,
ciclos) se convierte en algo válido. Después de shutdown(), las llamadas de registro no hacen nada.
Loggers por área
billing = lyrelog.logger("billing")
billing.warning("refund_denied", attrs={"order_id": order.id}, user_id=order.user_id)Un logger usa el cliente predeterminado que haya en el momento de la llamada, así que puedes
crearlo al importar, antes de init.
Usuarios
lyrelog.set_user("u_123") # attached to every following event, process-wide
lyrelog.info("checkout_done", user_id=request_user) # for this event onlyUn servidor atiende a muchas personas a la vez, así que pasa user_id= en cada llamada en lugar de usar
set_user.
El handler de logging
Lo más rápido es install_logging, que añade un LoggingHandler al logger raíz (y, con
uvicorn=True, el valor predeterminado, también a uvicorn y uvicorn.error) y baja el logger
raíz a level si está por encima, para que pasen los registros INFO. Si lo vuelves a llamar,
sustituye el handler anterior, y uninstall_logging() lo quita; uvicorn.access se queda fuera
(registra las peticiones en un middleware en su lugar).
import logging
import lyrelog
lyrelog.install_logging(logging.INFO)Si añades el handler tú mismo, recuerda que el logger raíz se queda en WARNING por defecto: un
handler configurado en INFO no recibe nada por debajo de WARNING hasta que el logger raíz lo
deja pasar.
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 |
|---|---|
Nombre del logger (app.matches, uvicorn.error) | category |
DEBUG ... CRITICAL | Lo mismo; por debajo de DEBUG es trace, entre INFO y WARNING es notice |
| El mensaje formateado | message; con argumentos, la plantilla va a attrs.msg_template para agrupar |
Campos de extra= | attrs, salvo user_id (el usuario del evento) y payload (se guarda como payload.data) |
exc_info | payload.exception y attrs.error_type, attrs.error_message |
| Archivo, línea, función | payload.source |
El handler nunca reenvía el logger del propio SDK, así que no puede entrar en bucle. Ese logger se
llama lyrelog: para ver lo que notifica el propio SDK (una clave rechazada, un endpoint
incorrecto, eventos descartados), dale un handler, por ejemplo
logging.getLogger("lyrelog").setLevel(logging.DEBUG) con basicConfig. Para los eventos que
quieras graficar, mejor llamadas directas con un nombre estable: un mensaje formateado es prosa.
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),
},
)La plantilla de la ruta deja los ids fuera del atributo, así que el panel puede contar por ruta.
El middleware no captura por sí mismo las excepciones no gestionadas: uvicorn registra cada una
con su traceback en uvicorn.error, e install_logging reenvía ese registro con error_type,
error_message y el traceback, así que capturarla también aquí la registraría dos veces. Con
gunicorn o uvicorn --workers, cada proceso worker tiene su propio emisor.
Django
Inicia el cliente una vez, en settings.py o en el AppConfig.ready(), y envía los registros de
logging mediante el ajuste 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 o un script
Una tarea que se ejecuta para muchas personas indica el usuario en cada evento y detiene el cliente antes de terminar:
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 y scripts cortos
El worker envía cada 5 s y una vez más al salir (atexit). Una función que se congela entre
peticiones (AWS Lambda, Cloud Functions) puede no llegar nunca a ninguno de los dos: llama a
lyrelog.flush() antes de devolver, y comprueba lo que devuelve si necesitas saberlo.
def handler(event, context):
try:
return process(event)
finally:
lyrelog.flush(timeout=2)atexit no se ejecuta después de os._exit(), ni cuando el proceso recibe SIGTERM sin un
handler. Uvicorn y gunicorn gestionan SIGTERM y salen con normalidad; en tu propio proceso de
larga duración, detén el cliente en un 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)Excepciones no capturadas
El SDK no instala ningún hook para las excepciones no capturadas. Para registrarlas, pon uno tú mismo, para el hilo principal y para los demás hilos:
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_threadLos frameworks capturan por su cuenta las excepciones dentro de las peticiones: para esas, usa el middleware de arriba o el logger del framework.
Excepciones
try:
sync()
except Exception:
lyrelog.capture_exception(category="jobs")Sin argumentos captura la excepción que se está gestionando; pasa una para capturar otra. Registra
exception con nivel error, con attrs.error_type y attrs.error_message (igual en todos los
SDK), y el tipo, el mensaje y el traceback en el payload. message= y level= cambian el nombre
y el nivel del evento, y user_id= define su usuario. El capture_exception de un logger usa su
categoría.
Entornos y plataforma
environment sale de la variable de entorno LYRELOG_ENVIRONMENT o, si no, es production.
platform es python. Puedes definir cualquiera de los dos en init:
lyrelog.init(api_key=..., environment="staging", platform="worker")Vale cualquier nombre: letras minúsculas, dígitos, - y _, hasta 32. Cualquier otro texto se
normaliza por ti.
Consentimiento
El consentimiento es para apps que se ejecutan en el dispositivo de alguien. Un SDK de servidor envía lo que recibe; no hay opción de consentimiento.
Ocultar datos sensibles y filtrar
Un valor se convierte en "[redacted]", en los atributos y en el payload, cuando el nombre de su
clave, en minúsculas y sin -, _, . ni espacios, es o termina en uno de estos:
authorization, cookie, password, passwd, secret, token, apikey, privatekey,
credential, credentials, accesskey o signature. Así, X-Api-Key, csrf_token,
Set-Cookie y user_token se ocultan; token_count y max_tokens, no.
redact_keys=[...] sustituye esa lista por la tuya (comparada de la misma forma), y
redact_keys=[] desactiva la ocultación. Para conservar los predeterminados y añadir uno, pasa
redact_keys=[*lyrelog.DEFAULT_REDACT_KEYS, "card_number"].
Para modificar o descartar eventos tú mismo, pasa before_send a init: una función que recibe
cada evento y lo devuelve, cambiado o no, o devuelve None para descartarlo.
def before_send(event):
if event["message"] == "health_check":
return None
return event
lyrelog.init(api_key="lyr_srv_...", before_send=before_send)Vaciar la cola y detener
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 espera hasta que se haya enviado todo lo registrado antes de la llamada, como mucho su
timeout (5 s por defecto), y devuelve True si la cola se vació y False si quedan eventos
esperando (el servidor pidió esperar con Retry-After, o no se pudo contactar con él) o se
perdieron. Cada petición al servidor tiene un timeout de 15 s.
client.stats() (en el cliente que devuelve init) informa de queued, dropped (cola llena),
delivered, rejected (líneas que el servidor rechazó), discarded (lotes descartados tras un
4xx o un 3xx), filtered (descartados por before_send), failed (eventos a los que no se pudo
dar forma, o cuyo before_send lanzó una excepción), reentrant (registrados desde dentro del
SDK, por ejemplo desde un handler de señales) y disabled (una clave rechazada, sin clave o un
endpoint incorrecto).
En desarrollo y en tests
Deja api_key vacío: el cliente acepta eventos, no envía nada y avisa una vez en el logger
lyrelog.
lyrelog.init(api_key=os.environ.get("LYRELOG_KEY", ""))Sin init, las funciones a nivel de módulo y los loggers no hacen nada.
Eventos verificados
Un evento verificado es uno que no puede haber enviado alguien que haya copiado la clave de ingesta pública de una app o de una página web. Qué demuestra eso, y qué no, se explica en Eventos verificados.
Envía con una clave de servidor, lyr_srv_.... Todos los eventos que envía están verificados
(verified_by es server) y no cuentan para la
cuota diaria de una dirección. Un
propietario la crea en la página API keys del proyecto, Send events from a server, tras un
inicio de sesión reciente (en los últimos 10 minutos), y se muestra una sola vez. Es un secreto:
mantenla fuera del repositorio y léela del entorno del servidor o de su almacén de secretos.
import os
lyrelog.init(api_key=os.environ["LYRELOG_KEY"]) # lyr_srv_..., set in the server's environmentPara comprobarlo, abre el explorador: en Filter, elige Verified by y Server key (los otros valores son App Attest y Not verified). Un evento abierto lo indica en Context, en su línea Sender: Verified, server key o Not verified, public key.
Los eventos enviados con una clave de ingesta, lyr_ing_..., o con una clave de acceso total,
lyr_adm_..., llegan sin verificar: cualquiera que tenga una clave pública podría haber enviado
lo mismo, y cuentan para la cuota diaria. Un evento verificado demuestra quién lo envió, no que lo
que dice sea cierto.
Consulta Eventos verificados para saber quién verifica qué y cómo funciona la cuota diaria.
Configuración
| Opción | Predeterminado | Significado |
|---|---|---|
endpoint | https://ingest.lyrelog.com | La URL base; si pegas una ruta /v1/..., se quita |
api_key | obligatoria | La clave de servidor del proyecto (lyr_srv_...) o una clave de ingesta. Vacía: no se envía nada |
environment | LYRELOG_ENVIRONMENT o, si no, production | Cualquier nombre válido |
platform | python | api, worker... |
release | ninguno | resource.app_version |
app_id | ninguno | resource.app_id: el nombre del servicio |
minimum_level | "debug" | Los eventos por debajo se descartan antes de entrar en la cola |
flush_interval | 5.0 s | Cada cuánto envía el worker |
max_queue | 10_000 | Por encima, se descartan los más antiguos |
max_queue_bytes | 16 MiB | El mismo tope, en bytes |
redact_keys | DEFAULT_REDACT_KEYS | Los nombres de clave que se ocultan; sustituye a los predeterminados |
before_send | ninguno | Modifica un evento, o devuelve None para descartarlo |
session_timeout | 30 min | Tiempo de inactividad tras el que empieza una sesión nueva. Solo en lyrelog.Client, no en init |
Entrega y límites
| Lotes | Hasta 500 eventos o 512 KiB, gzip. Un lote lleno sale de inmediato; si no, cada flush_interval. Un evento de más de 1 MiB se descarta y se cuenta. |
| Reintentos | De 1 s, duplicándose hasta 5 min, con equal jitter, respetando Retry-After (como mucho una hora); se reenvían los mismos bytes. Cualquier otro 4xx descarta el lote; un 3xx lo descarta con un aviso (no se siguen redirecciones). Una clave rechazada (401, 403) detiene los envíos hasta que el proceso se reinicia y conserva los eventos en memoria. |
| Cuota mensual | Cuando una organización Free ha agotado los eventos de su mes, el servidor responde 429. Los eventos se quedan en memoria y salen en cuanto el servidor vuelve a aceptarlos, hasta max_queue. El SDK registra un aviso en el logger lyrelog con el mensaje del servidor, y solo vuelve a avisar después de que se haya aceptado algún lote. |
| Topes | Por encima de max_queue se van los más antiguos, y con el siguiente lote sale un aviso lyrelog_events_dropped con el recuento. |
| Hilos y forks | Thread-safe. Tras os.fork, el proceso hijo recibe una cola, un worker, una instalación y una sesión nuevos. |
| Contexto | os_name (platform.system()), os_version (platform.release()), device_model (platform.machine()), un id de instalación por proceso y un id de sesión por proceso que cambia tras 30 minutos sin eventos. |
| Límites | Se ajustan antes de entrar en la cola: los objetos anidados a más de 4 niveles se convierten en una cadena JSON, los puntos en los nombres de atributo se convierten en _, un payload de más de 64 KiB se convierte en {"lyrelog_truncated": true, "bytes": N, "preview": "..."} y los tracebacks conservan sus últimos 48 KiB. |