encore-go-logging

Encore.go の構造化ロギング

構造化フィールドやトレース連携が必要なアプリケーションイベントには encore.dev/rlog を使用します。アプリケーションで確立されているフィールド名やイベントの慣習がこのガイドラインと整合している場合は、それらを維持してください。

記録する内容の決定

Encore がインフラストラクチャの操作から推測できない情報については、ログを追加します。

• ビジネス上の状態遷移
• 意思決定と、それを決定づけた入力
• リトライ、フォールバック、縮退運転
• リトライ、復旧、中断のいずれかを決定する境界での失敗
• ドメインコンテキストを必要とする外部システムとのやり取り
• セキュリティに関連する操作または管理操作

Encore はすでに API リクエスト、データベースクエリ、サービス呼び出し、キャッシュ操作、Pub/Sub アクティビティをトレースします。request started、querying database、request completed といったログでその実行を説明しないでください。

集計の件数とレベルにはメトリクスを使用します。呼び出しの流れとタイミングにはトレースを使用します。個々のイベントを調査するために必要なコンテキストにはログを使用します。

構造化ログの出力

メッセージを固定し、その後に文字列のキーと値を交互に渡します。

import "encore.dev/rlog"

rlog.Info("order rejected",
	"event", "order.rejected",
	"order_id", orderID,
	"product_id", productID,
	"reason", "insufficient_inventory",
	"requested_quantity", requestedQuantity,
	"available_quantity", availableQuantity,
)

メッセージに識別子を埋め込むことは避けてください。固定されたメッセージはグループ化でき、フィールドは検索可能なままです。

ダッシュボード、アラート、自動化で使用されるイベントには、固定の event フィールドを含めます。payment.authorized や subscription.cancelled のように <domain>.<past-tense-event> を推奨します。診断ログにはイベント名は必要ありません。

各フィールド名と型はイベント間で一貫させてください。整形された文章ではなく、明示的な単位を持つ数値や列挙型のような値を推奨します。

rlog.Info("payment authorized",
	"event", "payment.authorized",
	"amount_minor_units", 14900,
	"currency", "SEK",
)

Encore のランタイムフィールドは snake_case を使用します。encore_ で始まるフィールド名は予約済みです。rlog はそれらを x_ プレフィックスに書き換えます。

レベルの選択

Encore.go は Error、Warn、Info、Debug を提供します。rlog を通じて Trace 関数は公開されていません。

• Error: 予期しない失敗により操作が完了できなかった
• Warn: アプリケーションが復旧した、または縮退した状態で継続した
• Info: 意味のある、比較的低頻度のビジネスイベント
• Debug: 通常の運用には不要な診断の詳細

検証失敗、リソースの欠如、拒否されたログイン、拒否された支払いといった予期される結果は Error イベントではありません。ビジネス上の意味に基づいてレベルを選択してください。

デフォルトの最小レベルは trace であるため、4 つの rlog レベルのすべてが出力されます。頻繁に実行されるコードに Debug 呼び出しを追加する前に、encore.app で log_level を設定してください。

エラーは 1 回だけ記録

元の error をフィールド値として渡します。

if err := chargeCustomer(ctx, customerID, amount); err != nil {
	rlog.Error("payment authorization failed",
		"err", err,
		"customer_id", customerID,
		"amount_minor_units", amount,
		"currency", currency,
	)
	return err
}

error 値を渡すと、rlog がそのエラーシリアライゼーションを適用できます。先に err.Error() を呼び出すと、プレーンな文字列が渡されます。

返された失敗は、復旧の判断を所有し、その影響を説明するドメインコンテキストを持つ層でログに記録します。下位の層は、エラーを処理または抑制する場合、リトライする場合、不変条件の違反を検出する場合、または返されたエラーに含まれないコンテキストを保持している場合にのみログを記録すべきです。

共有コンテキストの追加

1 つのドメイン操作からの複数のイベントがフィールドを共有する場合は、rlog.With を使用します。

logger := rlog.With("import_id", importID, "tenant_id", tenantID)

logger.Info("user import completed", "succeeded_count", succeededCount, "failed_count", failedCount)
logger.Warn("user import row rejected", "row_number", rowNumber, "reason", "invalid_email")

Encore はすでにサービス、エンドポイント、トレース ID、認証されたユーザー ID をリクエストログに付加します。重複したコピーを追加しないでください。

機密データの保護

Encore はログフィールドを編集（レダクト）しません。認証情報、トークン、セッション識別子、Cookie、認可ヘッダー、シークレット設定、支払いの詳細、リクエストとレスポンスの完全な値を決してログに記録しないでください。

個人データよりも内部識別子を推奨します。保存すべきでない値の相関が必要な場合は、安定した非可逆なフィンガープリントを使用してください。

sensitive API アノテーションと encore:"sensitive" 構造体タグは、リクエストとレスポンスのペイロードをトレースから編集（レダクト）しますが、rlog に渡された値を編集（レダクト）するものではありません。

量の制御

バッチ処理や長時間実行される操作は、結果、件数、所要時間とともに要約してください。各項目ごとに 1 件のログを出力することは、それぞれの失敗を調査する必要がある場合を除いて避けてください。

大きな値からは、プロバイダーの応答、レコード、設定値、スライス、ドキュメント本文の全体ではなく、選択したメタデータのみをログに記録してください。プレビューのサイズを制限し、ログに記録する前に機密データが含まれていないか確認してください。

既存のアプリケーションをレビューする際は、まずループ、Pub/Sub サブスクライバー、ミドルウェア、頻繁に呼び出されるヘルパーを確認してください。こうした呼び出し箇所のごく一部が、ログ量の大部分を生み出していることがよくあります。

Encore.go ロギングガイドおよび rlog パッケージリファレンスを参照してください。