telemetry

テレメトリー運用

このスキルは、Prometheus、OpenTelemetry Collector、Lokiから成るテレメトリースタックを、提供時の単一のデプロイ単位として運用するために使用します。対象は、収集とスクレイピング、取り込み、保持、および生のシグナルをアラートに変換するルールです。これは、名前付きツール群の1つのスタックを対象とするツールスキルです。オブザーバビリティの戦略（SLI、SLO、エラーバジェット、計測対象）はplatform-engineeringの範囲です。ダッシュボード、パネル、Grafana側のアラートルール、コンタクトポイント、通知ポリシーはgrafanaの範囲です。このスキルが担当するのは、収集／取り込み／保持レイヤーと、これら2つのスキルが利用するPrometheusルールファイルです。

運用上の契約

1. 変更を加える前に、読み取り専用の調査を行います。 スクレイプ設定、ルールファイル、コレクターパイプライン、保持設定を最初に確認します。同梱のtelemetry-checkスクリプトは、何も変更せずにルールの健全性とスクレイプターゲットへの到達性を確認します。
2. 実行前に対象、範囲、ロールバック手順を確認します。 読み取り専用の調査は、確認を得ずに進められます。設定のリロード、promtoolによるルールのプッシュ、コレクターの再起動、保持ポリシーの変更などの変更には、対象インスタンスを明示した人間からの指示が必要です。
3. 設定を解析できても、正常に動作するとは限りません。 ルールの健全性チェックで構造は確認できますが、式が適切であることや、ターゲットをスクレイピングできることは証明されません。正常であると判断する前に、デリバリー境界（スクレイプ成功、ルール評価、アラート発火）で検証します。
4. 証拠は必要な範囲に限定します。 設定の差分とクエリ結果は要約し、prometheus.yml、コレクターパイプライン、認証情報をチャットに丸ごと出力しないでください。
5. 保持の判断に責任を持ちます。 保持は、コンポーネントごとに意図的に決定する容量およびコンプライアンス上の判断です。Prometheusのブロック保持、OTelエクスポーターのバッファリング、テナントごとのLoki保持を定期的に見直し、デフォルトのまま放置しないでください。

telemetry-checkスクリプト

scripts/telemetry-checkは、エージェント向けの読み取り専用チェッカーです。同梱の標準ライブラリYAMLリーダーでPrometheusルールファイルを解析し、依存関係のない構造健全性チェックを実行します。スクレイプ設定から静的ターゲットを抽出してTCP到達性を確認し、範囲を限定したJSONを出力します。ファイルへの書き込みや、データの外部送信は一切行いません。

scripts/telemetry-check --help                      # no server needed
scripts/telemetry-check --rules rules.yml --json    # rule sanity, machine-readable
scripts/telemetry-check --scrape prometheus.yml --json   # probe static targets
scripts/telemetry-check --targets targets.txt --timeout 5

終了コード：0はすべてのチェックに合格、1は問題の検出または致命的なエラー、2は使用方法のエラーです。telemetry-check --rulesで確認するのは構造のみです。各ルールにrecordまたはalertのどちらか一方だけが設定されていること、式が空でなく区切り記号の対応が取れていること、有効な期間、レコーディングルール名とラベル名、ラベル値が文字列のみであることを確認します。PromQLを完全に解析するには、別途promtool check rulesを使用してください。

運用手順

