alibabacloud-emas-apm-query

alibabacloud-emas-apm-query

1. シナリオの説明とアーキテクチャ

モバイルアプリに Alibaba Cloud EMAS APM を統合すると、毎日発生するクラッシュ／ANR／ラグ／カスタム／memory_leak／memory_alloc イベントが SDK によって集計され、バックエンドに報告されます。一般的なトラブルシューティングのワークフローは次のとおりです。

1. 修正する価値が最も高い Issue を見つける：エラー率／エラー数で並べ替え → 上位 3～5 件を選ぶ
2. 特定の Issue の概要を確認する：集計メトリクスと影響を受けたバージョンを取得する
3. 代表的なサンプルをいくつか見つける：異なるデバイス／バージョン／ネットワークを対象にする
4. サンプル内のスタックとビジネスログを読む：対処につながる手がかりを見つける
5. アプリのソースコードと照らし合わせて、修正案を提示する

このスキルは、上記の 5 つのステップを 1 つの CLI パイプラインにまとめます。プロセス全体で呼び出すのは aliyun emas-appmonitor の読み取り専用 API 4 つのみで、データベースやログサービスには依存しません。

GetIssues  → GetIssue → GetErrors → GetError
   ↓
(optional) stack ↔ user APP source → precise file:line + fix diff

対応する BizModules：crash／anr／lag／custom／memory_leak／memory_alloc 対応 OS：android／iphoneos／harmony（harmony は anr／memory_* に対応していません）

2. 前提条件

項目	要件	確認コマンド
Aliyun CLI のバージョン	>= 3.3.3	aliyun version
プラグイン	aliyun-cli-emas-appmonitor	aliyun emas-appmonitor --help
jq	任意のバージョン（スクリプトで必要）	jq --version

インストール手順の詳細については、references/cli-installation-guide.md を参照してください。推奨：自動プラグインインストールを一度有効にしてください。

aliyun configure set --auto-plugin-install true
aliyun plugin update

3. 認証情報の事前確認

AK／SK の値は出力しないでください。利用可能なプロファイルが存在することだけを確認します。

aliyun configure list

想定される出力には、Mode／RegionId が空でない current プロファイルが含まれます。含まれていない場合は、references/cli-installation-guide.md#Configuration に従って AK／OAuth／StsToken／RamRoleArn のいずれかを設定してください。

このスキルは、ライフサイクル全体を通して AK／SK フィールドの値自体を読み取ったり転送したりすることはありません。

4. AI モードのライフサイクル

開始（スキルの実行前）：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-emas-apm-query"

終了（トラブルシューティングの完了後）：

aliyun configure ai-mode disable

5. RAM 権限

このスキルで必要なのは、読み取り専用の emasha:View* アクション 4 つ（ViewIssues／ViewIssue／ViewErrors／ViewError）のみです。EMAS AppMonitor の RamCode は emasha であり、リソースレベルの認可には対応していないため、Resource は "*" に固定されています。

最小権限の完全な JSON ポリシー、同等のシステムポリシー（AliyunEMASAppMonitorReadOnlyAccess／AliyunEMASAppMonitorFullAccess）、およびよくある権限エラーのトラブルシューティングについては、references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応：実行中にコマンドまたは API 呼び出しで権限エラーが発生した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要な権限の全リストを確認する
2. ram-permission-diagnose スキルを使って、必要な権限を申請するようユーザーを案内する
3. 必要な権限が付与されたことをユーザーが確認するまで待つ

6. パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なパラメーター（RegionId、インスタンス名、CIDR ブロック、 パスワード、ドメイン名、リソース仕様など）をすべてユーザーに確認する必要があります。 明示的な承認なしに、デフォルト値を推測したり使用したりしないでください。

