アーリーアクセス招待制です。SDK はまだ公開されていません。招待をリクエスト
本文へスキップ
ドキュメント

Python

Python サービスから構造化ログを送ります。logging のハンドラー付き。標準ライブラリのみ。

サーバー、ワーカー、スクリプト

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

プロジェクトの API keys ページ(Send events from a server)で作成したサーバーキー lyr_srv_... を使ってください。これはシークレットです。サーバーの環境変数に置き、アプリや Web ページには決して含めないでください。そのイベントは検証済みになり、1 アドレスあたりの 1 日の割り当て(月間イベント数の一部)も適用されません。インジェストキー lyr_ing_... でも動きますが、そのイベントは検証済みになりません。

イベントは https://ingest.lyrelog.com に送られます。別の送信先に送る場合にのみ endpoint を指定してください。指定するのはベース URL で(.../v1/events:batch のパスを貼り付けても取り除かれます)、https:// でなければなりません。localhost の場合は http:// も使えます。

api_key が空の場合、クライアントはイベントを受け付けますが何も送信しません。そのため、開発中に環境変数が設定されていなくてもアプリはクラッシュしません。キーがない場合や endpoint が不正な場合は、lyrelog ロガーに警告として一度だけ報告されます。

lyrelog.Client(endpoint, api_key, ...) は、モジュールレベルのデフォルトを使わない以外は同じものです。2 つ目のプロジェクトやテストで使います。以下の関数はすべて、このクライアントのメソッドです。lyrelog.get_client() はデフォルトのクライアントを返し、init の前は None を返します。

イベントを記録する

レベルごとに 1 つの関数があります: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() の後は、ログの呼び出しは何もしません。

領域ごとのロガー

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

ロガーは呼び出し時点のデフォルトのクライアントを使うので、init より前の import 時に作成しておけます。

ユーザー

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

サーバーは多くのユーザーを同時に扱うので、set_user ではなく、呼び出しごとに user_id= を渡してください。

logging のハンドラー

いちばん手軽なのは install_logging です。ルートロガーに LoggingHandler を 1 つ追加し(デフォルトの uvicorn=True では uvicorn と uvicorn.error にも追加します)、ルートロガーのレベルが level より高い場合はそこまで下げるので、INFO のレコードも通るようになります。もう一度呼ぶと前のハンドラーを置き換え、uninstall_logging() で取り除けます。uvicorn.access は対象外です(リクエストはミドルウェアで記録してください)。

import logging
import lyrelog

lyrelog.install_logging(logging.INFO)

ハンドラーを自分で追加する場合、ルートロガーはデフォルトで WARNING で止まることに注意してください。INFO に設定したハンドラーでも、ルートロガーが通すようにするまでは 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
ロガー名(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

ハンドラーは SDK 自身のロガーを転送しないので、ループすることはありません。そのロガーの名前は lyrelog です。SDK 自身が報告する内容(キーの拒否、endpoint の誤り、破棄されたイベント)を見るには、このロガーにハンドラーを付けてください。たとえば 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 がそれぞれをトレースバック付きで uvicorn.error に記録し、install_logging がそのレコードを error_type、error_message、トレースバックとともに転送するので、ここでも記録すると二重になってしまいます。gunicorn や uvicorn --workers では、ワーカープロセスごとに独立した送信処理が動きます。

Django

クライアントは settings.py か AppConfig.ready() で一度だけ開始し、logging のレコードは Django の 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},
    },
}

ワーカーやスクリプト

多くのユーザーを対象に動くジョブでは、イベントごとにユーザーを設定し、終了する前にクライアントを停止します。

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

サーバーレスと短いスクリプト

ワーカーは 5 秒ごとに送信し、終了時(atexit)にももう一度送信します。リクエストの合間に凍結される関数(AWS Lambda、Cloud Functions)では、どちらにも到達しないことがあります。return する前に 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 はキャッチされなかった例外のためのフックをインストールしません。記録するには、メインスレッドと他のスレッドの両方に自分でフックを設定してください。

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

フレームワークはリクエスト内の例外を自分でキャッチします。それらには、上のミドルウェアかフレームワークのロガーを使ってください。

