SKILLOfficialmonitoring

live-data-forensics

プラグイン: amplitude
ソース: GitHub で見る ↗

説明

Amplitudeのデータを使用してライブ製品の問題を調査します。「今日、イベントXは発生しているか」「リリースによってYが動作しなくなったか」「問題Zの影響を受けているユーザーは誰か」といった質問に答えます。確認してから検索する一連の流れ、検索パラメータの設定方法、よくある失敗パターンに対応しています。 **次のような場合に使用:** - インシデント（本番環境の障害）の原因分析 - 計測機能の動作確認 - 影響を受けたユーザーの特定

原文を表示

Investigates live product issues against Amplitude data — "is X firing today", "did the release break Y", "which users are affected by Z". Covers the verify-then-query loop, query_amplitude_data parameterization, and its common failure modes. Use for incident analysis, instrumentation checks, and affected-user discovery.

ユースケース

本番環境の障害原因を分析する
イベント発生状況を確認する
計測機能の動作確認
影響を受けたユーザーを特定する

本文（日本語訳）

ライブデータフォレンジック

このMCPサーバーで最も一般的な多機能の調査作業：実際に起きているイベント（情報システムで記録される出来事）の動作を検証し、どの程度の影響があるかを測定し、影響を受けたユーザーを特定します。実際の運用で見られる調査パターンは決まった流れになっています。その流れに従いましょう。

調査の流れ

コンテクスト（周囲の状況）の確認 get_amplitude_contextを実行（引数なし）→ 続けてprojectIdを指定して再度実行します。プロジェクトIDは推測しないこと。
再利用してから作成する search_amp_entitiesで同じ領域の既存分析がないか探す — 保存済みグラフにはすでに正しいイベント名とセグメント（区分）が含まれています。
クエリ実行前に分類を確認する 接続されたカタログを調べて、そこにある分類リーダーでイベント名の候補と現在のステータス、クエリ可能性を確認してから、イベント・ユーザー・グループのプロパティ（属性）を調べて正確な名前と対象範囲を把握する。名前を推測しないこと — 間違った名前はグラフとして整形されていても中身は空のデータが返り、「ゼロ」と解釈されてしまいます。
イベントが実際に記録されているか確認する check_for_recent_event_ingestionで初出と最終の記録日時を確認 — イベントが記録されていなければ、定義がいかに正確でもグラフは空になります。
影響を測定する query_amplitude_dataを複数回実行 — 1回につき1つのスライス（バージョン別、理由プロパティ別、プラットフォーム別など）で、1度に全部を取得しない。型指定されたchartパラメータ（kind: 'segmentation'、イベント + where/group_by + date_range）を優先。これはサーバー側でコンパイルされ、検証と分類チェックが自動的に実行される — 事前チェック用の別途呼び出しは不要です。環境によって結果が異なる質問の場合は、本番環境と開発・検証環境のプロジェクトを比較してください。
影響を受けたユーザーを特定する query_amplitude_dataで user-ID を group_by（グループ化）指定して影響度の高い順にランク付け → use_amplitude_cohorts action: 'find'でユーザーの完全リストを取得。
タイムラインを再構築する ユーザーごとにget_amp_user_data include: 'timeline'を実行、バッチ処理します（母集団分析なら 10～20 並列呼び出しが通常；1回の呼び出しで最大10の識別子を受け付けます）。

query_amplitude_dataのパラメータ設定（ここで大半のエラーが発生します）

コンパイルエラーは自己解決式 型指定パスが 400 エラーで応答する際は、問題のあるフィールド名と修正ヒントが含まれます — そのフィールド1つだけを修正して再試行、全体を作り直さない。最も多い3つのエラー：相対的な範囲の単位がintervalと一致していない（「過去3年」を週単位で — 「過去156週」に換算するか interval を変更）；ファネル（購買フロー）のconversion_windowにunitがない；そのグラフタイプに対応していないフィルタ演算子（setを使えば全タイプで動作 — 属性の有無を判定）。
日付範囲は必須 — date_rangeを明示的に設定。{relative: "Last 30 Days"}または{start, end}（UNIX時刻の秒単位）どちらか一方のみ、両方は不可。時間単位の粒度ではウィンドウが限定されます（hourは約8日まで）；日単位の粒度は約30日まで。
あらゆるフィルタに有効な演算子と対応する対象範囲が必要 — opとscopeは分類検索から取得、直感で選ばない。対象範囲の不一致（「プロパティXはこのイベントタイプでは追跡されていない」）は、ユーザープロパティをイベントプロパティとして使う、またはその逆をしているということです。
セグメント（区分）はプロパティ条件と行動を組み合わせる — where（プロパティ条件）とperformed（「ウィンドウ内でそのイベントを≥N回実行したユーザー」）。全ユーザーを対象にする場合はsegmentsを完全に省略。
生のdefinitionフォールバック（構成、revenueなど高度なパラメータ）：失敗時、応答にはグラフタイプのスキーマと有効な列挙値、動作例が埋め込まれます — そこから修正して再試行。
read ETIMEDOUTはバックエンド側のタイムアウト — 日付範囲またはフィルタを絞込んで1度だけ再試行。

