Python
Logs estruturados dos seus serviços Python, com um handler de logging. Só a biblioteca padrão.
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 lyrelogPrimeiros 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 onlyUm 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 payloadlogging | Lyrelog |
|---|---|
Nome do logger (app.matches, uvicorn.error) | category |
DEBUG ... CRITICAL | Os mesmos; abaixo de DEBUG é trace, entre INFO e WARNING é notice |
| A mensagem formatada | message; 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_info | payload.exception e attrs.error_type, attrs.error_message |
| Arquivo, linha, função | payload.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 sServerless 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_threadOs 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ê.
Consentimento
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 sflush 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 environmentPara 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ção | Padrão | Significado |
|---|---|---|
endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido |
api_key | obrigatório | A chave de servidor do projeto (lyr_srv_...), ou uma chave de ingestão. Vazia: nada é enviado |
environment | LYRELOG_ENVIRONMENT, senão production | Qualquer nome válido |
platform | python | api, worker... |
release | nenhum | resource.app_version |
app_id | nenhum | resource.app_id: o nome do serviço |
minimum_level | "debug" | Eventos abaixo dele são descartados antes de entrar na fila |
flush_interval | 5.0 s | Com que frequência o worker envia |
max_queue | 10_000 | Além disso, os mais antigos são descartados |
max_queue_bytes | 16 MiB | O mesmo limite, em bytes |
redact_keys | DEFAULT_REDACT_KEYS | Os nomes de chave a ocultar; substitui os padrões |
before_send | nenhum | Altera um evento, ou retorna None para descartá-lo |
session_timeout | 30 min | Tempo de inatividade que inicia uma nova sessão. Só em lyrelog.Client, não em init |
Entrega e limites
| Lotes | Até 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 tentativas | 1 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 mensal | Quando 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 fila | Alé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 forks | Thread-safe. Depois de os.fork, o processo filho recebe uma fila, um worker, uma instalação e uma sessão novos. |
| Contexto | os_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. |
| Limites | Ajustados 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. |