/alibabacloud-emas-apm-query

name: alibabacloud-emas-apm-query
description: |
  Alibaba Cloud EMAS APM (mobile Application Performance Monitoring) issue
  troubleshooting skill. Covers the 4 read-only OpenAPIs exposed by the
  `aliyun emas-appmonitor` plugin: `get-issues` / `get-issue` / `get-errors`
  / `get-error`. Capabilities: Top-N aggregation, sample stack drill-down and
  dimension breakdowns for 6 issue types (crash / anr / lag / custom /
  memory_leak / memory_alloc), combined with the user's source code (Java /
  Kotlin / Objective-C / Swift / ArkTS / Dart / C# / JS) to produce root cause
  analysis and fix suggestions.
  Client coverage: native Android / iOS / HarmonyOS, Flutter, Unity
  (bundled to android / iphoneos / harmony; H5 is out of scope).
  Triggers: analyze app crash, troubleshoot ANR, APM crash investigation,
  list top issues, "what is this digestHash", iOS ANR Top 5, Android memory
  leak analysis, Flutter custom exception stacks, pull lag samples,
  emas appmonitor usage, sort issues by error rate, map stack to source,
  appKey problem, EMAS APM issue analysis, analyze APM issues.

alibabacloud-emas-apm-query

1. Scenario Description & Architecture

After a mobile app integrates Alibaba Cloud EMAS APM, the crash / anr / lag / custom / memory_leak / memory_alloc events it produces every day are aggregated and reported by the SDK to the backend. A typical troubleshooting workflow is:

1. **Figure out which Issues are most worth fixing**: sort by error rate / error count → pick Top 3~5 2. **Inspect what a specific Issue looks like**: fetch its aggregated metrics and affected versions 3. **Find several representative samples**: across different devices / versions / networks 4. **Read the stack + business log in a sample**: find actionable clues 5. **Compare against the app source code and propose a fix**

This skill stitches the 5 steps above into a single CLI pipeline. The entire process **only calls the 4 read-only APIs of `aliyun emas-appmonitor`**, and depends on no database / log service:

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

**Supported BizModules**: `crash` / `anr` / `lag` / `custom` / `memory_leak` / `memory_alloc` **Supported OS**: `android` / `iphoneos` / `harmony` (`harmony` does not have `anr` / `memory_*`)

2. Prerequisites

| Item | Requirement | Self-check command | | --- | --- | --- | | Aliyun CLI version | >= `3.3.3` | `aliyun version` | | Plugin | `aliyun-cli-emas-appmonitor` | `aliyun emas-appmonitor --help` | | jq | any version (required by scripts) | `jq --version` |

Full installation steps: [`references/cli-installation-guide.md`](references/cli-installation-guide.md). Recommended: enable auto plugin installation once:

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

3. Credential Pre-check

**Do NOT** print AK/SK values; just verify that an available profile exists:

aliyun configure list

The expected output contains a `current` profile whose `Mode` / `RegionId` are non-empty. If not, configure one of AK / OAuth / StsToken / RamRoleArn per [`references/cli-installation-guide.md#Configuration`](references/cli-installation-guide.md).

> **This skill never reads or forwards AK / SK field values themselves during its whole lifecycle.**

4. AI-mode Lifecycle

**Start** (before the skill runs):

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

**End** (after troubleshooting completes):

aliyun configure ai-mode disable

5. RAM Permissions

This skill only needs the 4 read-only `emasha:View*` actions (`ViewIssues` / `ViewIssue` / `ViewErrors` / `ViewError`). EMAS AppMonitor's RamCode is `emasha` and does **not** support resource-level authorization, so `Resource` is fixed to `"*"`.

For the full least-privilege JSON policy, the equivalent system policies (`AliyunEMASAppMonitorReadOnlyAccess` / `AliyunEMASAppMonitorFullAccess`), and common permission-error troubleshooting, see [`references/ram-policies.md`](references/ram-policies.md).

> **[MUST] Permission Failure Handling**: When any command or API call fails due to permission errors at any point during execution, follow this process: > 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL > 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions > 3. Pause and wait until the user confirms that the required permissions have been granted

6. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call, > ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, > passwords, domain names, resource specifications, etc.) MUST be confirmed with the > user. Do NOT assume or use default values without explicit user approval.

| Parameter | Required | Type | Description | Default | | --- | --- | --- | --- | --- | | `app-key` | Yes | int64 | EMAS APP Key (typically 9+ digits). **Prefer to infer from SDK initialization code in the current workspace** (see the 6 rule families in [`references/appkey-detection.md`](references/appkey-detection.md)); if exactly one match is found, echo it and wait for user confirmation; if multiple, list candidates and let the user pick; on miss, ask the user to provide it manually. | None (default: probed from workspace) | | `os` | Yes | enum | `android` / `iphoneos` / `harmony` (H5 goes to `h5`, which is out of scope). **Inferred together with `app-key` from the project type**: `build.gradle` / `AndroidManifest.xml` → `android`; `*.xcodeproj` / `Podfile` → `iphoneos`; `module.json5` + `ets/` → `harmony`. For cross-platform Flutter / Unity projects, the user MUST pick one (`android` / `iphoneos`). | None (default: probed from project type) | | `time-range` | Yes | object | `Star