1. デプロイを特定します：対象コンポーネント（Prometheus、OTel Collector、Loki）、デプロイ方法（バイナリ、コンテナー、オペレーター）、設定ファイルの保存場所、管理者を確認します。
2. 証拠を収集します：設定に対してtelemetry-check --rulesと--scrapeを実行し、アクセス可能な場合は稼働状態エンドポイント（/-/healthy、/api/v1/targets、コレクターのヘルスチェック、Lokiのreadyエンドポイント）も確認します。
3. クエリを調査する場合は、references/05-query-workflows.mdを読み込みます。シグナル、セレクター、UTCの時間範囲、ステップ／上限、想定単位を定義します。構文と意味を個別に検証し、読み取り専用のインスタントクエリを実行してから、範囲とログを限定したクエリを実行します。ステータス、範囲、時刻、上限、警告、カーディナリティの証拠を記録します。
4. 症状に照らしてトリアージします：報告された問題を証拠に対応付けます（シリーズが見つからない → スクレイプまたはラベルの再設定、アラートが発火しない → ルールまたは保持、ログが見つからない → 取り込みまたはラベルのカーディナリティ）。空の結果は不明として扱い、数値の0と見なさないでください。また、古い状態、一部の結果、期限切れ、ラベル不在、クエリエラーの各状態を区別します。
5. 確認を得て変更します：人間からの指示を得てから、範囲を限定した変更を行います。最初にロールバック手順を明示してください。
6. 検証します：該当するチェックを再実行し、デリバリー境界で観測できることを確認します。

Prometheus：スクレイプ、ルール、再ラベル付け、保持期間、HA

• スクレイプ設定（scrape_configs）：スクレイプグループごとに1つのジョブを設定し、意図的に scrape_intervalを定め、その値より短い scrape_timeoutと metrics_pathを指定します。既知のエンドポイントにはstatic_configs、動的なエンドポイントにはサービスディスカバリー（*_sd_configs）を使用します。実行中の設定は/api/v1/status/config、ターゲットは/api/v1/targets?state=activeで確認します。
• 記録ルールとアラートルール：ルールファイルは、PromQLのexpr、任意のfor／keep_firing_for期間、labels／annotationsを持つrecordルールまたはalertルールのgroupsで構成されます。変更をリロードする前に、promtool check rulesでPromQLを完全に解析し、同梱のtelemetry-check --rulesで依存関係なしに構造上の妥当性を確認します。ルールは小さく、適切な名前を付け、レビューしやすくする必要があります。100行の式はデバッグの負担であり、ルールではありません。
• 再ラベル付け：relabel_configsとmetric_relabel_configsは、取り込み前にラベルを書き換えます。ラベル名の規則の徹底、高カーディナリティまたは内部ラベルの削除、スクレイプメタデータの付加に使用します。再ラベル付けの誤りは、系列の識別情報をひそかに変えてしまいます。/metricsへの対象を絞ったcurlと、/api/v1/targetsにあるターゲットのscrapeUrlで確認してください。
• 保持期間：--storage.tsdb.retention.timeと--storage.tsdb.retention.sizeでローカルブロックの保持範囲を制限します。ブロックの既定期間は2hです。保持期間は容量に関する判断事項であり（references/04-stack-integration-and-retention.mdを参照）、既定値のまま放置するものではありません。カーディナリティとコンパクションの負荷を把握するため、prometheus_tsdb_head_seriesとprometheus_tsdb_compactionを監視します。
• 高可用性（HA）：同一の設定を持つ2つのPrometheusインスタンスに、--query.max-concurrencyの余裕を持たせ、一貫した外部ラベルを設定すると、クエリレイヤー（Thanos、Mimir、またはGrafanaのデータソース）でシャーディングまたは重複排除を行えます。アラートルールが二重発報しないようにする必要があります。HAペアには重複排除レイヤーか一貫したラベル付けが必要で、レプリカ間でルール評価を一貫させる必要があります。ルール評価の状態（forカウンター）は各インスタンス内に保持されます。

OpenTelemetry Collector：パイプライン、サンプリング、相関

