抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

Python

从你的 Python 服务发送结构化日志,自带 logging handler。只依赖标准库。

服务器、worker、脚本

lyrelog 包需要 Python 3.11 或更高版本,没有任何依赖。

内部预览:这个包尚未发布。在发布之前,uv add lyrelog 会失败,因为 PyPI 上还没有这个包。

安装

uv add lyrelog

开始使用

在启动时调用一次。lyrelog.init 会启动默认客户端(如果之前已有客户端,会先立即发送其队列中的事件,再替换它)并返回它;模块级函数都使用这个客户端。

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

使用服务器密钥 lyr_srv_...,在项目的 API keys 页面(Send events from a server)创建。它是机密:放在服务器的环境变量中,绝不能放进应用或网页。它发送的事件是已验证的,而且不受单个地址每日配额的限制。采集密钥 lyr_ing_... 也能用,但它发送的事件不是已验证的。

事件发往 https://ingest.lyrelog.com。只有要发到别处时才需要传 endpoint。它是基础 URL(粘贴的 .../v1/events:batch 路径会被去掉),必须是 https://,localhost 可以用 http://。

api_key 为空时,客户端照样接收事件,但什么都不发送,所以开发时少了某个环境变量也不会让应用崩溃。缺少密钥或 endpoint 无效时,会在 lyrelog logger 上输出一次警告。

lyrelog.Client(endpoint, api_key, ...) 与之相同,只是不设置模块级的默认客户端,适合第二个项目或测试:下面的每个函数都是它的方法。lyrelog.get_client() 返回默认客户端,在 init 之前返回 None。

记录事件

每个级别一个函数:trace、debug、info、notice、warning、error、critical,或者 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})

日志调用从不阻塞,也从不抛出异常:你传入的任何奇怪的东西(对象、NaN、循环引用)都会被转换成有效内容。调用 shutdown() 之后,日志调用不再起作用。

按分类划分的 logger

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

logger 在调用时才去找默认客户端,所以可以在 import 时、init 之前就创建它。

用户

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

服务器同时处理很多用户的请求,所以请在每次调用时传 user_id=,而不是用 set_user。

logging handler

最快的方法是 install_logging:它给根 logger 添加一个 LoggingHandler(uvicorn=True 时,也就是默认情况下,还会添加到 uvicorn 和 uvicorn.error),如果根 logger 的级别高于 level,还会把它降到这一级别,让 INFO 记录能通过。再次调用会替换之前的 handler,uninstall_logging() 会移除它;uvicorn.access 不包括在内(请改在中间件中记录请求)。

import logging
import lyrelog

lyrelog.install_logging(logging.INFO)

如果要自己添加 handler,记住根 logger 默认只放行 WARNING 及以上:一个设为 INFO 的 handler,在根 logger 放行之前,收不到任何低于 WARNING 的记录。

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
logger 名称(app.matches、uvicorn.error)category
DEBUG ... CRITICAL相同;低于 DEBUG 的是 trace,介于 INFO 和 WARNING 之间的是 notice
格式化后的消息message;带参数时,模板放进 attrs.msg_template,可用于分组
extra= 字段attrs,但 user_id(事件的用户)和 payload(保存为 payload.data)除外
exc_infopayload.exception 以及 attrs.error_type、attrs.error_message
文件、行号、函数payload.source

handler 从不转发 SDK 自己的 logger,所以不会形成循环。这个 logger 名为 lyrelog:想看 SDK 自身报告的问题(密钥被拒绝、endpoint 错误、事件被丢弃),给它加一个 handler,例如配合 basicConfig 使用 logging.getLogger("lyrelog").setLevel(logging.DEBUG)。对于想做成图表的事件,优先直接调用并使用固定的名称:格式化后的消息只是一段文字。

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