報告すべき内容

イベントが実際に記録されているか、その量、いつから記録されているか（初出日時）。
影響：影響を受けたユーザー数とアクティブユーザーに占める割合。
重要なスライス（バージョン、プラットフォーム、理由プロパティなど）。
影響を受けたユーザーの根拠：ボリューム上位ユーザーと 2～3 件の再構築タイムライン。

原文（English）を表示

Live Data Forensics

The most common multi-tool job on this MCP server: verify live event behavior, quantify impact, find affected users. Calls observed in the wild follow one arc — follow it too.

The arc

Context. get_amplitude_context (no args) → again with projectId. Do not guess project IDs.
Reuse before rebuild. search_amp_entities for existing analyses of the same area — saved charts already encode correct event names and segments.
Verify taxonomy before querying. Inspect the connected catalog and use its current taxonomy reader to confirm candidate event names, status, and queryability, then read event, user, or group properties for exact names and scope. Never guess names—a wrong name returns a well-formed chart with empty data, which reads as "zero".
Check the event is live. check_for_recent_event_ingestion confirms first-seen/last-seen before you query — a silent event means the chart will be empty no matter how correct the definition is.
Quantify. query_amplitude_data bursts — one slice per call (by version, by reason property, by platform), not one mega-query. Prefer the typed chart parameter (kind: 'segmentation', events + where/group_by + date_range); it compiles server-side and validation + taxonomy checks run automatically — no separate pre-flight call needed. Compare prod vs staging/UAT projects when the question is environment-specific.
Find affected users. query_amplitude_data with a user-ID group_by to rank affected users → use_amplitude_cohorts action: 'find' for the full set.
Reconstruct timelines. get_amp_user_data include: 'timeline' per user, batched (10–20 parallel calls is normal for population analysis; the tool accepts up to 10 identifiers per call).

query_amplitude_data parameterization (this is where most errors come from)

Compile errors are self-serve. The typed path fails with a 400 naming the offending field plus a fix hint — fix that one field and retry, don't rebuild. The three seen most: relative range whose unit doesn't match interval ("Last 3 Years" at weekly interval — re-denominate as "Last 156 Weeks" or change the interval); funnel conversion_window missing unit; unknown filter operator for that chart kind (use set for presence — works in every kind).
Date range is required — set date_range explicitly, either {relative: "Last 30 Days"} or {start, end} epoch seconds, never both. Sub-daily intervals only allow short windows (hour caps ~8 days); daily granularity caps around 30 days.
Every filter needs a valid operator and matching scope — take op and scope from the taxonomy lookup, not intuition. A scope mismatch ("property X is not tracked on this event_type") means you used a user property as an event property or vice versa.
Segments combine property conditions and behaviors — where (property conditions) plus performed ("users who did event ≥N times in a window"). Omit segments entirely for all users.
Raw definition fallback (composition, revenueLtv, advanced params): on failure the response embeds the chart-type schema with valid enums and a working example — fix from that and retry.
read ETIMEDOUT is a backend timeout — narrow the date range/filters and retry once.

What to report back

Whether the event fires at all, volume, and since when (first-seen).
Impact: affected-user count and share of active users.
The slices that matter (version, platform, reason property).
Affected-user evidence: top users by volume + 2–3 reconstructed timelines.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。

ライブデータフォレンジック

調査の流れ

コンテクスト（周囲の状況）の確認 get_amplitude_contextを実行（引数なし）→ 続けてprojectIdを指定して再度実行します。プロジェクトIDは推測しないこと。

再利用してから作成する search_amp_entitiesで同じ領域の既存分析がないか探す — 保存済みグラフにはすでに正しいイベント名とセグメント（区分）が含まれています。

クエリ実行前に分類を確認する 接続されたカタログを調べて、そこにある分類リーダーでイベント名の候補と現在のステータス、クエリ可能性を確認してから、イベント・ユーザー・グループのプロパティ（属性）を調べて正確な名前と対象範囲を把握する。名前を推測しないこと — 間違った名前はグラフとして整形されていても中身は空のデータが返り、「ゼロ」と解釈されてしまいます。

イベントが実際に記録されているか確認する check_for_recent_event_ingestionで初出と最終の記録日時を確認 — イベントが記録されていなければ、定義がいかに正確でもグラフは空になります。

影響を測定する query_amplitude_dataを複数回実行 — 1回につき1つのスライス（バージョン別、理由プロパティ別、プラットフォーム別など）で、1度に全部を取得しない。型指定されたchartパラメータ（kind: 'segmentation'、イベント + where/group_by + date_range）を優先。これはサーバー側でコンパイルされ、検証と分類チェックが自動的に実行される — 事前チェック用の別途呼び出しは不要です。環境によって結果が異なる質問の場合は、本番環境と開発・検証環境のプロジェクトを比較してください。