パラメーター	必須	型	説明	デフォルト
app-key	はい	int64	EMAS APP Key（通常は 9 桁以上）。現在のワークスペースにある SDK 初期化コードからの推測を優先します（references/appkey-detection.md の 6 つのルールファミリーを参照）。一致するものが 1 つだけ見つかった場合は、それを提示してユーザーの確認を待ちます。複数見つかった場合は候補を一覧表示し、ユーザーに選択してもらいます。見つからない場合は、ユーザーに手動での指定を求めます。	なし（デフォルト：ワークスペースから調査）
os	はい	enum	android / iphoneos / harmony（H5 は h5 ですが、対象範囲外です）。プロジェクトの種類から app-key と同時に推測します：build.gradle / AndroidManifest.xml → android、*.xcodeproj / Podfile → iphoneos、module.json5 + ets/ → harmony。クロスプラットフォームの Flutter / Unity プロジェクトでは、ユーザーがいずれか（android / iphoneos）を選択する必要があります。	なし（デフォルト：プロジェクトの種類から調査）
time-range	はい	object	StartTime=<ms> EndTime=<ms> Granularity=1 GranularityUnit=<HOUR|DAY>	過去 24 時間（ユーザーが変更可能）
biz-module	いいえ	list	省略した場合は 6 つのモジュールすべてをスキャンします。指定した場合は、そのモジュールだけを分析します	6 つすべて
digest-hash	いいえ	string	ユーザーが特定の Issue をすでに把握している場合、Top-N の段階を省略して直接詳細を調査します	なし
top-n	いいえ	int	Top Issue の数	5
filter-json	いいえ	string	特定のバージョン／デバイスモデル／リージョンなどでさらに絞り込む JSON 文字列	適用なし

タイムスタンプの単位：すべての API で Unix ミリ秒を使用します。ユーザーが秒単位の値（< 1e12）を渡した場合、スクリプトによって自動的に 1000 倍されます。

biz-module の注意点：CLI の --help には従来の enum（exception / crash / lag / custom / h5JsError / h5WhiteScreen）が記載されていますが、anr / memory_leak / memory_alloc は実際にはバックエンドに転送され、機能します。このスキルは、デフォルトでユーザーが指定した 6 つのモジュールすべてをスキャンします。詳細は references/biz-module-reference.md を参照してください。

time-range の注意点：環境によっては、Granularity=60 GranularityUnit=MINUTE がバックエンドに拒否されます（Code: 200, Message: "unknown error" を返します）。必ず Granularity=1 GranularityUnit=DAY または GranularityUnit=HOUR を優先してください。

--os の注意点：CLI の --help では --os は省略可能とされていますが、実際には省略するとエラーなしで空のリストが返されます（Model.Items=[]、Total=0）。4 つの API すべてに --os を明示的に渡す必要があります。

--did の注意点：get-error の --did も --help では省略可能とされていますが、バックエンドでは暗黙的に必須です。省略すると Code: 100011 Parameter Not Enough が返されます。get-errors の Items[*].Did から取得してください（dig_issue.sh ではすでに処理されています。aliyun emas-appmonitor get-error を手動で呼び出す場合は、明示的に渡してください）。

DigestHash の 2 つの意味：get-errors は Items[*].DigestHash を返しますが、これは単一イベントのハッシュであり、渡した集約済みの --digest-hash とは異なります。次に get-error を呼び出す場合も、集約済みのハッシュ（get-issues / get-issue で使用したもの）を使い続けてください。単一イベントのハッシュに切り替えないでください。

biz-module の再利用：get-issues から Top Issue を取得するために使用した bizModule は、次の 3 つのステップ（get-issue / get-errors / get-error）でも再利用する必要があります。そうしないと、レスポンスが空になります（同じ DigestHash は 1 つの bizModule にしか存在しません）。list_top_issues.sh は各行に bm フィールドをすでに付与しているため、再利用できます。

7. コアワークフロー

