Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

Python

Logs estruturados dos seus serviços Python, com um handler de logging. Só a biblioteca padrão.

Servidores, workers, scripts

O pacote lyrelog exige Python 3.11 ou mais recente e não tem dependências.

Prévia interna: este pacote ainda não foi publicado. Até lá, uv add lyrelog falha: não existe pacote no PyPI.

Instalação

uv add lyrelog

Primeiros passos

Uma vez, na inicialização. lyrelog.init inicia o cliente padrão (esvaziando a fila de um cliente anterior e substituindo-o) e o retorna; as funções do módulo usam esse cliente.

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",
)

Use uma chave de servidor, lyr_srv_..., da página API keys do projeto (Send events from a server). É um segredo: mantenha-a no ambiente do seu servidor, nunca num app ou numa página web. Os eventos dela são verificados, e o limite diário de um mesmo endereço de remetente não se aplica a eles. Uma chave de ingestão, lyr_ing_..., também funciona, mas os eventos dela não são verificados.

Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los a outro lugar. É a URL base (se você colar um caminho .../v1/events:batch, ele é removido) e precisa ser https://, ou http:// para localhost.

Uma api_key vazia cria um cliente que aceita eventos e não envia nada, então uma variável de ambiente faltando em desenvolvimento não derruba o app. Uma chave ausente ou um endpoint inválido são reportados uma vez, como um warning no logger lyrelog.

lyrelog.Client(endpoint, api_key, ...) é o mesmo sem o padrão no nível do módulo, para um segundo projeto ou para testes: todas as funções abaixo são métodos dele. lyrelog.get_client() retorna o cliente padrão, ou None antes de init.

Registrar eventos

Uma função por nível: 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})

Uma chamada de log nunca bloqueia e nunca lança exceção: qualquer coisa estranha que você passar (objetos, NaN, ciclos) vira algo válido. Depois de shutdown(), as chamadas de log não fazem nada.

Loggers para cada área

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

Um logger usa o cliente padrão que existir no momento da chamada, então você pode criá-lo no import, antes de init.

Usuários

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

Um servidor atende muitas pessoas ao mesmo tempo, então passe user_id= em cada chamada em vez de usar set_user.

O handler de logging

O jeito mais rápido é install_logging, que adiciona um LoggingHandler ao root logger (e, com uvicorn=True, o padrão, a uvicorn e uvicorn.error) e baixa o root logger para level se ele estiver acima, para que registros INFO passem. Chamá-lo de novo substitui o handler anterior, e uninstall_logging() o remove; uvicorn.access fica de fora (registre as requisições num middleware).

import logging
import lyrelog

lyrelog.install_logging(logging.INFO)

Para adicionar o handler você mesmo, lembre que o root logger para em WARNING por padrão: um handler configurado em INFO não recebe nada abaixo de WARNING até o root logger deixar passar.

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
Nome do logger (app.matches, uvicorn.error)category
DEBUG ... CRITICALOs mesmos; abaixo de DEBUG é trace, entre INFO e WARNING é notice
A mensagem formatadamessage; com argumentos, o template vai para attrs.msg_template, para agrupar
Campos de extra=attrs, exceto user_id (o usuário do evento) e payload (mantido como payload.data)
exc_infopayload.exception e attrs.error_type, attrs.error_message
Arquivo, linha, funçãopayload.source

O handler nunca repassa o logger do próprio SDK, então não entra em loop. Esse logger se chama lyrelog: para ver o que o SDK reporta sobre si mesmo (uma chave recusada, um endpoint errado, eventos descartados), dê a ele um handler, por exemplo logging.getLogger("lyrelog").setLevel(logging.DEBUG) com basicConfig. Para eventos que você quer ver em gráficos, prefira chamadas diretas com um nome estável: uma mensagem formatada é texto livre.

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),
            },
        )

