alibabacloud-emas-apm-query

What this skill does

# 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:

```bash
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:

```bash
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):

```bash
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):

```bash
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 | `StartTime=<ms> EndTime=<ms> Granularity=1 GranularityUnit=<HOUR\|DAY>` | Last 24 hours (user-overridable) |
| `biz-module` | No | list | If omitted, all 6 modules are scanned; if specified, only that module is analyzed | All 6 |
| `digest-hash` | No | string | If the user already knows a specific Issue, skip the Top-N stage and drill down directly | None |
| `top-n` | No | int | Number of Top issues | `5` |
| `filter-json` | No | string | Further narrow down (specific version / device model / region ...), a JSON string | Not applied |

**Timestamp unit**: every API uses **Unix milliseconds**. If the user passes a value in seconds (< 1e12), the scripts will automatically multiply by 1000.

**`biz-module` pitfall**: the CLI `--help` lists the legacy enum (`exception / crash / lag / custom / h5JsError / h5WhiteScreen`); however, **`anr / memory_leak / memory_alloc` are actually forwarded to the backend** and work. This skill scans all 6 modules requested by the user by default; see [`references/biz-module-reference.md`](references/biz-module-reference.md).

**`time-range` pitfall**: in some environments `Granularity=60 GranularityUnit=MINUTE` is rejected by the backend (returns `Code: 200, Message: "unknown error"`). **Always prefer** `Granularity=1 GranularityUnit=DAY` or `GranularityUnit=HOUR`.

**`--os` pitfall**: the CLI `--help` marks `--os` as optional, but in practice **omitting it returns an empty list without error** (`Model.Items=[]`, `Total=0`). All 4 APIs must pass `--os` explicitly.

**`--did` pitfall**: `get-error`'s `--did` is also marked optional in `--help`, but is **implicitly required by the backend**. Omitting it returns `Code: 100011 Parameter Not Enough`. Take it from `get-errors`' `Items[*].Did` (already handled by `dig_issue.sh`; when calling `aliyun emas-appmonitor get-error` manually, pass it explicitly).

**Dual semantics of `DigestHash`**: `get-errors` returns `Items[*].DigestHash`, which is the hash of a **single event**, different from the **aggregated** `--digest-hash` you passed in. When calling `get-error` next, still use the **aggregated** hash (the one you used in `get-issues` / `get-issue`); do not switch to the single-event hash.

**Reuse `biz-module`**: whichever `bizModule` was used to obtain a Top Issue from `get-issues` must be reused for the next three steps (`get-issue` / `get-errors` / `get-error`); otherwise the response will be empty (the same `DigestHash` exists under only one bizModule). `list_top_issues.sh` already attaches a `bm` field to each row so it can be reused.

## 7. Core Workflow

```mermaid
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[Pa