使用路由模板,属性里就不会出现 id,控制台才能按路由计数。中间件本身不捕获未处理的异常:uvicorn 会把每个异常连同 traceback 记录到 uvicorn.error,install_logging 会把这条记录连同 error_type、error_message 和 traceback 一起转发,所以如果在这里再捕获一次,就会记录两遍。使用 gunicorn 或 uvicorn --workers 时,每个 worker 进程都有自己的发送器。

Django

在 settings.py 或你的 AppConfig.ready() 中启动一次客户端,然后通过 Django 的 LOGGING 设置发送 logging 记录:

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

worker 或脚本

为许多用户执行的任务,要在每个事件上设置用户,并在结束前停止客户端:

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 和短脚本

后台线程每 5 秒发送一次,退出时(atexit)再发送一次。在两次请求之间会被冻结的函数(AWS Lambda、Cloud Functions)可能两者都等不到:请在返回前调用 lyrelog.flush(),如果需要知道结果,就检查它的返回值。

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

atexit 在 os._exit() 之后不会运行,进程收到 SIGTERM 而没有处理程序时也不会。Uvicorn 和 gunicorn 会处理 SIGTERM 并正常退出;在你自己的长期运行进程中,请在信号处理程序里停止客户端:

import signal
import sys

import lyrelog


def on_sigterm(signum, frame):
    lyrelog.shutdown(timeout=2)
    sys.exit(0)


signal.signal(signal.SIGTERM, on_sigterm)

未捕获的异常

SDK 不会为未捕获的异常安装 hook。要记录它们,请自己为主线程和其他线程设置:

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

框架会自己捕获请求中的异常:对于这些异常,请使用上面的中间件或框架的 logger。

异常

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

不带参数时,捕获当前正在处理的异常;传入一个异常则捕获那一个。它以 error 级别记录一条 exception,带有 attrs.error_type 和 attrs.error_message(所有 SDK 都一样),payload 中带有类型、消息和 traceback。message= 和 level= 修改事件的名称和级别,user_id= 设置它的用户。logger 的 capture_exception 使用该 logger 的分类。

环境和平台

environment 取自环境变量 LYRELOG_ENVIRONMENT,否则为 production。platform 为 python。两者都可以在 init 中设置:

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

名称不限:小写字母、数字、- 和 _,最多 32 个字符。其他文本会自动规范化。

用户同意针对的是运行在用户设备上的应用。服务器 SDK 收到什么就发送什么,没有同意选项。

脱敏和过滤

在属性和 payload 中,只要某个值的键名转成小写并去掉 -、_、. 和空格后,等于下列之一或以其结尾,这个值就会变成 "[redacted]":authorization、cookie、password、passwd、secret、token、apikey、privatekey、credential、credentials、accesskey 或 signature。所以 X-Api-Key、csrf_token、Set-Cookie 和 user_token 会被脱敏,token_count 和 max_tokens 不会。

redact_keys=[...] 用你的列表替换它(匹配方式相同),redact_keys=[] 关闭脱敏。想保留默认值再加一个,传入 redact_keys=[*lyrelog.DEFAULT_REDACT_KEYS, "card_number"]。

想自己修改或丢弃事件,给 init 传入 before_send:这个函数拿到每个事件,返回这个事件(改过或没改),或者返回 None 丢弃它。

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


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

立即发送(flush)和停止

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 会等待调用之前记录的所有事件发送完毕,最多等 timeout(默认 5 秒)。队列清空时返回 True;如果还有事件在等待(服务器用 Retry-After 要求等待,或者连不上服务器)或已经丢失,则返回 False。每个发往服务器的请求 15 秒后超时。

client.stats()(在 init 返回的客户端上调用)报告以下数值:queued、dropped(队列已满)、delivered、rejected(服务器拒收的行)、discarded(因 4xx 或 3xx 被丢弃的批次)、filtered(被 before_send 丢弃)、failed(无法整理成合法格式的事件,或 before_send 抛出了异常)、reentrant(在 SDK 内部记录的,例如在信号处理程序中)以及 disabled(密钥被拒绝、没有密钥或 endpoint 无效)。

