Go
Go サービスから構造化ログを送ります。log/slog のハンドラー付き。標準ライブラリのみ。
モジュールは go.lyrelog.com/lyrelog です。Go 1.24 以降で動作し、依存関係はありません。
社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは go get go.lyrelog.com/lyrelog は失敗します。リポジトリが非公開で、まだリリースもないためです。
インストール
go get go.lyrelog.com/lyrelogはじめる
import "go.lyrelog.com/lyrelog"
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...", // a server key, or read it from your own config
Platform: "api",
})
if err != nil {
log.Fatal(err) // only for a bad config: logging itself never fails
}
defer client.Close() // sends what is left (waits at most 5 s)プロジェクトの API keys ページ(Send events from a server)で作成したサーバーキー lyr_srv_... を使ってください。これはシークレットです。サーバーの環境変数に置き、アプリや Web ページには決して含めないでください。そのイベントは検証済みになり、1 アドレスあたりの 1 日の割り当て(月間イベント数の一部)も適用されません。インジェストキー lyr_ing_... でも動きますが、そのイベントは検証済みになりません。
必須なのは APIKey だけです。指定しないと、New はエラーと nil のクライアントを返します。nil の *Client は何もしないので、クライアントを作る前でも(あるいは作らなくても)ログを記録するコードを書けます。Endpoint のデフォルトは https://ingest.lyrelog.com です。これはベース URL で、/v1/events:batch のパスを貼り付けても取り除かれます。
log.Fatal と os.Exit は defer された呼び出しを飛ばすので、その後に defer client.Close() が実行されることはありません。main では、処理を行う関数から終了コードを返すようにしてください。
func main() { os.Exit(run()) }
func run() int {
client, err := lyrelog.New(lyrelog.Config{APIKey: os.Getenv("LYRELOG_KEY")})
if err != nil {
fmt.Fprintln(os.Stderr, err) // client is nil and does nothing: carry on without it
}
defer client.Close() // runs before os.Exit
// ...
return 0
}サーバーレス関数(AWS Lambda)では、ハンドラーが return する前に client.Flush(ctx) を呼んでください。ランタイムが次の送信より前にプロセスを凍結することがあります。
イベントを記録する
レベルごとに 1 つのメソッドがあります:Trace、Debug、Info、Notice、Warning、Error、Critical、または Log(level, message, ...)。詳細はオプションで渡します:lyrelog.Category、lyrelog.Attrs、lyrelog.Payload、lyrelog.User。
client.Info("checkout_done", lyrelog.Attrs{"plan": "pro", "latency_ms": 412})
client.Error("payment_failed",
lyrelog.Category("billing"),
lyrelog.Attrs{"code": "card_declined"},
lyrelog.Payload(map[string]any{"response": body}),
)属性には文字列、数値、真偽値、nil、文字列のスライス、入れ子のマップ(4 階層まで)を使えます。ドットを含む名前は _ に書き換えられます。複数の Attrs オプションはマージされ、同じキーは後のものが優先されます。Payload は encoding/json でエンコードされます。すでに JSON になっているバイト列には json.RawMessage を渡してください(ただの []byte は base64 文字列として届きます)。
領域ごとのロガー
billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})ユーザー
client.SetUser("u_123") // attached to every following event
client.SetUser("") // clear itサーバーは多くのユーザーを同時に扱います。イベントごとに lyrelog.User(id) でユーザーを設定してください。そのイベントについては SetUser で設定したユーザーより優先されます。
slog のハンドラー
log/slog のレコードを Lyrelog に送ります。
logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")- レコードのメッセージがイベントのメッセージに、レコードの時刻がイベントの時刻になります。属性とグループは入れ子の属性になります。
- トップレベルの
categoryという文字列属性で領域を設定できます(属性としては送られません)。ない場合はハンドラーのCategoryが使われます。 - レベル:
Debug-4以下はtrace、Debugはdebug、Infoはinfo、InfoとWarnの間はnotice、Warnはwarning、Errorはerror、Error+4以上はcriticalです。 SlogOptions.Levelはクライアントの最小レベルに加えてさらに最小レベルを設けます。AddSourceは、呼び出し元の関数、ファイル、行を含むsource属性を追加します。go build -trimpathでビルドすると、ファイルにはビルドマシンのディレクトリではなくモジュールのパスが入ります。
ターミナルへの出力も続けたい場合は、各レコードを両方のハンドラーに送ってください。Go 1.26 以降では slog.NewMultiHandler でできます。
logger := slog.New(slog.NewMultiHandler(
slog.NewTextHandler(os.Stderr, nil),
lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)net/http のミドルウェア
組み込みのミドルウェアはありません。次のミドルウェアは、すべてのリクエストを http 領域の http_request_served として記録します。レベルは info、4xx では warning、5xx では error です。パスではなくルートのパターンを使うので、ID によってカーディナリティが爆発することはありません。
func logRequests(client *lyrelog.Client, next http.Handler) http.Handler {
httpLog := client.Logger("http")
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(recorder, r)
level := lyrelog.LevelInfo
switch {
case recorder.status >= 500:
level = lyrelog.LevelError
case recorder.status >= 400:
level = lyrelog.LevelWarning
}
httpLog.Log(level, "http_request_served", lyrelog.Attrs{
"method": r.Method,
"route": r.Pattern, // set by http.ServeMux (Go 1.23+), e.g. "GET /users/{id}"
"status": recorder.status,
"duration_ms": time.Since(start).Milliseconds(),
})
})
}
type statusRecorder struct {
http.ResponseWriter
status int
}
func (s *statusRecorder) WriteHeader(code int) {
s.status = code
s.ResponseWriter.WriteHeader(code)
}
// Unwrap lets http.ResponseController reach the original writer (Flush, deadlines).
func (s *statusRecorder) Unwrap() http.ResponseWriter { return s.ResponseWriter }
// http.ListenAndServe(":8080", logRequests(client, mux))どのルートにも一致しなかったリクエストでは、r.Pattern は空です。
エラー
if err := charge(ctx, order); err != nil {
client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}イベントは exception、レベルは error です。属性には error_type と error_message が入り、payload にはエラーのチェーン(ラップされた各エラー)とスタックが入ります。nil のエラーでは何も記録しません。Logger.CaptureError は同じことをロガーの category で行います。レベルは常に error です。別のレベルにしたい場合は、Log で自分でエラーを記録してください。
panic
SDK は panic を recover しません。net/http はハンドラーの panic を recover しますが、出力するだけなので、上のミドルウェアの外側にあるミドルウェアで記録してください。
func recoverPanics(client *lyrelog.Client, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
v := recover()
if v == nil {
return
}
if v == http.ErrAbortHandler {
panic(v)
}
err, ok := v.(error)
if !ok {
err = fmt.Errorf("panic: %v", v)
}
client.CaptureError(err, lyrelog.Category("http"),
lyrelog.Attrs{"handled": false, "mechanism": "panic", "route": r.Pattern})
http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
}()
next.ServeHTTP(w, r)
})
}
// http.ListenAndServe(":8080", recoverPanics(client, logRequests(client, mux)))payload のスタックは panic が recover された場所で取得されるので、panic を起こしたフレームもそのまま含まれます。自分で起動した goroutine の中の panic は、何かが送信される前にプログラムをクラッシュさせます。その goroutine の中で同じように recover してください。
環境とプラットフォーム
Environment のデフォルトは環境変数 LYRELOG_ENVIRONMENT(小文字に変換)で、なければ production です。Platform のデフォルトは go です。どちらも設定で指定できます。
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...",
Environment: "staging",
Platform: "worker",
})どちらも英小文字、数字、-、_ で 32 文字まで、先頭は英字か数字でなければなりません。Config.Environment や Config.Platform が不正な場合、New はエラーを返します。$LYRELOG_ENVIRONMENT が不正な場合は ErrorLog に報告され、production に置き換えられるので、デプロイ時のタイプミスでサービスが止まることはありません。Release のデフォルトはビルド情報にあるメインモジュールのバージョン、AppID のデフォルトはメインモジュールのパスです。
同意
同意は、誰かのデバイス上で動くアプリのためのものです。サーバー SDK は渡されたものをそのまま送ります。
フラッシュと停止
err := client.Flush(ctx) // send what's queued now
client.Close() // flush (up to CloseTimeout) and stopFlush は呼び出し前にキューに入ったものをすべて送信し、その完了か ctx の終了まで待ちます。戻り値は次のとおりです。
- すべてサーバーに届いた場合は
nil。 - 先にコンテキストが終了した場合は
ctx.Err()。 401または403の後はErrUnauthorized(クライアントはプロセスが再起動するまで送信を止め、キューは保持します)。- バッチが拒否されて破棄されたことを示すエラー(残りは送信済みです)。
- 配信に失敗し、リトライされることを示すエラー(イベントは保持されます)。サーバーが求めた
Retry-Afterの期間中は、Flushは何も送信せずにすぐこのエラーを返します。 Closeの後はErrClosed。
Close は最後のフラッシュを最大 CloseTimeout まで待ち、同じ値を返します。その時点でまだ送信されていないイベントは破棄され、Stats().Dropped に数えられます。Close の後は、ログの呼び出しは何もしません。
client.Stats() は次の値を返します:Queued(待機中。リトライ中のバッチも含む)、Sent(サーバーが受け付けたもの)、Rejected(サーバーが拒否した行。再送されません)、Dropped(クライアントが破棄したもの:キューのオーバーフロー、拒否されたバッチ、Close 時の残り)。
開発時とテスト
APIKey がないと、New はエラーと nil のクライアントを返し、nil のクライアントは何もしません。上の run の例のように、テストでもキーのないノート PC でも同じコードが動きます。nil のクライアントの上に作った slog のハンドラーは、すべてのレコードを破棄します。
テストで何が記録されるかを確認するには、リクエストを記録する Transport を持つ HTTPClient を渡すか、Endpoint を httptest.Server に向けてください(ループバックアドレスでは平文の http:// を使えます)。
検証済みイベント
検証済みイベント(verified event)とは、アプリや Web ページから公開のインジェストキーをコピーした第三者には送れないイベントのことです。それが何を証明し、何を証明しないかは検証済みイベントを参照してください。
サーバーキー lyr_srv_... で送信します。このキーで送られるイベントはすべて検証済み(verified_by が server)になり、1 アドレスあたりの 1 日の割り当ても消費しません。サーバーキーは、オーナーが最近のサインイン(10 分以内)の後、プロジェクトの API keys ページの Send events from a server で作成します。キーは一度しか表示されません。これはシークレットです。リポジトリには含めず、サーバーの環境変数やシークレットストアから読み込んでください。
client, err := lyrelog.New(lyrelog.Config{
APIKey: os.Getenv("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 日の割り当てについては、検証済みイベントを参照してください。
設定
| フィールド | デフォルト | 意味 |
|---|---|---|
Endpoint | https://ingest.lyrelog.com | ベース URL。/v1/... のパスを貼り付けても取り除かれます。平文の http:// は localhost のみ |
APIKey | 必須 | プロジェクトのサーバーキー(lyr_srv_...)、またはインジェストキー |
Environment | $LYRELOG_ENVIRONMENT、なければ production | 有効な任意の名前 |
Platform | go | api、worker など |
Release | モジュールのバージョン | resource.app_version として送られます |
AppID | モジュールのパス | resource.app_id として送られます |
MinimumLevel | LevelDebug | これより低いレベルのイベントはキューに入る前に破棄されます |
FlushInterval | 5 秒 | バックグラウンドの goroutine が送信する間隔 |
MaxQueue | 10,000 | これを超えると古いものから破棄され、Stats().Dropped に数えられます |
MaxQueueBytes | 16 MiB | 同じ上限をバイト数で指定 |
CloseTimeout | 5 秒 | Close が最後のフラッシュを待つ時間 |
HTTPClient | タイムアウト 30 秒 | バッチを送信するクライアント。独自のクライアントを使っても、リダイレクトは決してたどりません |
ErrorLog | stderr、一度だけ | SDK 自身の診断メッセージを受け取ります。各メッセージは lyrelog: で始まります。指定しない場合、stderr に出力されるのは最初のキー拒否またはバッチの破棄と、クォータの警告だけです。このクライアントに送り込むロガーには向けないでください |
配信と制限
- 1 つのバックグラウンド goroutine が、最大 500 件または 512 KiB のバッチを gzip で作ります。いっぱいになったバッチはすぐに送られます。並行して使っても安全です。
- フルジッター付きでリトライし(1 秒から倍々で最大 5 分)、
Retry-After(秒数または日時)を守り、同じバイト列を再送します。それ以外の 4xx ではバッチを破棄します。3xx では破棄して警告を記録します。 - 名前が
authorization、cookie、password、token、secret、apikeyなど共通のリストにあるもののいずれかと一致するか、それで終わるキーの値は、キューに入る前に"[redacted]"になります。属性と payload のどの深さでも(マップ、JSON 名による構造体、スライス、http.Header)、何かが切り詰められる前に適用されます。Config.RedactKeysはリストを置き換え、nil でない空のスライスで無効になります。追加するにはRedactKeys: append(lyrelog.DefaultRedactKeys(), "pin")とします。 - Free の組織が今月のイベント数を使い切ると、サーバーは
429を返します。イベントはメモリに残り、サーバーが再び受け付けるようになった時点で、MaxQueueまで送信されます。クライアントはErrorLog(または stderr)に警告を一度出し、バッチが受け付けられるまでそれ以上は何も出しません。 - コンテキスト:
os_nameはruntime.GOOS、app_buildはバイナリに VCS のリビジョンがあればそれ、インストール ID とセッション ID はプロセスごとです。 - 制限はキューに入る前に適用されます。属性は末端の値を 1 つずつ数え(入れ子の値も 1 つずつ数えます)、200 個を超えた分は破棄されて
lyrelog_dropped_attrsに数えられ、名前のドットは_になり(http.statusはhttp_status)、エラー、時刻、期間、Stringerは文字列に、構造体は JSON 形式に、NaN はnullになります。64 KiB を超える payload は、先頭 1 KiB を含む{"lyrelog_truncated": true, "bytes": N, "preview": "..."}になります。1 つのイベントの属性はエンコード後 256 KiB が上限で、512 KiB のバッチに収まらないイベントは破棄され、件数が記録されます。 Configや*Clientをfmtで出力しても、API キーは隠されます。