flowchart TD
    Start[User request] --> DetectCtx{Workspace can infer AppKey+OS?}
    DetectCtx -- single match --> ConfirmCtx[Echo for user confirmation]
    DetectCtx -- multiple matches --> PickCtx[List candidates, let user pick]
    DetectCtx -- miss --> AskCtx[Ask user for AppKey + OS]
    ConfirmCtx --> HasHash
    PickCtx --> HasHash
    AskCtx --> HasHash
    HasHash{digestHash provided?}
    HasHash -- yes --> SingleIssue[get-issue: fetch single Issue metadata]
    HasHash -- no --> ParallelIssues[Parallel get-issues over 6 bizModules]
    ParallelIssues --> TopN[Sort by errorRate, take Top 3-5]
    TopN --> IterateTop[Iterate Top Issues]
    IterateTop --> SingleIssue
    SingleIssue --> GetErrors[get-errors: latest 3-5 samples]
    GetErrors --> PickSample["Sample policy: latest / hot device / latest affected version"]
    PickSample --> GetError[get-error: stack/threads/logs/dimensions]
    GetError --> HasCode{CWD has APP source?}
    HasCode -- yes --> CodeMatch[stack -> file + line -> diff]
    HasCode -- no --> CliReport[CLI-only diagnostic report]
    CodeMatch --> Report[Final report: issue list + root cause + fix]
    CliReport --> Report
    Report --> CallFailed{Any CLI call failed?}
    CallFailed -- yes --> CliSelfDiag["CLI self-diagnose: --log-level debug / --cli-dry-run / configure list / plugin update"]
    CallFailed -- no --> endNode[Done]
    CliSelfDiag --> endNode

7.0 実行時に Skill ディレクトリ（$SKILL_DIR）を特定する

SKILL.md が読み込まれた時点で、Agent は Skill 自身のパスを把握しています（コンテキスト内の <available_skills> にある fullPath / path フィールドを参照）。この Skill にバンドルされたリソース（scripts/ / assets/ / references/）を読み取る必要がある bash コマンドを実行する前に、Agent は必ず SKILL.md のディレクトリを SKILL_DIR に一度だけエクスポートしてください。

# The Agent fills in the absolute path of SKILL.md into the placeholder, then exports once
export SKILL_DIR="$(cd "$(dirname "<ABSOLUTE_PATH_OF_SKILL.md>")" && pwd)"

# Self-check: all three directories must exist
[[ -d "$SKILL_DIR/scripts" && -d "$SKILL_DIR/assets" && -d "$SKILL_DIR/references" ]] \
  || { echo "[ERROR] SKILL_DIR does not point to the root of this Skill: $SKILL_DIR" >&2; exit 1; }

ルール：

1. ~/.cursor/skills-cursor/... または ~/.claude/skills/... をハードコードしないでください：この Skill はリポジトリ（.agent/skills/alibabacloud-emas-apm-query/）内、またはユーザーレベルに配置される可能性があり、絶対パスはホストによって異なります。
2. 相対パスを使うために Skill ディレクトリへ cd することに依存しないでください：スクリプトは現在の作業ディレクトリ（ユーザーの APP ソースルート）に成果物を出力するため、cd するとこの動作が損なわれます。
3. bash スクリプトにはフォールバックがあります：scripts/list_top_issues.sh と scripts/dig_issue.sh は、先頭で BASH_SOURCE を使って自身の場所を自動検出するため、エクスポートされていなくても $SKILL_DIR を特定できます。SKILL.md 内のその他のインライン jq / rg コマンドを実行するには、Agent が事前に $SKILL_DIR をエクスポートする必要があります。

7.1 ステージ A：Top N（digest-hash が指定されていない場合）

scripts/list_top_issues.sh を使って、6 つの biz_modules を並列にスキャンします。

bash "$SKILL_DIR/scripts/list_top_issues.sh" \
  --app-key <AppKey> \
  --os <iphoneos|android|harmony> \
  --start-time <startMs> \
  --end-time <endMs> \
  --top-n 5 \
  --order-by ErrorRate

出力は統合された Top-N テーブルで、各行には {bm, digestHash, ec, er, edc, edr, name, type, reason} が含まれます。 フィルターを追加するには（例：「バージョン 3.5.x のみ」）、--filter-json '{"Key":"appVersion","Operator":"in","Values":["3.5.0","3.5.1"]}' を追記してください。詳細は references/filter-reference.md を参照してください。

