Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

Python

Logs estructurados desde tus servicios Python, con un handler de logging. Solo la biblioteca estándar.

Servidores, workers, scripts

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 lyrelog

Primeros 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 only

Un 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 payload
loggingLyrelog
Nombre del logger (app.matches, uvicorn.error)category
DEBUG ... CRITICALLo mismo; por debajo de DEBUG es trace, entre INFO y WARNING es notice
El mensaje formateadomessage; 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_infopayload.exception y attrs.error_type, attrs.error_message
Archivo, línea, funciónpayload.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 s

Serverless 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_thread

Los 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.

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 s

flush 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 environment

Para 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ónPredeterminadoSignificado
endpointhttps://ingest.lyrelog.comLa URL base; si pegas una ruta /v1/..., se quita
api_keyobligatoriaLa clave de servidor del proyecto (lyr_srv_...) o una clave de ingesta. Vacía: no se envía nada
environmentLYRELOG_ENVIRONMENT o, si no, productionCualquier nombre válido
platformpythonapi, worker...
releaseningunoresource.app_version
app_idningunoresource.app_id: el nombre del servicio
minimum_level"debug"Los eventos por debajo se descartan antes de entrar en la cola
flush_interval5.0 sCada cuánto envía el worker
max_queue10_000Por encima, se descartan los más antiguos
max_queue_bytes16 MiBEl mismo tope, en bytes
redact_keysDEFAULT_REDACT_KEYSLos nombres de clave que se ocultan; sustituye a los predeterminados
before_sendningunoModifica un evento, o devuelve None para descartarlo
session_timeout30 minTiempo de inactividad tras el que empieza una sesión nueva. Solo en lyrelog.Client, no en init

Entrega y límites

LotesHasta 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.
ReintentosDe 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 mensualCuando 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.
TopesPor 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 forksThread-safe. Tras os.fork, el proceso hijo recibe una cola, un worker, una instalación y una sesión nuevos.
Contextoos_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ímitesSe 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.