rust-observability

Rust のオブザーバビリティ

運用上の疑問や障害モードを起点にテレメトリーを設計します。ログは個別のイベントを説明し、トレースは境界を越えた処理をつなぎ、メトリクスは時間の経過に伴う振る舞いを定量化し、プロファイルはリソース消費を診断します。すべてのデータをすべてのシグナルに出力しないでください。

対象範囲とルーティング

tracing、サブスクライバー、構造化ログ、メトリクス、OpenTelemetry、コンテキスト伝播、サンプリング、エクスポーター、リクエスト相関、非同期ランタイム診断、秘匿化、シャットダウン時のフラッシュには、このスキルを使用します。

並行性の正しさについては rust-concurrency、HTTP ミドルウェアについては rust-web、セキュリティイベントのポリシーについては rust-web-security、パフォーマンスプロファイリングについては rust-performance、依存関係の機能については rust-cargo-build にルーティングします。

ワークフロー

1. 意思決定と SLO から始める

運用担当者が答える必要のある疑問を列挙します。リクエストレートとレイテンシ、エラーカテゴリー、飽和状態、キューの深さ、再試行、依存関係の健全性、タスクのリーク、リソース使用量、デプロイの識別情報などです。エクスポーターを選ぶ前に、サービス名、環境、バージョン、インスタンス属性、所有者、保持期間、アクセス制御、コスト予算を定義します。

2. 構造化トレーシングを確立する

処理時間を伴う操作やネストされた処理には tracing のスパンを使用し、ある時点で発生した事実にはイベントを使用します。

use tracing::{info, instrument};

#[instrument(skip(payload), fields(job.id = job_id))]
async fn process(job_id: u64, payload: &[u8]) {
    info!(payload.len = payload.len(), outcome = "accepted");
}

• ドメイン上の意味に基づき、スパン名とフィールド名に一貫性を持たせます。
• シークレット、本文、認証情報、生の SQL 値、大きなペイロードは記録しません。
• フォーマット済みメッセージだけでなく、安定したエラーカテゴリーと結果を記録します。
• .await をまたいでスパンガードを誤って保持するのではなく、インストルメント化された Future がポーリング中に入場するようにします。
• フィルタリングとフォーマットはライブラリ内ではなく、アプリケーション境界で設定します。

トレーシングと構造化ログを参照してください。

3. カーディナリティを抑えたメトリクスを設計する

合計値にはカウンター、現在の状態にはゲージ、分布にはヒストグラムを選びます。安定した低カーディナリティのラベルを使って、スループット、レイテンシ、エラー、飽和状態、キュー待機時間、再試行、拒否、リソースプールを記録します。

ユーザー ID、リクエスト ID、生のパスを含む URL、SQL テキスト、任意のエラーメッセージ、上限のないテナント ID をメトリクスラベルに使用しないでください。SLO に基づいて、ヒストグラムの単位とバケットを定義します。メトリクスとカーディナリティを参照してください。

4. 分散コンテキストを伝播する

信頼できるトランスポート形式からのみリモートトレースコンテキストを抽出し、サーバーまたはコンシューマーのスパンを作成して、現在のコンテキストを送信リクエストやメッセージに注入します。生成したタスク間の因果関係を意図的に維持します。分離されたバックグラウンド処理には、親を継承するのではなくリンクが必要な場合があります。

相互運用性またはベンダーに依存しないエクスポートが必要な場合に限り、OpenTelemetry を使用します。シグナルの成熟度、クレートのバージョン、ランタイム要件、バッチ動作、エクスポーターの互換性を確認してください。OpenTelemetry とコンテキストを参照してください。

5. パイプラインとシャットダウンを設定する

• プロセス起動時にサブスクライバーとレイヤーを一度だけ構成します。
• 認証と監査を備えた制御がある場合に限り、フィルターを再読み込み可能にします。
• エクスポーターのキューに上限を設け、破棄またはバックプレッシャーの動作を定義します。
• 明示的なポリシーでトレースをサンプリングします。成功時のトラフィックを高コストにせず、エラーやまれな経路を観測できる状態に保ちます。
• サービスのシャットダウン期限内に、テレメトリープロバイダーをフラッシュするかシャットダウンします。
• 同じインストルメント化されたネットワーク経路を使用するエクスポーターからの再帰的なテレメトリーを避けます。

6. テレメトリーの動作を検証する

フィールド名、レベル、エラーカテゴリー、コンテキスト伝播、秘匿化、カーディナリティ、サブスクライバー無効時の動作、エクスポーター障害、キューの飽和、シャットダウン時のフラッシュをテストします。不安定なフォーマット済み行をアサートするのではなく、テスト用サブスクライバーまたはメモリー内エクスポーターを使用します。

診断ビルドでは tokio-console を使用して、長時間のポーリング、リソース待ち、リークしたタスクを見つけます。制御エンドポイントを公開しないでください。ランタイムと運用を参照してください。

完了基準

• すべてのシグナルを、運用上の問いまたは SLO に結び付けます。
• 安定したフィールドと明示的な秘匿化を備えた、構造化スパンとイベントを使用します。
• メトリクスのラベル数を制限し、ヒストグラムの単位を定義します。
• サポート対象の受信、送信、メッセージングの各境界をまたいで、トレースコンテキストを伝播させます。
• エクスポーターのコスト、キュー、サンプリング、シャットダウン時間に上限を設けます。
• 特定のテキストフォーマッターやベンダーに依存せず、テレメトリーを振る舞いとしてテストします。

リソース

• トレーシングと構造化ログ
• メトリクスとカーディナリティ
• OpenTelemetry とコンテキスト
• ランタイムと運用
• 実行シナリオ
• examples/golden-observability/：コンパイル可能なカスタムトレーシングレイヤーの仕様。

上流のソース

• tracing
• tracing-subscriber
• OpenTelemetry Rust
• metrics
• tokio-console

データのプライバシー

このスキルは、ユーザーデータを収集、保存、送信しません。テレメトリーの変更によって本番データが送信される場合があります。エクスポーターを有効にする前に、承認、送信先、保持期間、秘匿化、アクセス制御を確認してください。