例外

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

引数なしで呼ぶと、処理中の例外を記録します。別の例外を記録するには、それを渡します。error レベルで exception を記録し、attrs.error_type と attrs.error_message(どの SDK でも同じ)を付け、payload には型、メッセージ、トレースバックを入れます。message= と level= でイベントの名前とレベルを変えられ、user_id= でユーザーを設定できます。ロガーの capture_exception は、そのロガーの category を使います。

環境とプラットフォーム

environment は環境変数 LYRELOG_ENVIRONMENT から取得し、なければ production です。platform は python です。どちらも init で設定できます。

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

名前は自由です。英小文字、数字、-、_ を使い、32 文字までです。それ以外の文字列は自動的に正規化されます。

同意は、誰かのデバイス上で動くアプリのためのものです。サーバー SDK は渡されたものをそのまま送ります。同意のオプションはありません。

マスキングとフィルタリング

属性と payload の中で、キー名を小文字にして -、_、.、空白を除いたものが authorization、cookie、password、passwd、secret、token、apikey、privatekey、credential、credentials、accesskey、signature のいずれかと一致するか、それで終わる場合、その値は "[redacted]" になります。つまり X-Api-Key、csrf_token、Set-Cookie、user_token はマスクされますが、token_count と max_tokens はマスクされません。

redact_keys=[...] はこのリストを独自のものに置き換え(照合方法は同じです)、redact_keys=[] でマスキングは無効になります。デフォルトを残したまま 1 つ追加するには、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)

フラッシュと停止

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 ロガーに一度だけ警告します。

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

init を呼ばなければ、モジュールレベルの関数とロガーは何もしません。

検証済みイベント

検証済みイベント(verified event)とは、アプリや Web ページから公開のインジェストキーをコピーした第三者には送れないイベントのことです。それが何を証明し、何を証明しないかは検証済みイベントを参照してください。

サーバーキー lyr_srv_... で送信します。このキーで送られるイベントはすべて検証済み(verified_by が server)になり、1 アドレスあたりの 1 日の割り当ても消費しません。サーバーキーは、オーナーが最近のサインイン(10 分以内)の後、プロジェクトの API keys ページの Send events from a server で作成します。キーは一度しか表示されません。これはシークレットです。リポジトリには含めず、サーバーの環境変数やシークレットストアから読み込んでください。

import os

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

確認するにはエクスプローラーを開き、Filter で Verified by と Server key を選びます(他の値は App Attest と Not verified です)。開いたイベントでは、Context の Sender の行に Verified, server key または Not verified, public key と表示されます。

インジェストキー lyr_ing_... やフルアクセスキー lyr_adm_... で送られたイベントは、検証されずに届き、1 日の割り当ても消費します。公開キーを持っている人なら誰でも同じものを送れたはずだからです。検証済みイベントが証明するのは誰が送ったかであり、その内容が正しいことではありません。

誰が何を検証するのか、そして 1 日の割り当てについては、検証済みイベントを参照してください。

設定

オプションデフォルト意味
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 分新しいセッションが始まるまでの無操作時間。init ではなく lyrelog.Client でのみ指定できます

配信と制限

バッチ最大 500 件または 512 KiB、gzip。いっぱいになったバッチはすぐに送られ、それ以外は flush_interval ごとに送られます。1 MiB を超えるイベントは破棄され、件数が記録されます。
リトライイコールジッター付きで 1 秒から倍々で最大 5 分、Retry-After を守ります(最大 1 時間)。同じバイト列を再送します。それ以外の 4xx ではバッチを破棄します。3xx では警告とともに破棄します(リダイレクトはたどりません)。キーが拒否された場合(401、403)は、プロセスが再起動するまで送信を止め、イベントはメモリに保持します。
月間クォータFree の組織が今月のイベント数を使い切ると、サーバーは 429 を返します。イベントはメモリに残り、サーバーが再び受け付けるようになった時点で、max_queue まで送信されます。SDK はサーバーのメッセージとともに lyrelog ロガーに警告を一度出し、その後はバッチが受け付けられた後にのみ再び警告します。
上限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": "..."} になり、トレースバックは末尾の 48 KiB が残ります。