authoring-log-alerts

ログアラートの作成

アラートの作成は推測ではなく、_測定_の問題です。網羅することが目的ではありません。重要なサービスにおける実際の本番環境のパターンをもとに、週に0～3回発火するしきい値を設定することが目的です。

このスキルを使う場合

• ユーザーがプロジェクトの「アラートを設定して」／「アラートを提案して」と依頼した場合。
• ユーザーがサービスからアラート対象となるシグナルが出ているかを評価したい場合。
• ユーザーがログアラートを有効にしたばかりで、最初のアラートセットを求めている場合。

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

• 既存のアラートを調整する場合 — これは別の作業です（発火／解決の頻度を確認するには posthog:logs-alerts-events-list を使い、調整するには posthog:logs-alerts-partial-update を使います）。
• 発生中のインシデントを調査する場合 — posthog:query-logs で行を取得してください。インシデントの最中にアラートを作成しないでください。

ツール

ツール	役割	使用する場面
posthog:logs-services	指定期間の上位25サービスと、log_count、error_count、error_rate、スパークラインを表示します。	ステップ1 — トリアージ。
posthog:logs-attributes-list / posthog:logs-attribute-values-list	より絞り込んだフィルターに使うキー／値を見つけます。	ステップ2、任意。
posthog:logs-count-ranges	フィルターに対する適応型の時間バケット別カウントを取得します。	ステップ3 — ベースライン。
posthog:logs-alerts-simulate-create	下書きの設定を -7d の履歴に対して、完全な状態機械で再生します。	ステップ4 — 検証。
posthog:logs-alerts-create	アラートを保存します。	ステップ5 — 公開。
posthog:logs-alerts-destinations-create	アラートをSlack、webhook、またはMicrosoft Teamsに接続します。	ステップ5：公開。

作成時に posthog:query-logs を呼び出さないでください。必要なのは行ではなく分布です。ユーザーが「発火していたもののサンプルを見せて」と求めた場合に限り、最後の手順で posthog:query-logs を使います。limit: 10 で十分です。

ワークフロー

1. トリアージ — 候補サービスを選ぶ

フィルターを指定せず、直近24時間分の posthog:logs-services を呼び出します。レスポンスは25サービスまでに制限され、スパークラインも含まれるため、小さくまとまっています。

次の両方を満たす場合、そのサービスを候補にします。

• log_count が無視できない数である（24時間で約1,000以上 — ログが少ないサービスでは、アラートを設定できるほどのシグナルが得られません）。
• error_rate がゼロではない、またはユーザーがそのサービスを明示的に指定している。

ユーザーがログ量の変化に関するアラート（例：「api-gatewayが突然ログを出さなくなったら警告して」）を希望していない限り、ログ量は多くても error_rate == 0 のサービスは除外します。ログ量の下限アラートには threshold_operator: below を使い、異なる考え方が必要です。references/volume-floor-alerts.md を参照してください。

ユーザーがサービスを指定している場合は、エラーシグナルがなくても候補として扱います。

2. （任意）フィルターを絞り込む

サービスに複数のエラーサブタイプがある場合、「すべてのエラー」に対するアラートは通常、範囲が広すぎます。posthog:logs-attributes-list（attribute_type: log を試してください）と posthog:logs-attribute-values-list を使って判別に使える属性を探します。よく使われる属性は http.status_code、error.type、k8s.container.name です。下書きに絞り込みフィルターを追加してください。

シンプルに保ちます。重大度フィルターを1つ、属性フィルターを1～2つ使えば十分です。複数条件のフィルターは判断が難しくなり、精度の向上につながることもほとんどありません。

3. ベースライン — 7 日間にわたって候補を評価する

候補のフィルター、dateRange: { date_from: "-7d" }、targetBuckets: 24（1 バケット ≈ 7 時間）を指定して、posthog:logs-count-ranges を呼び出します。レスポンスにはバケットごとの件数が含まれます。

パーセンタイルを目視で判断したり、しきい値をアラートの時間枠に合わせて手動で調整したりしないでください。 件数範囲のレスポンスをヘルパースクリプトに渡してください。

echo '<count-ranges JSON>' | python3 scripts/baseline_stats.py --window-minutes 5

スクリプトは次の値を返します。

{
  "n_buckets": 12,
  "bucket_minutes": 420.0,
  "alert_window_minutes": 5,
  "stats": { "p50": 12.0, "p95": 71.25, "p99": 126.25, "max": 140 },
  "suggested_threshold_count": 5,
  "rationale": "max(p99=126.25, median*3=36.0, floor=5) scaled from 420m bucket to 5m window",
  "health": []
}

suggested_threshold_count を初期しきい値として使用します。health を確認してください。

health フラグ	意味	対応
sparse:N_of_M_buckets	7 日間のベースラインとして、空でないバケットが少なすぎます。	フィルターの範囲を広げる、期間を -30d に延長する、またはスキップします。
empty	すべてのバケットがゼロです。	スキップします — シグナルがありません。
spiky	max が p95 の 10 倍以上です。	件数しきい値アラートが適しています。続行します。
flat	p95 ≈ p50 です。	慎重に判断してください — 振り返り期間中にインシデントがなかったか、メトリクスが平滑すぎる可能性があります。期間を延長するか、スキップしてください。
[]（空）	分布は健全です。	続行します。