• Collectorパイプライン：パイプラインは、シグナルの種類（メトリクス、ログ、トレース）ごとに、receivers → processors → exportersをつないだ有向非巡回チェーンです。パイプラインは種類ごとに分け、範囲を絞ってください。シグナルを混在させると、デバッグできなくなります。各パイプラインには少なくとも1つのエクスポーターが必要です。使用されていないレシーバーやエクスポーターは、不要な設定です。
• レシーバー、プロセッサー、エクスポーター：レシーバーはデータ（OTLP、Prometheus、filelog、hostmetrics）を受け入れます。プロセッサーはデータを変換、バッチ処理、フィルタリング、サンプリングし、リソース属性を付加します。エクスポーターはデータを後続へ送信します（OTLP、Prometheus remote write、Loki、logging）。順序が重要です。バッチ処理とmemory_limiterプロセッサーはエクスポーターより前に配置し、tail_samplingはトレースパイプラインだけに配置します。
• サンプリング：トレースのtail_samplingはバッチ単位で判断し、probabilistic_samplerはステートレスで、より低コストです。意図的にサンプリングしてください。エラーや処理に時間のかかる経路はトレースをすべて保持し、大量の正常トラフィックにはテールサンプリングを適用し、エラーのシグナルは決してサンプリングで取り除かないでください。サンプリングは保持期間と連携させる必要があります。サンプリングされたトレースは永久に失われるため、この判断は緊急時ではなく、パイプラインの設計段階で行います。
• トレース／スパンの相関：ログ行とメトリクスのエグゼンプラーにtrace_idとspan_idを含め、LogQLとPromQLからトレースに戻れるようにします。CollectorのspanmetricsプロセッサーはスパンからREDメトリクスを導出し、トレースコンテキストを含むOTLPログは、相関用の構造化ラベルとしてtrace_idを付けてLokiに取り込まれます。トレースコンテキストの伝搬はアプリケーションレベルの課題であり、backend-engineeringが担当します。Collector側についてはここで説明します。

Loki：取り込み、LogQL、保持期間、ラベル

• 取り込み：Loki は、Promtail、OTel Collector の loki exporter、または Grafana Agent/Alloy からプッシュ API（/loki/api/v1/push）経由でデータを取り込みます。loki_distributor_bytes_received_total と ready エンドポイントで取り込みを確認してください。取り込みが（レート制限や too many outstanding requests により）気付かれないまま破棄されると、障害を見逃すことになります。
• LogQL：{label="value"} |= "filter" | json はストリームを選択し、行をフィルタリングします。ラベルマッチャーが主なコスト要因です。LogQL の分析クエリ（sum by (...) (rate({app="x"} |~ "error"[5m]))）は、ラベルインデックスと行のフィルタリングを組み合わせて処理されます。実際に使うマッチャーのコストが低くなるようにラベルを設計してください。
• 保持期間：retention_period と retention_size はテナントごとに適用されます。コンパクターがこれらを適用し、インデックスのシャードを統合します。管理しなければログ量に上限はありません。ロールアウト前に保持期間を設定し、loki_compactor のメトリクスで追跡してください。また、ログの保持は責任者を定めて決定するコンプライアンス上の判断として扱ってください。
• ラベル：Loki のラベルは反転インデックスです。カーディナリティの高いラベル（リクエスト ID、ユーザー ID、トレース ID）はインデックスのサイズとストリーミングコストを急増させます。ラベルはテナント、アプリ、環境、ジョブに限定し、カーディナリティの高いフィールドはログ行に含めて、LogQL の | json／| regexp または OTel の構造化メタデータで抽出してください。カーディナリティに関する指針：ログ行ごとに値が変わるラベルはインデックスに含めないでください。

スタック全体での保持期間

保持期間はスタック全体に関わる判断です。Prometheus ブロック（生のサンプル）、OTel Collector のバッファリング（メモリ内キュー、エクスポーターの再試行）、Loki（インデックス化されたログ）はそれぞれ独立した保持期間を持ち、チームが負担するのはそれらを合わせたストレージ容量です。データが答える問い（アラート用の直近のメトリクス、傾向分析用のサンプル、デバッグと監査用のログ）に基づいてコンポーネントごとに決定し、設定ファイルに反映して、定期的に見直してください。トレードオフの表と保持期間を監視するアラートルールについては、references/04-stack-integration-and-retention.md を参照してください。

参照資料の振り分け

次の場合に読み込む	参照資料
ソース、バージョンに関する記録、更新手順	references/00-source-index.md
スクレイプ設定、記録ルール／アラートルール、再ラベル付け、保持期間、HA	references/01-prometheus-operations.md
Collector のパイプライン、レシーバー／プロセッサー／エクスポーター、サンプリング、相関付け	references/02-opentelemetry-collector.md
取り込み、LogQL、保持期間、ラベル設計	references/03-loki-operations.md
PromQL／LogQL の構築、意味の確認、コストの上限設定、データがない場合の診断	references/05-query-workflows.md
コンポーネント間の保持期間に関する判断とスタックの統合	references/04-stack-integration-and-retention.md

