investigating-logs

ログの調査

調査は絞り込みの問題です。読む前に要約してください。 posthog:logs-patterns を 1 回呼び出すと、数百万行を最大 200 個のテンプレートに圧縮できます。 posthog:logs-patterns-diff を 1 回呼び出すと、「以前と比べて現在は何が違うのか」に直接答えられます。 生の行（posthog:query-logs）を確認するのは、調査の最後のステップであり、最初ではありません。

このスキルを使う場面

• 「ログを確認して」／「サービス X は正常ですか？」／「デプロイ（またはモデルの更新、設定変更、移行）で何か問題が起きましたか？」
• 「エラーが増えたのはなぜですか？」／「この急増について説明して」／インシデントのトリアージ — 「何が変わりましたか？」
• 「このサービスは何をログに記録していますか？」— 見慣れない、またはノイズの多いログストリームを把握するとき。
• 別の場所で報告された障害（アラート、エラートラッキングの課題、ユーザーからの苦情）の証拠となるログを探すとき。

このスキルを使わない場面

• ログアラートの作成や調整には使いません。これは authoring-log-alerts の役割です。
• プロダクトイベント、ユーザー、インサイトの分析には使いません。これは querying-posthog-data の役割です。
• HogQL では posthog:execute-sql を介して logs テーブルを利用できますが、ログの調査には使わないでください。 ログに対する手書きの SQL は、読み取りバイト数の上限に達することが多く、以下のツールなら 1 回の低コストな呼び出しで得られる結果を改めて導き出すことになります。 SQL は、ログから得られた情報をログ以外のデータと結合する必要があるまれなケースに限って使用してください。

ツール

ツール	役割
posthog:logs-services-create	ログ数、エラー数、エラー率、スパークラインを含むサービス上位 25 件。概要の把握に使用します。
posthog:logs-patterns	1 つの期間のメッセージテンプレートを頻度順に抽出します。「このログストリームには何が記録されていますか？」
posthog:logs-patterns-diff	2 つの期間のテンプレートを比較します。新規／頻度が変化／消失。「何が変わりましたか？」
posthog:logs-count / posthog:logs-count-ranges	フィルターに一致する件数と、時間単位に区切った件数。行を取得する前にボリュームを特定します。
posthog:logs-sparkline-query	重要度またはサービス別に分類した時間経過に伴うボリューム（分類を含む唯一の時間区切り表示）。
posthog:logs-facet-values-create	フィルター条件下での重要度／サービス（またはリソース属性）の分布。
posthog:logs-attributes-list / posthog:logs-attribute-values-list	フィルターを作成する前に、属性キーと値を確認します。
posthog:query-logs	生の行。すべての詳細調査の終着点であり、出発点ではありません。

各ツールの説明には、パラメーターとレスポンスの形式が記載されています。呼び出す前に確認してください。

質問の形式に応じてワークフローを選ぶ

「健全ですか？」— デプロイ後／変更後の検証

ユーザーが何かを変更し（デプロイ、モデルのバージョンアップ、設定、マイグレーション）、ログに問題がないか確認したい場合です。

1. 変更時刻と対象サービスを特定します。ユーザーがまだ伝えていない場合は確認してください。境界がなければ、差分に意味はありません。
2. posthog:logs-services-create で状況を把握します。サービスは引き続きログを出力していますか？現在の error_rate はいくつですか？ ログが出なくなったサービスも、エラーが発生し始めたサービスと同様に、検証に失敗しています。
3. posthog:logs-patterns-diff で、query.dateRange を変更時刻から現在までに設定し、baselineDateRange を変更直前の比較可能な期間に設定して、serviceNames で対象を絞り込みます。 変更直後に新しいエラー／致命的エラーのテンプレートが現れるのは、典型的なデグレの兆候です。既存のエラーテンプレートで rate_ratio が大きく変動していないかも確認してください。
4. 変更前後にまたがる期間を posthog:logs-count-ranges で確認し、ログ量の継続性をチェックします。 メッセージの内容に変化がなくても、レートの不連続（クラッシュループ、再起動の連発、ログの途絶）はここに現れます。
5. 疑わしいパターンだけを掘り下げます。各パターンの match_regex を使って posthog:query-logs から生ログを取得します。