4. 下書きを作成してシミュレーションする

以下のデフォルト値から初期設定を選びます。設定の根拠については、references/threshold-defaults.md を参照してください。

設定	デフォルト	備考
threshold_count	スクリプトの suggested_threshold_count	アラートの時間枠に合わせて調整済みです。
threshold_operator	above	件数下限アラートの場合のみ below を使用します。
window_minutes	5	許可値：5、10、15、30、60。スクリプトに渡した値と一致させる必要があります。
evaluation_periods	3	N-of-M の M です。
datapoints_to_alarm	2	N-of-M の N です。2-of-3 にすると、ノイズの多いバケットが 1 つあった場合の誤報を減らせます。
cooldown_minutes	30	通知（発報または解決）の最短間隔です。

これらの設定と date_from: "-7d" を指定して、posthog:logs-alerts-simulate-create を呼び出します。レスポンスには fire_count と resolve_count が含まれます。

5. 反復 — 3 回試し、その後公開するか見送る

目標：-7d で fire_count を 0〜約 3 にします。この範囲外の場合：

結果	調整
7 日間の fire_count = 0 かつ ベースラインにスパイクがあった	スクリプトの stats.p95 に近づけるよう threshold_count を下げるか、1-of-2 に変更します。
fire_count = 0 かつ ベースラインがフラット	このサービスにはアラートに適したシグナルがありません。見送り、その理由を記録します。
fire_count > 5	スクリプトの stats.max に近づけるよう threshold_count を上げるか、より滑らかなウィンドウになるよう 3-of-5 に変更します。
fire_count は問題ないが、resolve_count が fire_count と一致しない	クールダウンが長すぎるか、基になる状態が実際に継続しています。現時点では許容範囲です。

しきい値を調整する際は、スクリプトの stats ブロックから値を読み取ってください。パーセンタイルを手計算で再計算してはいけません。

候補ごとの反復は、シミュレーション呼び出し 3 回までにします。3 回試しても範囲内に収まらない場合、そのメトリクスは適切ではありません。フィルターの範囲が広すぎるか、ウィンドウが適切でないか、サービスにしきい値の形を持つシグナルが実際にありません。その旨を記録して次に進みます。

6. 公開 — 作成と通知先の設定

ドラフトのシミュレーションが問題なく完了したら：

1. 検証済みの設定を使って posthog:logs-alerts-create を呼び出します。このスキルから作成されたアラートだとユーザーがひと目でわかるよう、<service> error rate (auto) のような名前を付けます。

2. 通知先を設定するために posthog:logs-alerts-destinations-create を呼び出します。通知先のないアラートは通知されません。 対応する通知先フィールド：

   • Slack：type: "slack"、slack_workspace_id、slack_channel_id。slack_channel_name は任意です。
   • Webhook：type: "webhook" と webhook_url。
   • Microsoft Teams：type: "teams" と webhook_url。

   設定する前に、チャンネル名または Webhook URL を必ずユーザーに確認してください。明示的な確認なしに、自動生成したアラートを本番チャンネルに接続してはいけません。ユーザーが迷っている場合は、最初の数件のアラートにはトラフィックの少ないテスト用チャンネルを提案します。

確認後に切り替えるため、アラートを enabled: false の状態で作成したい場合は、-create に enabled: false を渡し、作成したドラフトの数を伝えます。

フィルターの形式 — 必須

posthog:logs-alerts-create の filters フィールドには LogsViewerFilters のサブセットを指定し、次のうち少なくとも 1 つを含める必要があります。

• severityLevels — ["trace","debug","info","warn","error","fatal"] のリスト
• serviceNames — サービス名文字列のリスト
• filterGroup — プロパティフィルターグループ

同じ形式を posthog:logs-alerts-simulate-create の filters フィールドにも指定します。シミュレーションのフィルターはアラートのフィルターと完全に一致させてください。一致しないと、公開するアラートとは異なるアラートをシミュレーションすることになります。

最小限の例：

{
  "severityLevels": ["error", "fatal"],
  "serviceNames": ["api-gateway"]
}

トークン節約のルール

• 最初に posthog:logs-services を 1 回呼び出します。候補ごとには呼び出しません。
• 候補ごとに targetBuckets: 24 を指定して posthog:logs-count-ranges を 1 回呼び出します。作成中に 30 を超えないようにします。
• 候補ごとの posthog:logs-alerts-simulate-create 呼び出しは 3 回以下にします。
• 作成ループ中の posthog:query-logs 呼び出しは 0 回にします。
• 未検証のドラフトを長々と並べるより、十分に検証した少数のアラートを報告します。

出力

次の形式で、実施した内容を報告します。

• 公開した各アラート：名前、フィルター、しきい値、7 日間でシミュレーションした fire_count、通知先。
• 見送った各候補：サービス名と理由（フラットなベースライン、しきい値を調整できない、トラフィック量が少ない）。
• シミュレーション呼び出しの合計数、作成したアラートの合計数。

ユーザーがこの内容を確認し、本番稼働前にドラフトを無効にするかどうか判断できるようにします。

関連スキル

• investigating-logs — サービスにアラートを設定する前にベースラインを把握し、アラート発報後に調査します
• authoring-error-tracking-alerts — ログ行ではなく例外に対してアラートを設定します