production-observability

本番環境の可観測性

すべてのメソッドではなく、ユーザーに見える操作と運用上の境界に計装を追加します。

基本設定

• Actuator と、デプロイ先のプラットフォームに合わせて選んだメトリクスレジストリを追加します。
• アプリケーションのメトリクスとトレースには Micrometer Observation を使用します。
• 選択したブリッジとともに Micrometer Tracing を使用し、ビジネスコード全体でトレース API を混在させないでください。
• プラットフォームで OpenTelemetry コレクターが標準化されている場合は、OTLP 経由でエクスポートします。
• 必要な Actuator エンドポイントだけを公開し、非公開のエンドポイントはすべて保護します。

オブザベーションの規約

• orders.create のように、安定した操作を名前にしてオブザベーションを作成します。
• メトリクスのタグは低カーディナリティに保ちます。例：メソッド、結果、リージョン、または値の範囲を限定したステータス。
• リクエスト ID、ユーザー ID、注文 ID、例外メッセージは、トレースまたはログにのみ記録します。
• @Async、エグゼキューター、Reactor の境界を越えてコンテキストを伝播します。
• 外部依存関係ごとに、レイテンシー、スループット、障害、飽和度を記録します。

ヘルスチェックとレディネス

• 依存サービスの障害で全ポッドが再起動しないよう、ライブネスをリモートシステムから独立させます。
• 必須の依存関係をレディネスグループに含めます。
• カスタムヘルスインジケーターは、トラフィックの受け入れに影響する依存関係に対してのみ作成します。
• ヘルスチェックには明示的なタイムアウトを設定します。

ログとアラート

• トレースとスパンの相関情報を含む構造化ログを出力します。
• 認証情報、トークン、個人データ、プロンプト、ペイロードは、デフォルトでマスキングします。
• 生のメトリクスノイズではなく、サービス目標に関連する症状に対してアラートを設定します。
• ランブックへのリンクと、影響を受けているサービスや依存関係を特定するのに十分なディメンションを含めます。

例

• examples/good-observation.java と examples/bad-observation.java を参照してください。

注意点

• エージェントがユーザー ID やエンティティ ID をメトリクスのタグに設定すると、カーディナリティが無制限になります。
• エージェントがすべての Actuator エンドポイントを公開すると、露出が過剰になります。必要最小限だけを公開し、保護してください。
• エージェントがデータベースをライブネスの条件にすると、依存サービスの障害によって再起動ループが発生します。
• エージェントがデバッグ用にリクエスト本文やトークンをログに出力する場合は、出力前に機密データをマスキングしてください。
• エージェントがスパンを作成しても非同期処理でコンテキストが失われる場合は、コンテキスト伝播を明示的に設定してください。