含まれる成果物

• scripts/telemetry-check：読み取り専用のルール確認とスクレイプターゲット到達可能性のチェックツール（標準ライブラリのみ、--json、--rules／--scrape／--targets、サーバーなしでの --help）。
• tests/test_telemetry_check.py：読み取り専用の契約を含む、フィクスチャ設定を使った決定論的なテスト。
• fixtures/：テストと出発点として使う prometheus-rules.yml（有効なルール）と scrape-config.yml（有効なスクレイプ設定）。
• references/：日付とソースインデックスを付した5つの参照資料とソースインデックス。コストに上限を設けた PromQL／LogQL のワークフローを含みます。
• evals/evals.json：エージェントの実行用の、出力品質を評価する6つのケース。

検証の境界

主張	最低限の証拠
ルールファイルの構造が正しい	telemetry-check --rules FILE --json がエラーなしで終了コード 0 を返す
ルールファイルが意味的に有効	promtool check rules FILE が終了コード 0 を返す
ターゲットからスクレイプできる	telemetry-check --scrape CONFIG --json が到達可能と報告し、/api/v1/targets に state="up" と表示される
パイプラインが稼働中	Collector のヘルスエンドポイントが応答し、シグナルごとのメトリクス（otelcol_receiver_*、otelcol_exporter_*）が増加する
取り込みが正常	Distributor のメトリクスが増加し、ready エンドポイントが 200 を返す
保持ポリシーが適用されている	retention_period／retention_size が明示的に設定され、compactor／TSDB のメトリクスでポリシーが確認できる

厳守すべき境界

• 対象とロールバック手順が明示された人間からの指示なしに、スクレイプ設定、ルールファイル、Collector パイプライン、保持ポリシーを変更してはいけません。読み取り専用の調査は自由に行えます。
• スクレイプの成功、ルールの評価、アラートの発火といった配信境界の証拠なしに、ルールやターゲットが機能すると主張してはいけません。
• 設定全体、認証情報、生ログをチャットで公開してはいけません。代わりに証拠を要約してください。
• telemetry-check は読み取り専用ツールとしてのみ実行してください。変更機能はありません。
• ダッシュボード、Grafana アラートルール、連絡先、通知ポリシーはgrafanaの担当範囲です。SLI／SLO の設計とオブザーバビリティ戦略はplatform-engineeringの担当範囲です。ここでは内容を重複させないでください。

使用しない場合

• オブザーバビリティ戦略と SLO（計装対象、SLI／SLO の設計、エラーバジェット、ページングポリシー）— これはplatform-engineeringの担当範囲です。
• Grafana 製品に関する作業（ダッシュボード、パネル、データソース、Grafana アラートルール、連絡先、通知ポリシー、RBAC）— これはgrafanaの担当範囲です。Prometheus と Loki にクエリを実行しますが、Grafana 側を担当します。
• アプリケーションの計装コード（サービス内の OTel SDK、トレースコンテキストの伝播、アプリケーションコード内のカスタムエクスポーター）— これはアプリケーション開発の担当範囲です。backend-engineeringを参照してください。
• リバースプロキシとエッジのオブザーバビリティ（Traefik のメトリクス／トレース／アクセスログ設定）— これはtraefikの担当範囲です。そのオブザーバビリティリファレンスでは、このスタックをバックエンドとして扱います。
• スタックのインフラストラクチャへのデプロイ（Helm チャート、Kubernetes オペレーター、スタック自体の Docker Compose）— これはkubernetesとdocker-composeの担当範囲です。
• その他のバックエンド（Tempo、Mimir、Thanos、Datadog、InfluxDB）— これらはそれぞれの担当者の範囲です。このスキルでは Prometheus、OTel Collector、Loki を一つの単位として扱います。