开发和测试

把 api_key 留空:客户端接收事件,什么都不发送,并在 lyrelog logger 上警告一次。

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

没有调用 init 时,模块级函数和 logger 不起作用。

已验证事件

已验证事件是指不可能由从应用或网页中复制了公开采集密钥的人发出的事件。它能证明什么、不能证明什么,请看已验证事件。

用服务器密钥 lyr_srv_... 发送。它发出的每个事件都是已验证的(verified_by 为 server),并且不计入单个地址的每日配额。服务器密钥由所有者在项目的 API keys 页面,通过 Send events from a server 创建,需要近期登录过(10 分钟以内),而且只显示一次。它是机密:不要放进代码仓库,从服务器的环境变量或机密存储中读取。

import os

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

要检查,打开 explorer:在 Filter 中选择 Verified by 和 Server key(另外两个值是 App Attest 和 Not verified)。打开一个事件,在 Context 下的 Sender 一行会显示:Verified, server key 或 Not verified, public key。

用采集密钥 lyr_ing_... 或完全访问密钥 lyr_adm_... 发送的事件到达时是未验证的:任何持有公开密钥的人都可能发出同样的事件,而且这些事件计入每日配额。已验证事件证明的是谁发送了它,而不是它的内容属实。

谁验证什么,以及每日配额,请看已验证事件。

配置

选项默认值说明
endpointhttps://ingest.lyrelog.com基础 URL;粘贴的 /v1/... 路径会被去掉
api_key必填项目的服务器密钥(lyr_srv_...)或采集密钥。为空:什么都不发送
environmentLYRELOG_ENVIRONMENT,否则为 production任何有效名称
platformpythonapi、worker……
release无resource.app_version
app_id无resource.app_id:服务名称
minimum_level"debug"低于这个级别的事件在入队前就被丢弃
flush_interval5.0 秒后台线程多久发送一次
max_queue10_000超出后丢弃最旧的
max_queue_bytes16 MiB同一个上限,按字节计
redact_keysDEFAULT_REDACT_KEYS要脱敏的键名;会替换默认列表
before_send无修改事件,或返回 None 丢弃它
session_timeout30 分钟空闲多久后开始新会话。只在 lyrelog.Client 上可用,init 不支持

发送和限制

批次最多 500 个事件或 512 KiB,gzip 压缩。批次满了立即发送,否则每隔 flush_interval 发送一次。超过 1 MiB 的事件会被丢弃并计数。
重试从 1 秒开始翻倍,最长 5 分钟,带等量抖动(equal jitter),遵守 Retry-After(最多一小时);重发的是相同的字节。其他任何 4xx 都会丢弃该批次;3xx 会丢弃该批次并发出警告(不跟随重定向)。密钥被拒绝(401、403)时停止发送,直到进程重启,事件保留在内存中。
每月配额Free 组织用完当月事件配额后,服务器返回 429。事件留在内存中,等服务器重新接收时再发出,最多保留 max_queue 个。SDK 会在 lyrelog logger 上输出一次带服务器消息的警告,之后只有在有批次被接收后才会再次警告。
上限超过 max_queue 后丢弃最旧的事件,并随下一个批次发出一条带数量的 lyrelog_events_dropped 警告。
线程和 fork线程安全。os.fork 之后,子进程会得到全新的队列、后台线程、安装和会话。
上下文os_name(platform.system())、os_version(platform.release())、device_model(platform.machine()),每个进程一个安装 id,以及每个进程一个会话 id,30 分钟没有事件后更换。
限制入队前裁剪:嵌套超过 4 层的对象变成 JSON 字符串,属性名中的点变成 _,超过 64 KiB 的 payload 变成 {"lyrelog_truncated": true, "bytes": N, "preview": "..."},traceback 保留最后 48 KiB。