可観測性ガイドライン

分散システムとマイクロサービスへの包括的な可視性を確保するために、これらの可観測性原則を適用してください。

コア可観測性原則

• 組み込まれた可観測性を備えた、慣用的で保守しやすく高性能なコードの開発をガイド
• Clean Architecture を通じてモジュール設計と関心の分離を強化
• テスト駆動開発と最初からの堅牢な可観測性を推進

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
• 機密情報 (個人識別情報、認証情報) のログ出力を避ける

アーキテクチャパターン

• ハンドラー、サービス、リポジトリ、ドメインモデルを備えた Clean Architecture を適用
• ドメイン駆動設計原則を使用して明確な境界を実現
• 明示的な依存性注入を備えたインターフェイス駆動開発を優先
• 継承より合成を好み、小さく目的に特化したインターフェイスを優先

相関とコンテキスト

• リクエストライフサイクル全体を通じてコンテキストを伝播
• 相関 ID を使用してサービス間のリクエスト追跡を実施
• テレメトリーにサービスバージョンとデプロイメント情報を含める
• トレースにフィルタリング用の関連するビジネスコンテキストをタグ付け
• トレース対ログおよびログ対トレース相関を有効化

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

• サービスヘルスとビジネスメトリクス用のダッシュボードを作成
• SLO とエラーバジェットに基づいてアラートを設定
• プロアクティブな問題の特定のため異常検知を使用
• 一般的なアラートシナリオのランブックをドキュメント化
• アラートを定期的にレビューおよびチューニングしてノイズを削減

インストルメンテーションのベストプラクティス

• サービス境界 (エントリー/エグジットポイント) でインストルメント
• データベース操作と外部呼び出しに対してカスタムスパンを追加
• 関連する属性を含める (ユーザー ID、リクエストタイプなど)
• ノイズを生成する過度なインストルメンテーションを避ける
• 一貫した属性命名のため意味的慣例を使用

本番環境での考慮事項

• 可視性とコストのバランスを取るため適切なサンプリングレートを設定
• 一貫したトレース取得のためヘッドベースサンプリングを使用
• エラー取得のためテールベースサンプリングを実装
• デバッグニーズに基づいて保持ポリシーを設定
• 可観測性インフラストラクチャのヘルスを監視