影響を受けたユーザーを特定する query_amplitude_dataで user-ID を group_by（グループ化）指定して影響度の高い順にランク付け → use_amplitude_cohorts action: 'find'でユーザーの完全リストを取得。

タイムラインを再構築する ユーザーごとにget_amp_user_data include: 'timeline'を実行、バッチ処理します（母集団分析なら 10～20 並列呼び出しが通常；1回の呼び出しで最大10の識別子を受け付けます）。

query_amplitude_dataのパラメータ設定（ここで大半のエラーが発生します）

コンパイルエラーは自己解決式 型指定パスが 400 エラーで応答する際は、問題のあるフィールド名と修正ヒントが含まれます — そのフィールド1つだけを修正して再試行、全体を作り直さない。最も多い3つのエラー：相対的な範囲の単位がintervalと一致していない（「過去3年」を週単位で — 「過去156週」に換算するか interval を変更）；ファネル（購買フロー）のconversion_windowにunitがない；そのグラフタイプに対応していないフィルタ演算子（setを使えば全タイプで動作 — 属性の有無を判定）。

日付範囲は必須 — date_rangeを明示的に設定。{relative: "Last 30 Days"}または{start, end}（UNIX時刻の秒単位）どちらか一方のみ、両方は不可。時間単位の粒度ではウィンドウが限定されます（hourは約8日まで）；日単位の粒度は約30日まで。

あらゆるフィルタに有効な演算子と対応する対象範囲が必要 — opとscopeは分類検索から取得、直感で選ばない。対象範囲の不一致（「プロパティXはこのイベントタイプでは追跡されていない」）は、ユーザープロパティをイベントプロパティとして使う、またはその逆をしているということです。

セグメント（区分）はプロパティ条件と行動を組み合わせる — where（プロパティ条件）とperformed（「ウィンドウ内でそのイベントを≥N回実行したユーザー」）。全ユーザーを対象にする場合はsegmentsを完全に省略。

生のdefinitionフォールバック（構成、revenueなど高度なパラメータ）：失敗時、応答にはグラフタイプのスキーマと有効な列挙値、動作例が埋め込まれます — そこから修正して再試行。

read ETIMEDOUTはバックエンド側のタイムアウト — 日付範囲またはフィルタを絞込んで1度だけ再試行。

報告すべき内容

イベントが実際に記録されているか、その量、いつから記録されているか（初出日時）。

影響：影響を受けたユーザー数とアクティブユーザーに占める割合。

重要なスライス（バージョン、プラットフォーム、理由プロパティなど）。

影響を受けたユーザーの根拠：ボリューム上位ユーザーと 2～3 件の再構築タイムライン。

The arc

Context. get_amplitude_context (no args) → again with projectId. Do not guess project IDs.

Reuse before rebuild. search_amp_entities for existing analyses of the same area — saved charts already encode correct event names and segments.

Verify taxonomy before querying. Inspect the connected catalog and use its current taxonomy reader to confirm candidate event names, status, and queryability, then read event, user, or group properties for exact names and scope. Never guess names—a wrong name returns a well-formed chart with empty data, which reads as "zero".

Check the event is live. check_for_recent_event_ingestion confirms first-seen/last-seen before you query — a silent event means the chart will be empty no matter how correct the definition is.

Quantify. query_amplitude_data bursts — one slice per call (by version, by reason property, by platform), not one mega-query. Prefer the typed chart parameter (kind: 'segmentation', events + where/group_by + date_range); it compiles server-side and validation + taxonomy checks run automatically — no separate pre-flight call needed. Compare prod vs staging/UAT projects when the question is environment-specific.

Find affected users. query_amplitude_data with a user-ID group_by to rank affected users → use_amplitude_cohorts action: 'find' for the full set.

Reconstruct timelines. get_amp_user_data include: 'timeline' per user, batched (10–20 parallel calls is normal for population analysis; the tool accepts up to 10 identifiers per call).

query_amplitude_data parameterization (this is where most errors come from)

Compile errors are self-serve. The typed path fails with a 400 naming the offending field plus a fix hint — fix that one field and retry, don't rebuild. The three seen most: relative range whose unit doesn't match interval ("Last 3 Years" at weekly interval — re-denominate as "Last 156 Weeks" or change the interval); funnel conversion_window missing unit; unknown filter operator for that chart kind (use set for presence — works in every kind).

Date range is required — set date_range explicitly, either {relative: "Last 30 Days"} or {start, end} epoch seconds, never both. Sub-daily intervals only allow short windows (hour caps ~8 days); daily granularity caps around 30 days.

Every filter needs a valid operator and matching scope — take op and scope from the taxonomy lookup, not intuition. A scope mismatch ("property X is not tracked on this event_type") means you used a user property as an event property or vice versa.

Segments combine property conditions and behaviors — where (property conditions) plus performed ("users who did event ≥N times in a window"). Omit segments entirely for all users.

Raw definition fallback (composition, revenueLtv, advanced params): on failure the response embeds the chart-type schema with valid enums and a working example — fix from that and retry.

read ETIMEDOUT is a backend timeout — narrow the date range/filters and retry once.