7.2 ステージ B：単一の Issue を詳しく調査する

scripts/dig_issue.sh を使います。

bash "$SKILL_DIR/scripts/dig_issue.sh" \
  --app-key <AppKey> \
  --os <iphoneos|android|harmony> \
  --biz-module <crash|anr|lag|custom|memory_leak|memory_alloc> \
  --digest-hash <13-char Base36> \
  --start-time <startMs> --end-time <endMs> \
  --sample-size 3

出力ディレクトリ：

emas-apm-dig-<AppKey>-<DigestHash>-<epoch>/
  01-get-issue.json
  02-get-errors.json           (contains the ClientTime/Uuid/Did triples)
  samples/<Uuid>.json          (complete JSON per sample, includes Backtrace/EventLog etc.)
  report.md                    (structured markdown report)

7.3 ステージ C：コードマッピングと差分（CWD に APP ソースがある場合）

references/troubleshoot-workflow.md に従ってください。

1. プラットフォーム（Android / iOS / Harmony / RN / Flutter / Web）を特定します
2. Model.Backtrace → APP のユーザーフレームのみを残す → ソースを grep する → ファイルと行番号を特定する
3. EventLog + Controllers + Threads + CustomInfo を使ってタイムラインを補完します
4. 最小限の差分（20 行以下 + 「なぜ」を説明する 1 文）を出力します

CWD にソースが含まれていない場合は、CLI 診断レポート（Issue の概要、サンプル次元の比較、代表的なスタック）のみを出力し、「APP ソースディレクトリに切り替えると、コードレベルの位置を特定できます」というヒントを追記します。

7.4 失敗時の対応（CLI のみ）

aliyun emas-appmonitor の呼び出しが失敗した場合は、次のセルフチェックを順に実行します。

aliyun configure list                                   # 1. current profile / mode / region
aliyun plugin update                                    # 2. latest plugin
aliyun emas-appmonitor <cmd> ... --cli-dry-run          # 3. parameter serialization check
aliyun emas-appmonitor <cmd> ... --log-level debug      # 4. HTTP body + RequestId

サーバー側のデータソースを照会するようユーザーに案内しないでください。

8. 成功の検証

実行可能なコマンドと各ステップの合格／不合格基準を含む、CLI による 6 ステップの完全なセルフ検証は references/verification-method.md にあります。正しい CLI パターンと誤った CLI パターンの一覧は references/acceptance-criteria.md にあります。主な基準は次のとおりです。

1. 到達可能：get-issues の dry-run で HTTP ボディが正常に出力される
2. 空でない：いずれかの biz_module で Model.Total >= 1 となる
3. 安定：同一のパラメーターで 2 回呼び出すと、同じ Top 5 の DigestHash が返される
4. フィルターが機能する：フィルター追加後、Total が全件数以下になる
5. 3 段階のチェーン：issues → issue → errors → error で Stack を最初から最後まで取得できる
6. 診断可能：エラーを意図的に発生させたとき、出力に RequestId と ErrorCode が含まれる

9. クリーンアップ

このスキルは読み取り専用であり、クリーンアップが必要なクラウドリソースは作成しません。

ティアダウンは次の 2 つだけです。

aliyun configure ai-mode disable

# (optional) delete the local JSON directories produced by dig_issue.sh
rm -rf ./emas-apm-dig-*

10. ベストプラクティス