O template da rota deixa os ids fora do atributo, então o painel consegue contar por rota. O middleware não captura exceções não tratadas por conta própria: o uvicorn registra cada uma com o traceback em uvicorn.error, e install_logging repassa esse registro com error_type, error_message e o traceback, então capturá-la aqui também a registraria duas vezes. Com gunicorn ou uvicorn --workers, cada processo worker tem o seu próprio envio.

Django

Inicie o cliente uma vez, em settings.py ou no seu AppConfig.ready(), e envie os registros de logging pela configuração LOGGING do 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},
    },
}

Um worker ou um script

Um job que roda para muitas pessoas define o usuário em cada evento e para o 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 e scripts curtos

O worker envia a cada 5 s e mais uma vez na saída (atexit). Uma função que fica congelada entre requisições (AWS Lambda, Cloud Functions) pode nunca chegar a nenhum dos dois: chame lyrelog.flush() antes de retornar, e confira o que ele retorna se precisar saber.

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

atexit não roda depois de os._exit(), nem quando o processo recebe SIGTERM sem handler. O Uvicorn e o gunicorn tratam SIGTERM e saem normalmente; no seu próprio processo de longa duração, pare o cliente num 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)

Exceções não capturadas

O SDK não instala um hook para exceções não capturadas. Para registrá-las, defina um você mesmo, para a thread principal e para as outras 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

Os frameworks capturam por conta própria as exceções dentro das requisições: para essas, use o middleware acima ou o logger do framework.

Exceções

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

Sem argumento, captura a exceção que está sendo tratada; passe uma para capturar outra. Registra exception no nível error com attrs.error_type e attrs.error_message (os mesmos em todos os SDKs), e o tipo, a mensagem e o traceback no payload. message= e level= mudam o nome e o nível do evento, e user_id= define o usuário. O capture_exception de um logger usa a categoria dele.

Ambientes e plataforma

environment vem da variável de ambiente LYRELOG_ENVIRONMENT; sem ela, é production. platform é python. Defina qualquer um dos dois em init:

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

Qualquer nome serve: letras minúsculas, dígitos, - e _, até 32. Outro texto é normalizado para você.

O consentimento é para apps que rodam no dispositivo de alguém. Um SDK de servidor envia o que recebe; não há opção de consentimento.

Ocultar e filtrar

Um valor vira "[redacted]", nos atributos e no payload, quando o nome da chave dele, em minúsculas e sem -, _, . ou espaços, é ou termina com um de authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential, credentials, accesskey ou signature. Assim, X-Api-Key, csrf_token, Set-Cookie e user_token são ocultados; token_count e max_tokens não.

redact_keys=[...] substitui essa lista pela sua (comparada da mesma forma), e redact_keys=[] desliga a ocultação. Para manter os padrões e adicionar um nome, passe redact_keys=[*lyrelog.DEFAULT_REDACT_KEYS, "card_number"].

Para alterar ou descartar eventos você mesmo, passe before_send para init: uma função que recebe cada evento e o retorna, alterado ou não, ou None para descartá-lo.

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


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

Esvaziar a fila e parar

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 até que tudo o que foi registrado antes da chamada tenha sido enviado, até o seu timeout (5 s por padrão), e retorna True se a fila esvaziou, ou False se ainda há eventos esperando (o servidor pediu para esperar com Retry-After, ou não foi possível alcançá-lo) ou se foram perdidos. Cada requisição ao servidor tem timeout de 15 s.

client.stats() (no cliente que init retorna) informa queued, dropped (fila cheia), delivered, rejected (linhas que o servidor recusou), discarded (lotes descartados depois de um 4xx ou 3xx), filtered (descartados por before_send), failed (eventos que não puderam ser montados, ou cujo before_send lançou exceção), reentrant (registrados de dentro do SDK, por exemplo num signal handler) e disabled (uma chave recusada, sem chave ou um endpoint inválido).

Em desenvolvimento e testes

Deixe api_key vazio: o cliente aceita eventos, não envia nada e avisa uma vez no logger lyrelog.

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