合格と判断するには、次の3点すべてを満たす必要があります。新しいエラーテンプレートがないこと、エラーの rate_ratio に大きな変動がないこと、ログ量が継続していることです。 比較した期間を明示してください。「健全」という判断の確かさは、ベースライン次第です。

「この急増の原因は？」

1. まず発生箇所を絞り込みます。ユーザーが指定した期間を posthog:logs-count-ranges で調べ、ログが集中しているバケットを再帰的に掘り下げます。各バケットの date_from／date_to を次の呼び出しに渡してください。3～4段階で止めます。
2. 原因を説明します。急増期間を query.dateRange、その直前の期間を baselineDateRange に設定して posthog:logs-patterns-diff を実行します。上位の new エントリーと rate_shift エントリーが説明になります。両方の期間を個別に調べて手作業で差分を取らないでください。差分の取得は1回の呼び出しでできます。

インシデントのトリアージ — 「何が壊れましたか？」

まず posthog:logs-patterns-diff を実行します。インシデント期間と、その直前の正常と確認された期間を比較します（同じ曜日の先週と比較する場合は、ベースラインを省略できます）。疑わしいのは new エントリーと、rate_ratio の変動が最も大きい項目です。それぞれを生ログにたどって確認します。 障害が発生しているサービスが不明な場合は、posthog:logs-facet-values-create で severityLevels: ["error", "fatal"] を指定して service_name をファセットし、まずサービスを特定します。

「このストリームには何が記録されていますか？」— 未知のサービス

直近1時間を対象に、サービスを絞り込んで posthog:logs-patterns を実行します。テンプレートを estimated_count と severity_counts のエラー比率（0以外）で確認します。答えが見つからない場合に限り、期間を広げるか searchTerm を追加します。

対象が明確な場合 — 特定のメッセージ、属性、人物

対象がすでに明確な場合（エラー文字列、リクエスト ID、distinct_id など）は、パターンの抽出を省略します。posthog:logs-attributes-list／posthog:logs-attribute-values-list で適切なキーを見つけ、posthog:logs-count で件数を確認してから、posthog:query-logs でログ行を取得します。

調査の信頼性を保ち、コストを抑えるルール

• 対象サービスがわかったら、すべての呼び出しで serviceNames（またはリソース属性フィルター）を指定します。 スコープを指定しない呼び出しはチーム全体のストリームを走査し、パターンサンプルの予算を使い果たします。
• posthog:query-logs では、query.dateRange の明示的な指定が必須です。省略するとデフォルトの期間が使われるのではなく、400 エラーになります。
• パターンの件数はサンプリングによる推定値です（sampled: true）。約 10,000 行に 1 回未満しか出現しないテンプレートは、検出されないことがあります。 まれなテンプレートが見つからなくても、それが出なくなった証拠にはなりません。
• 差分に new の項目が大量に並んでいる場合は、鵜呑みにする前に baseline.total_count を確認します。 ベースラインが小さい、または空（ログ記録が始まったばかり）の場合、すべてが新しい項目に見えます。
• severityLevels は、severity_text と完全一致する6つの標準的な小文字の区分に照合します。 severity フィルターで行数が0件の場合は、posthog:logs-attribute-values-list { key: "severity_text" } で保存値を確認します。
• 予算：サービス呼び出しは1回、期間のペアごとのパターン差分は最大1回、件数範囲のレベルは3～4段階、 query-logs は確認済みの疑わしい項目に限り、limit は100以下にします。

出力

判定を最初に示し、その後に根拠を続けます。

• 判定：健全／劣化／判断不能。比較した期間も示します。
• 疑わしい項目（あれば）：テンプレート、分類（new／rate_shift）、推定件数または rate_ratio、サービス、生ログのサンプル1～2件。
• 確認した内容と未確認の内容：対象サービス、期間、確信度を制限するサンプリングやベースラインに関する注意点。

ユーザーが調査をやり直さなくても、判定に基づいて対応できるようにします。

関連スキル

• authoring-log-alerts — 判定の根拠となったチェックを、継続的でノイズの少ないアラートにします
• exploring-apm-traces — 不審なログ行を起点に、その前後のリクエストトレースをたどります