1. まず調査し、その後で質問します：メインフローに入る前に、references/appkey-detection.mdに従ってユーザーのワークスペース内にある SDK の初期化コードを grep し、app-key / os を推定します。最初に質問するのではなく、該当箇所が見つかった後でのみユーザーに確認します。
2. まず上位を確認し、その後で掘り下げます：最初からすべての Issue に対して dig_issue.sh を実行しないでください。まず list_top_issues.sh で Top N を集計し、その後で個々の Issue を掘り下げます。CLI 呼び出しの合計数は O(all) ではなく O(N) です。
3. 必ず --os を指定します：--help では4つすべての API で --os が任意とされていますが、省略すると結果が何も返されないままになります。必ず android / iphoneos / harmony を明示的に指定します。
4. get-error には必ず --did を指定します：--help では任意とされていますが、バックエンドでは暗黙的に必須です。get-errors のレスポンスにある Items[*].Did から取得します。
5. biz-module を再利用します：次の get-issue / get-errors / get-error 呼び出しでは、get-issues で Issue が取得されたときと同じ bizModule を使用してください。切り替えると結果が何も返されません。
6. 時間範囲は「広い」状態から「狭い」状態へ絞ります：診断は24h / Granularity=1 GranularityUnit=DAY で開始します。特定のバージョン / デバイスが見つかったら、GranularityUnit=HOUR で1～4時間に絞ります。
7. フィルターは JSON 文字列です：--filter の値全体を単一の JSON 文字列にする必要があります。手動でのエスケープミスを避けるため、jq -cn でネストした SubFilters を作成します（references/filter-reference.mdを参照）。
8. 複数アカウントのシナリオ：aliyun configure list でプロファイルを確認し、暗黙的な環境変数の切り替えに頼るのではなく、--profile <name> を明示的に指定します。
9. get-error のレスポンスは保存します：この API のレスポンスは数百 KB から数 MB に及ぶことがあります。head / tail で JSON を切り詰めないでください。まず > /tmp/emas-error-XXX.json に書き込み、その後 jq で処理します。
10. Android の難読化：a.a.a.b.c のようなクラス名が見つかった場合、コードのマッピングを試みる前に、推測するのではなくユーザーに mapping.txt を依頼します。
11. iOS がシンボル化されていない場合：Model.SymbolicStatus=false のとき、Stack には生のアドレスが多数含まれます。デバイス / バージョンの観点に限って結論を出し、dSYM がアップロードされた後で再分析します。
12. 並列実行時の QPS 制御：list_top_issues.sh には、スロットリングを避けるため sleep 0.3s が組み込まれています。6つの biz_modules をスキャンしても合計2～3秒で済むため、追加の並列処理は不要です。
13. biz-module の結果が空でもエラーではありません：harmony の anr / memory_* やトラフィックが非常に少ない AppKeys で Total=0 が返されるのは正常であり、再試行する必要はありません。
14. このスキルを逆用してデータを書き込まないでください：4つすべての API は Get* / View* です。ユーザーが「Issue のステータスを更新」または「修正済みとしてマーク」したい場合、それは UpdateIssueStatus のような書き込み API の対象であり、スコープ外です。

11. 参照リンク

ドキュメント	目的
references/cli-installation-guide.md	Aliyun CLI のインストール／設定／プラグイン／認証情報
references/appkey-detection.md	Android／iOS／Harmony／Flutter／Unity／H5 におけるユーザーのワークスペースからの AppKey と OS の特定
references/ram-policies.md	最小権限の JSON と権限エラーへの対処
references/get-issues.md	GetIssues のパラメーター／レスポンス／並び順
references/get-issue.md	GetIssue のパラメーター／レスポンス
references/get-errors.md	GetErrors のパラメーター／レスポンス
references/get-error.md	GetError のパラメーター／レスポンス
references/filter-reference.md	--filter の構造／演算子／SubFilters／ドライラン検証
references/biz-module-reference.md	6 つの biz_modules × プラットフォーム × 利用可能な filterCode の一覧
references/troubleshoot-workflow.md	スタックからソース、差分までの全フロー
references/related-commands.md	aliyun emas-appmonitor のすべてのコマンドのチートシートとスキルの範囲
references/verification-method.md	合格／不合格の基準を含む、実行可能な CLI 検証の 6 ステップ
references/acceptance-criteria.md	正しい CLI パターンと誤った CLI パターンの一覧（レビュー／セルフチェック用）
assets/system-filters/index.json	14 個の静的フィルタースナップショット（biz_module × プラットフォーム）のインデックス