observability-guidelines

可観測性ガイドライン

これらの可観測性の原則を適用し、分散システムやマイクロサービスを包括的に可視化しましょう。

可観測性の基本原則

• 可観測性を組み込んだ、慣用的で保守しやすく高性能なコードの開発を促進します
• クリーンアーキテクチャを通じて、モジュール設計と関心事の分離を徹底します
• テスト駆動開発を推進し、初期段階から堅牢な可観測性を確保します

OpenTelemetry の統合

• 分散トレース、メトリクス、構造化ログに OpenTelemetry を使用します
• すべてのサービス境界をまたいでトレーススパンを開始し、伝播させます
• スパンの作成には otel.Tracer を、メトリクスの収集には otel.Meter を使用します
• OpenTelemetry Collector、Jaeger、または Prometheus にデータをエクスポートします
• 本番環境に適したサンプリングレートを設定します

分散トレース

• すべての受信リクエストをトレースし、内部呼び出し全体にコンテキストを伝播させます
• ミドルウェアを使用して、HTTP と gRPC のエンドポイントを自動的に計測します
• すべての下流サービス呼び出しにトレースコンテキストを含めます
• サービス内の重要な操作に対して子スパンを作成します
• デバッグと分析に役立つ属性をスパンに追加します

メトリクスの収集

すべてのサービスで、次の主要なメトリクスを監視します。

• リクエストレイテンシ：p50、p90、p95、p99 のパーセンタイルを追跡します
• スループット：エンドポイントごとに、1 秒あたりのリクエスト数を測定します
• エラー率：4xx と 5xx のレスポンスを分けて追跡します
• リソース使用量：CPU、メモリ、ディスク、ネットワークの使用率を監視します
• カスタムビジネスメトリクス：ドメイン固有の KPI を追跡します

構造化ログ

• 相関のため、すべてのログに一意のリクエスト ID とトレースコンテキストを含めます
• 機械で解析できるように、構造化ログ形式（JSON）を使用します
• タイムスタンプ、サービス名、トレース ID、スパン ID など、関連するコンテキストを含めます
• 適切なレベル（DEBUG、INFO、WARN、ERROR）でログを記録します
• 機密情報（PII、認証情報）のログ記録は避けます

アーキテクチャパターン

• ハンドラー、サービス、リポジトリ、ドメインモデルを備えたクリーンアーキテクチャを適用します
• 明確な境界を定めるため、ドメイン駆動設計の原則を使用します
• 明示的な依存性注入を伴う、インターフェース主導の開発を優先します
• 継承よりコンポジションを優先し、小規模で目的を限定したインターフェースを重視します

相関とコンテキスト

• リクエストのライフサイクル全体を通じてコンテキストを伝播させます
• サービス間でリクエストを追跡するために相関 ID を使用します
• テレメトリにサービスのバージョンとデプロイ情報を含めます
• フィルタリングに役立つビジネスコンテキストをトレースにタグ付けします
• トレースからログへ、ログからトレースへの相関を有効にします

アラートとダッシュボード

• サービスの健全性とビジネスメトリクスを表示するダッシュボードを作成します
• SLO とエラーバジェットに基づいてアラートを設定します
• プロアクティブに問題を特定するため、異常検知を使用します
• よくあるアラートのシナリオについて、ランブックを文書化します
• ノイズを減らすため、アラートを定期的に見直して調整します

計装のベストプラクティス

• サービス境界（入口と出口）で計装します
• データベース操作や外部呼び出しにカスタムスパンを追加します
• 関連する属性（ユーザー ID、リクエストの種類など）を含めます
• ノイズを生む過剰な計装は避けます
• 一貫した属性名を使用するため、セマンティック規約に従います

本番環境での考慮事項

• 可視性とコストのバランスを取るため、適切なサンプリングレートを設定します
• 一貫してトレースを取得するため、ヘッドベースサンプリングを使用します
• エラーを取得するため、テールベースサンプリングを実装します
• デバッグのニーズに応じて保持ポリシーを設定します
• 可観測性基盤の健全性を監視します