Sem init, as funções do módulo e os loggers não fazem nada.

Eventos verificados

Um evento verificado é um evento que não pode ter sido enviado por alguém que copiou a chave de ingestão pública de um app ou de uma página web. O que isso prova, e o que não prova, está em Eventos verificados.

Envie com uma chave de servidor, lyr_srv_.... Todo evento que ela envia é verificado (verified_by é server) e não conta para a cota diária de um endereço. Um proprietário a cria na página API keys do projeto, em Send events from a server, depois de ter entrado recentemente (nos últimos 10 minutos), e ela é mostrada uma única vez. É um segredo: mantenha-a fora do repositório e leia-a do ambiente do servidor ou do seu gerenciador de segredos.

import os

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

Para conferir, abra o explorer: em Filter, escolha Verified by e Server key (os outros valores são App Attest e Not verified). Um evento aberto mostra isso em Context, na linha Sender: Verified, server key ou Not verified, public key.

Eventos enviados com uma chave de ingestão, lyr_ing_..., ou com uma chave de acesso total, lyr_adm_..., chegam não verificados: qualquer pessoa com uma chave pública poderia ter enviado o mesmo, e eles contam para a cota diária. Um evento verificado prova quem o enviou, não que o que ele diz seja verdade.

Veja Eventos verificados para saber quem verifica o quê e como funciona a cota diária.

Configuração

OpçãoPadrãoSignificado
endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido
api_keyobrigatórioA chave de servidor do projeto (lyr_srv_...), ou uma chave de ingestão. Vazia: nada é enviado
environmentLYRELOG_ENVIRONMENT, senão productionQualquer nome válido
platformpythonapi, worker...
releasenenhumresource.app_version
app_idnenhumresource.app_id: o nome do serviço
minimum_level"debug"Eventos abaixo dele são descartados antes de entrar na fila
flush_interval5.0 sCom que frequência o worker envia
max_queue10_000Além disso, os mais antigos são descartados
max_queue_bytes16 MiBO mesmo limite, em bytes
redact_keysDEFAULT_REDACT_KEYSOs nomes de chave a ocultar; substitui os padrões
before_sendnenhumAltera um evento, ou retorna None para descartá-lo
session_timeout30 minTempo de inatividade que inicia uma nova sessão. Só em lyrelog.Client, não em init

Entrega e limites

LotesAté 500 eventos ou 512 KiB, gzip. Um lote cheio sai na hora; senão, a cada flush_interval. Um evento acima de 1 MiB é descartado e contado.
Novas tentativas1 s, dobrando até 5 min, com equal jitter, respeitando Retry-After (no máximo uma hora); os mesmos bytes são reenviados. Qualquer outro 4xx descarta o lote; um 3xx o descarta com um aviso (redirecionamentos não são seguidos). Uma chave recusada (401, 403) para os envios até o processo reiniciar e mantém os eventos em memória.
Cota mensalQuando uma organização Free já usou os eventos do mês, o servidor responde 429. Os eventos ficam em memória e saem quando o servidor voltar a aceitá-los, até max_queue. O SDK registra um warning no logger lyrelog com a mensagem do servidor, e só avisa de novo depois de um lote ter sido aceito.
Limites da filaAlém de max_queue, os mais antigos saem, e um aviso lyrelog_events_dropped com a contagem vai junto com o próximo lote.
Threads e forksThread-safe. Depois de os.fork, o processo filho recebe uma fila, um worker, uma instalação e uma sessão novos.
Contextoos_name (platform.system()), os_version (platform.release()), device_model (platform.machine()), um id de instalação por processo e um id de sessão por processo que muda depois de 30 minutos sem eventos.
LimitesAjustados antes de entrar na fila: objetos aninhados além de 4 níveis viram uma string JSON, pontos nos nomes de atributos viram _, um payload acima de 64 KiB vira {"lyrelog_truncated": true, "bytes": N, "preview": "..."}, tracebacks mantêm os últimos 48 KiB.