{"id":"437eda04-3ab2-410a-b809-e01fb95f47f9","entityType":"agent","slug":"clawhub-sdk-team-alibabacloud-cms-manage","name":"alibabacloud-cms-manage","canonicalUrl":"https://www.xpersona.co/agent/clawhub-sdk-team-alibabacloud-cms-manage","canonicalPath":"/agent/clawhub-sdk-team-alibabacloud-cms-manage","generatedAt":"2026-10-11T07:41:14.690Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:19:34.533Z","emptyReason":null},"description":"Entry skill for the aliyun CLI distribution of CloudMonitor (CMS). Use when the user mentions aliyun cms2, CloudMonitor, CMS commands, or any CMS module operation such as Integration Policy/Center, APM, RUM, Prometheus Service, Recording rule, alert rule, alert template, alert history, event hub, SLS event, PromQL, cloud resource, service observability, monitoring onboarding, metric query, etc.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-cms-manage","sourceUrl":"https://clawhub.ai/sdk-team/alibabacloud-cms-manage","homepage":"https://clawhub.ai/sdk-team/skills/alibabacloud-cms-manage","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/sdk-team/alibabacloud-cms-manage","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/sdk-team/skills/alibabacloud-cms-manage","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"alibabacloud-cms-manage technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:19:34.533Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:19:34.533Z","emptyReason":null},"stars":null,"forks":null,"downloads":1148,"packageName":null,"latestVersion":"1.0.5","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:19:34.461Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T05:19:34.533Z","lastCrawledAt":"2026-10-11T05:19:34.461Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T05:19:34.461Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.5","createdAt":"2026-10-09T06:39:21.028Z","changelog":"alibabacloud-cms-manage 1.0.5 - Added a new reference manifest file (references/manifest.json). - Updated multiple documentation and reference files for onboarding and integrations. - Removed obsolete skill-card.md. - Documentation and modules aligned for improved process clarity and maintainability.","fileCount":23,"zipByteSize":131221},{"version":"1.0.4","createdAt":"2026-08-29T05:52:38.281Z","changelog":"- Added new reference: integration-management, expanding integration-related documentation. - Updated onboarding references for batch, cloud, cs, and ecs to improve clarity and structure. - Improved integration and Prometheus management documentation. - Clarified and strengthened skill conventions on command parameter handling and choice presentation. - Removed outdated skill-card.md for consistency.","fileCount":22,"zipByteSize":131102},{"version":"1.0.3","createdAt":"2026-08-27T02:00:41.547Z","changelog":"alibabacloud-cms-manage v1.0.3 - Major documentation refactor: expanded and revised conventions, prerequisites, structured user input, and parameter confirmation rules. - Added multiple new reference documents covering onboarding workflows, Prometheus, ECS, cloud/on-prem onboarding, integration diagnosis, and Grafana rules. - Updated global conventions: clarified when regions and other parameters must be explicitly confirmed and how structured choices and recommendations are presented. - Removed deprecated documentation files and reorganized references for improved clarity and maintainability.","fileCount":21,"zipByteSize":128659},{"version":"1.0.2","createdAt":"2026-06-16T02:58:28.321Z","changelog":"alibabacloud-cms-manage v1.0.2 - Requires explicit user confirmation for all write and high-impact create operations, with concise summaries and clear approval (no specific phrase required). - Region selection for `entity query --source CloudResource` now defaults to all regions unless the user explicitly specifies a region. - Improved handling for mutually exclusive user choices: uses structured selection tools when available; falls back to plain-text lists otherwise. - Clarifies that for any uncertain parameters (region, workspace, resource type, etc.), values must always be explicitly provided by the user; never inferred or guessed. - On workspace selection, requires explicit user choice—workspace discovery pattern is not a permission to auto-select. - Results from paginated or truncated queries are never treated as complete until all pages are fetched or total count is reached. Other changes: - AI-Mode instructions and redundant instructions were removed. - The skill card file (skill-card.md) was removed.","fileCount":13,"zipByteSize":69466},{"version":"1.0.1","createdAt":"2026-06-02T07:52:39.015Z","changelog":"- Added requirement for explicit human confirmation before any destructive/mutating operations (update, delete, patch, stop, start, etc.); write commands are no longer auto-executed. - Improved CLI upgrade instructions: for outdated CLIs, now prompts user to confirm manual upgrade before re-checking version if auto-upgrade is unavailable. - Removed obsolete skill-card documentation. - Updated module reference and related API documentation.","fileCount":13,"zipByteSize":57142},{"version":"1.0.0","createdAt":"2026-05-29T10:20:47.401Z","changelog":"Initial release: Entry skill for managing Alibaba Cloud CloudMonitor (CMS) via the aliyun CLI. - Provides detailed prerequisite checks for CLI installation, version, and plugin availability. - Documents AI-Mode setup and teardown for improved agent interactions. - Strictly enforces use of `aliyun cms2` without fallback to legacy commands or workarounds. - Includes module routing based on user keywords for integration, alerting, APM, RUM, events, notifications, and more. - Outlines error handling tips and output conventions to ensure smooth command execution.","fileCount":13,"zipByteSize":56145}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-cms-manage","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-cms-manage` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/sdk-team/alibabacloud-cms-manage before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T07:41:14.687Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-cms-manage/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:19:34.533Z","emptyReason":null},"readme":"Skill: alibabacloud-cms-manage\n\nOwner: sdk-team\n\nSummary: Entry skill for the aliyun CLI distribution of CloudMonitor (CMS). Use when the user mentions aliyun cms2, CloudMonitor, CMS commands, or any CMS module operation such as Integration Policy/Center, APM, RUM, Prometheus Service, Recording rule, alert rule, alert template, alert history, event hub, SLS event, PromQL, cloud resource, service observability, monitoring onboarding, metric query, etc.\n\nTags: latest:1.0.5\n\nVersion history:\n\nv1.0.5 | 2026-10-09T06:39:21.028Z | auto\n\nalibabacloud-cms-manage 1.0.5\n\n- Added a new reference manifest file (references/manifest.json).\n- Updated multiple documentation and reference files for onboarding and integrations.\n- Removed obsolete skill-card.md.\n- Documentation and modules aligned for improved process clarity and maintainability.\n\nv1.0.4 | 2026-08-29T05:52:38.281Z | auto\n\n- Added new reference: integration-management, expanding integration-related documentation.\n- Updated onboarding references for batch, cloud, cs, and ecs to improve clarity and structure.\n- Improved integration and Prometheus management documentation.\n- Clarified and strengthened skill conventions on command parameter handling and choice presentation.\n- Removed outdated skill-card.md for consistency.\n\nv1.0.3 | 2026-08-27T02:00:41.547Z | auto\n\nalibabacloud-cms-manage v1.0.3\n\n- Major documentation refactor: expanded and revised conventions, prerequisites, structured user input, and parameter confirmation rules.\n- Added multiple new reference documents covering onboarding workflows, Prometheus, ECS, cloud/on-prem onboarding, integration diagnosis, and Grafana rules.\n- Updated global conventions: clarified when regions and other parameters must be explicitly confirmed and how structured choices and recommendations are presented.\n- Removed deprecated documentation files and reorganized references for improved clarity and maintainability.\n\nv1.0.2 | 2026-06-16T02:58:28.321Z | auto\n\nalibabacloud-cms-manage v1.0.2\n\n- Requires explicit user confirmation for all write and high-impact create operations, with concise summaries and clear approval (no specific phrase required).\n- Region selection for `entity query --source CloudResource` now defaults to all regions unless the user explicitly specifies a region.\n- Improved handling for mutually exclusive user choices: uses structured selection tools when available; falls back to plain-text lists otherwise.\n- Clarifies that for any uncertain parameters (region, workspace, resource type, etc.), values must always be explicitly provided by the user; never inferred or guessed.\n- On workspace selection, requires explicit user choice—workspace discovery pattern is not a permission to auto-select.\n- Results from paginated or truncated queries are never treated as complete until all pages are fetched or total count is reached.\n\nOther changes:\n- AI-Mode instructions and redundant instructions were removed.\n- The skill card file (skill-card.md) was removed.\n\nv1.0.1 | 2026-06-02T07:52:39.015Z | auto\n\n- Added requirement for explicit human confirmation before any destructive/mutating operations (update, delete, patch, stop, start, etc.); write commands are no longer auto-executed.\n- Improved CLI upgrade instructions: for outdated CLIs, now prompts user to confirm manual upgrade before re-checking version if auto-upgrade is unavailable.\n- Removed obsolete skill-card documentation.\n- Updated module reference and related API documentation.\n\nv1.0.0 | 2026-05-29T10:20:47.401Z | auto\n\nInitial release: Entry skill for managing Alibaba Cloud CloudMonitor (CMS) via the aliyun CLI.\n\n- Provides detailed prerequisite checks for CLI installation, version, and plugin availability.\n- Documents AI-Mode setup and teardown for improved agent interactions.\n- Strictly enforces use of `aliyun cms2` without fallback to legacy commands or workarounds.\n- Includes module routing based on user keywords for integration, alerting, APM, RUM, events, notifications, and more.\n- Outlines error handling tips and output conventions to ensure smooth command execution.\n\nArchive index:\n\nArchive v1.0.5: 23 files, 131221 bytes\n\nFiles: assets/related_apis.yaml (8801b), references/ai.md (11696b), references/alerting.md (34367b), references/apm-metrics.md (10501b), references/apm.md (43561b), references/batch-onboarding-workflow.md (34822b), references/cloud-onboarding.md (12743b), references/cs-onboarding.md (24522b), references/ecs-onboarding.md (11396b), references/event-hub.md (4265b), references/grafana-dashboard-rules.md (2263b), references/integration-common.md (59818b), references/integration-diagnosis.md (24554b), references/integration-management.md (9434b), references/manifest.json (19b), references/probe-metric-agent-spec.md (1356b), references/prometheus-management.md (12181b), references/ram-policies.md (16471b), references/rum.md (17667b), references/umodel-metrics.md (4510b), skill-card.md (2288b), SKILL.md (29698b), _meta.json (142b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: alibabacloud-cms-manage\ndescription: |\n Entry skill for the aliyun CLI distribution of CloudMonitor (CMS).\n Use when the user mentions aliyun cms2, CloudMonitor, CMS commands,\n or any CMS module operation such as Integration Policy/Center, APM, RUM,\n Prometheus Service, Recording rule, alert rule, alert template, alert history,\n event hub, SLS event, PromQL, cloud resource, service observability,\n monitoring onboarding, metric query, etc.\nlicense: Apache-2.0\ncompatibility: aliyun-cli>=3.3.15\nmetadata:\n domain: aiops\n owner: cms\n contact: cms@alibaba-inc.com\n---\n\n# CMS CLI — `aliyun cms2`\n\n## Prerequisite Check\n\n> **Once per session**: perform this prerequisite check only on the **first** invocation of this skill in a conversation. If all checks already passed earlier in the same session, skip directly to the relevant module.\n\n1. **Check `aliyun` exists** — `which aliyun` (macOS/Linux) or `where aliyun` (Windows).\n - Not found → ask the user to install the aliyun CLI first: . Stop and wait.\n\n2. **Check CLI version** — run `aliyun version`. Minimum required: **3.3.15** (see `compatibility` in frontmatter).\n\n > ⚠️ Compare version segments as **integers** (semver): 3.3.4 < 3.3.15 because 4 < 15.\n > Shell verification: `printf '%s\\n' \"3.3.15\" \"$(aliyun version)\" | sort -V | head -1`\n > If the output equals the current version, the requirement is NOT met.\n\n - Version OK → go to step 3.\n - Version too old or unrecognized →\n 1. Run `aliyun upgrade --help` to test whether the `upgrade` subcommand exists.\n - Available → run `aliyun upgrade -y` to update to the latest version automatically, then re-check `aliyun version`.\n 2. If `upgrade` not available → ask the user to upgrade manually following the official guide: . Wait for the user to confirm the upgrade is complete, then re-check `aliyun version`.\n 3. If upgrade succeeded → go to step 3.\n 4. If upgrade failed → ask the user to upgrade manually: . Stop and exit.\n\n3. **Check `cms2` plugin** — run `aliyun cms2 --help`.\n - Help output OK → continue to **Credentials**.\n - `unknown command` / missing → **stop immediately**, output the error report below (append CLI version, OS, and error message), and make **no further CLI calls**.\n\n---\n\n## Credentials\n\n`aliyun cms2` reuses the aliyun CLI credential system (`aliyun configure`).\nUse `--profile ` to switch profiles.\n\n## Observability\n\nUpon loading this skill, generate a random session ID (32-char lowercase hex string) once per session...\n\nFor every aliyun cms2 command, append:\n--user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-cms-manage/{session-id}\"\n\nLocal utility commands (e.g. `version`, `configure`, `plugin`, `--help`) do not support this flag and are excluded.\n\n## Global Conventions\n\n**Hard constraint**: fallback to `aliyun cms`, other API versions, or any workaround is strictly prohibited.\n\n> **Run `aliyun cms2 [subcommand] --help` before first use of a subcommand in a session** to get the full flag list and examples. Once the help for the same subcommand has been read in the current session and the command shape has not changed, reuse that knowledge instead of repeating the help call. A named subcommand's `--help` / `--show-schema` / `--show-example-body` is the authority for that command's flags, body envelope, response fields, and environment behaviour — do not search other skill files for a copy of those fields.\n\n- **Prefer `-o text`** (default) to reduce token consumption for list/get; use `-o json` only when the output is parsed field by field rather than read.\n- **Addon-release `values`**: expand each field's `fieldPath` into nested JSON as specified in [Addon Values Defaults](references/integration-common.md#addon-values-defaults-hard-requirement). Do not write a dotted `fieldPath` as one literal key. How to pick `--env-type`, where child fields sit on create vs update, and when a subset is (or is not) a valid body, are in that section.\n- **Region parameter required for mutating and detail commands**: unless otherwise specified by a module-specific rule, all `create`, `update`, `delete`, and single-resource `get`/detail commands MUST include the `--region` parameter so the request is routed to the correct backend OpenAPI endpoint. Omitting `--region` on these commands may cause routing failures or operate against an unintended region, and the error can name something else entirely — `integration policy create` returns `status 400: The workspace can not be created` even when the workspace exists and the body is valid. This does not apply to `list`/query commands that intentionally span multiple regions (e.g. `entity query --source CloudResource` all-region queries). Requiring the flag is not permission to choose its value — resolve it per [Region Confirmation Gate](#region-confirmation-gate-hard-requirement).\n- **One choice, one question**: every enumerated choice (region, workspace, policy, addon, scope mode, tag match mode, and any other mutually exclusive parameter) is asked as one question carrying **all** of its options. Never split them across questions or into a `（续）...` continuation, and never drop the ones that do not fit — a split turns one choice into two answers that can conflict or be left incomplete, and a truncated list hides valid choices entirely. When the structured input form cannot render every option, ask as plain text and spell out every option with its explanation in the question body. A mutually exclusive choice stays single-select; only a genuinely multi-valued one (several regions) is multi-select. A prompt may carry several distinct choices, each its own question. Put any recommended value directly in the option label (for example `(Recommended)`); recommendations are advisory only and do not permit cloud-side writes unless another rule permits defaulting or the user confirms.\n- **Human confirmation required for writes and high-impact creates**: before any command that creates or changes cloud-side state (`create`, `update`, `delete`, `patch`, `start`, `stop`, etc.), show a concise confirmation summary and the exact command, ask whether the user confirms execution, and wait for a clear affirmative answer. The summary must include the operation, target resource identifiers, expected impact, and notable risks or irreversible effects when applicable. Do not require an exact phrase or long confirmation text; a clear affirmative answer such as \"yes\", \"confirm\", \"proceed\", or \"确认\" is sufficient approval. Skip confirmation only for dry-run, preview-only, or read-equivalent creates with no cloud-side impact; if uncertain, require confirmation.\n- **Uncertain parameters must be explicitly answered by the user**: for any parameter whose value is not explicitly provided or cannot be reliably determined (e.g. `region`/`regionId`, workspace, policy, `resourceGroup`, tag, resource scope, `addon`/`addonName`, resource type, cloud product/service name, onboarding configuration options, etc.), ask the user for a clear answer before proceeding. Never fabricate, guess, infer from defaults/history, or arbitrarily choose one value. A module-specific reference may define narrow exceptions — for the integration module they are listed in [references/integration-common.md](references/integration-common.md#general-conventions). Changing an existing addon release's settings is an unrehearsable write: follow [Addon Release Config Update](references/integration-common.md#addon-release-config-update-hard-requirement).\n- **A discovery query is not an answer**: a read command (`workspace list`, `entity query`, `policy list`, `sts get-caller-identity`, etc.) only builds the candidate set you present, and its output never becomes the user's answer — not when it returns a single candidate, not when a naming convention makes the value derivable, and not when an earlier turn of the session used one. \"Reliably determined\" means the user's own words or the resource they named pinned the value, not that the query happened to be unambiguous.\n- **Name-to-ID lookup must match exactly**: when looking up a region ID, workspace ID, integration policy ID, resource group ID, resource type value, or cloud product/service name/code by name, if no exact match is found in the query results, do **not** silently pick an arbitrary value as a substitute. Instead, report the mismatch to the user and ask them to confirm or provide the correct value.\n\n### Region Confirmation Gate (Hard Requirement)\n\nApplies to **every** module and to every command that takes `--region` or a `region`/`regionId` body field. Settle the region **before** the workspace, since workspace verification is region-scoped.\n\nList/query commands omit `--region` only when a module rule says the call is all-region. Omitting the flag is not all-region: the CLI supplies the profile default. Mutating and detail commands must carry it per [Region parameter required](#global-conventions).\n\nThere are exactly three legitimate sources for the value:\n\n1. The user stated it in the current request — not an earlier unrelated turn of the same session.\n2. The user picked it from a candidate list you presented, and you waited for that answer before running the next command.\n3. The host injected it as runtime context (the console session's current region). Say which region you are operating on before using it.\n\nAnything else is a violation, including: a CLI profile / `aliyun configure` / `ALIYUN_REGION` default, or an omitted required `--region`; the `cn-hangzhou` of docs and examples, or a region only stated in narration; splitting `default-cms-{userId}-{regionId}` (or any workspace name); passing `controlRegionId`.\n\nA module may bind `--region` to the `regionId` of a resource the user already confirmed (named cluster, workspace that already passed this gate, instance). That is still Source 1 or 2. Module references do not loosen this.\n\n**If Source 1 and 2 are absent**, present the region as a choice per [One choice, one question](#global-conventions) and stop. Gather candidates with `aliyun cms2 meta regions` and offer every `regionId` (never `showName` or `controlRegionId`); only consuming that output is wrong. Source 3, when present, is a recommended option only — it routes the call and does not decide scope. Onboarding region scope is collected by [Resource Scope Selection Gate](references/integration-common.md#resource-scope-selection-gate-hard-requirement); do not ask a second region question here.\n\n`controlRegionId` is the control-plane region and may differ for dedicated / exclusive locations — never pass it as `--region`.\n\n### Workspace Confirmation Gate (Hard Requirement)\n\nApplies to **every** module and to every command that takes `--workspace` or a `workspace` body field. There are exactly three legitimate sources for the value:\n\n1. The user stated it in the current conversation. Verify it exists in the target region by exact `workspaceName` match; no exact match → report and ask, never substitute a near match.\n2. The user picked it from a candidate list you presented, and you waited for that answer before running the next command.\n3. The environment supplied it as runtime context (e.g. the console session the skill runs inside) and its region matches the target region. Say which workspace you are operating on before using it.\n\nAnything else is a violation: adopting the single row `aliyun cms2 workspace list` returned, picking the `default-cms-{userId}-{regionId}` entry because it looks like the account default, assembling that name from `aliyun sts get-caller-identity` plus a region, or reusing a workspace from an earlier unrelated request in the same session.\n\nSo `aliyun cms2 workspace list` remains the right way to gather candidates — only consuming its output instead of presenting it is wrong. Mark the best candidate `(Recommended)` inside the option per [One choice, one question](#global-conventions), then stop and wait.\n\nModule references do not loosen this. Where one gives `default-cms-{userId}-{regionId}` as the workspace's \"default format\" or builds it from an account ID and a region, that describes how the account's default workspace is named — it is the candidate to recommend, never permission to skip the question.\n\n## Pagination & Query Failure Handling\n\n- **Paginate to completion**: for every `list` command that supports `--next-token`, keep querying until no `nextToken` remains or accumulated count ≥ `totalCount`. Do not trust the first page as complete when pagination metadata indicates more data.\n- **Page size on paginated `list`**: when the command accepts `--max-results`, pass `100` and then paginate to completion. **This document wins over `--help`**: do not rely on the omitted-flag default. `policy list --help` says 30 (max 100) but omitting it can return `maxResults: 100`; `prometheus instance list` omitted default is 30. 20 pages × 30 can truncate a large list.\n- **Accumulated count ≥ totalCount**: stop even if `nextToken` is non-empty or `truncated=true`; `totalCount` is the stronger signal.\n- **Empty page with satisfied totalCount**: stop even if `nextToken` is present.\n- **Token loop protection**: track seen tokens; stop on repeat and report as partial.\n- **Page limit**: default 20 pages; report partial if reached.\n- **Truncated results**: do not conclude absence from partial results. Use filters (`--search`, `--query`, `--policy-name`, etc.) or paginate fully.\n- **Transient query failure**: retry once on a transient server-side error (`DEADLINE_EXCEEDED`, timeout); if it still fails, mark as `Unknown`/`QueryFailed` — do not treat as healthy or unhealthy.\n\n## Error Handling\n\nError codes and actions are listed in `aliyun cms2 --help`. Additional tips:\n\n- `InvalidJSON` usually means malformed `--body`; validate with `jq . <<<''` before passing to the CLI.\n- `--body and stdin are mutually exclusive; specify only one` — means both `--body` (or `--file`) and stdin data were provided. Fix: keep only one input source. In agent/CI environments where stdin may be a pipe, append `< /dev/null` to the command to ensure stdin is empty.\n\n## Output Language and Terminology\n\n- Write user-facing explanations, analysis, recommendations, summaries, and conclusions in the user's language; default to Simplified Chinese when that language is unclear or mixed. Follow a mid-conversation switch from that point on, and let an explicit instruction about output language override both.\n- Question prompts, option labels, table headers, and reports are user-facing text too — phrase them in the answer language even where a reference file spells them out in one language.\n- CLI command names, flags, API paths, JSON field names, enum values, resource IDs, metric names, and log/error messages MUST remain verbatim English/code, whatever the answer language.\n- Answering in English: use the Glossary's English column as the canonical vocabulary rather than inventing synonyms.\n- Answering in Chinese: use the Glossary's Chinese terms in all prose, never leaving a mapped term in English. Write `中文（English）` on first mention only when it disambiguates, then the Chinese term alone. Before sending, scan for mapped English terms and replace them, except inside code, commands, JSON fields, IDs, or quoted CLI output.\n\nExamples (Chinese answers):\n- Good: `接入配置（AddonRelease，CLI 命令为 addon-release）`\n- Good: `查询接入配置状态：aliyun cms2 integration addon-release list ...`\n- Bad: `all releases are Ready`\n- Better: `所有接入配置均 Ready`\n\n## Glossary\n\n| English | 中文 |\n|----------------------------------------|-----------------|\n| Cloud Monitor / CMS | 云监控 |\n| Workspace | 工作空间 |\n| Application Monitoring / APM | 应用监控 |\n| RUM | 用户体验监控 |\n| Synthetic Monitoring / Synthetic | 云拨测 |\n| CloudResource | 云资源 |\n| EntityStore | 实体仓库 |\n| Entity | 实体 |\n| Integration Policy / policy | 接入策略 |\n| Addon / addon | 组件 |\n| Addon Catalog | 组件目录 |\n| AddonRelease / addon release / release | 接入配置 |\n| Collector | 采集器 |\n| Prometheus View | Prometheus 聚合视图 |\n| AggTaskGroup | 聚合任务 |\n| Delivery Task | 数据投递任务 |\n| Alert Rule | 告警规则 |\n| Alert Template | 告警模板 |\n| Alert History | 告警历史 |\n| Notification Channel | 通知渠道 |\n| Contact | 联系人 |\n| Event Hub | 事件中心 |\n| Metric Meta | 指标元数据 |\n| ClusterCollector | 集群采集器 |\n| NodeCollector | 节点采集器 |\n| Cluster probe | 集群探针 |\n| Metric drop | 指标废弃 |\n| CMS resource tag | CMS 资源标签 |\n| Grafana workspace | Grafana工作区 |\n\n## Metadata Query Mapping\n\n| What You Need | How to Get It |\n|--------------|---------------|\n| **Metric business metadata** (namespaces & product codes via `meta namespaces`; metric name, type, unit, dimensions via `meta metrics`) | `meta namespaces` / `meta metrics` |\n| **Prometheus labels, values & series inspection** | `metric promql labels` / `label-values` / `series` |\n\nIntegration-module lookups (resource metadata, onboarding status, policy-scoped Kubernetes resources, Prometheus instance by policy) live in [references/integration-common.md](references/integration-common.md#metadata-query-mapping).\n\n## Module Routing\n\n| User Intent Keywords | Commands | Module |\n|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|\n| onboarding, monitoring addon, policy, integration, addon release, integration resource, Kubernetes resource list, Namespace resources under policy, resources managed by policy, teardown, offboarding — **common rules, load for every onboarding operation** | `integration` `integration resource` | [references/integration-common.md](references/integration-common.md) |\n| container onboarding, ACK/ACS/ASI cluster onboarding, cluster fleet audit, which clusters are not onboarded | `integration` `entity query` | [references/cs-onboarding.md](references/cs-onboarding.md) (+ integration-common.md) |\n| ECS host onboarding, ECS fleet audit, NodeCollector | `integration` `entity query` | [references/ecs-onboarding.md](references/ecs-onboarding.md) (+ integration-common.md) |\n| cloud service onboarding, RDS/SLB/ALB/Redis/MongoDB/PolarDB onboarding, cloud resource fleet audit | `integration` `entity query` | [references/cloud-onboarding.md](references/cloud-onboarding.md) (+ integration-common.md) |\n| batch cloud service metric onboarding, batch onboarding, cloud-batch-metrics | `integration` `meta` `entity query` | [references/batch-onboarding-workflow.md](references/batch-onboarding-workflow.md) (+ integration-common.md) |\n| integration policy diagnosis, health-check, troubleshoot policy, scrape config, ServiceMonitor/PodMonitor/custom collection diagnosis, `custom-discover-` (a release name — read `discoverType` before treating it as a custom-job), job target | `integration check-scrape-config` `integration job-target` `integration check-collector-target` `integration resource` `integration dashboard` | [references/integration-diagnosis.md](references/integration-diagnosis.md) |\n| metric drop, drop metrics, dropMetrics, 指标废弃, 丢弃指标, 废弃指标, cluster probe metric-agent | `integration collector` `integration addon-release` | [references/integration-management.md](references/integration-management.md) (+ integration-common.md) |\n| add / change / remove CMS resource tags, 打标签, 修改标签, 删除标签, CMS resource tags, application service (APM/RUM) tags | `tag` | [references/integration-management.md](references/integration-management.md) (+ integration-common.md) |\n| Prometheus view, Prometheus aggregation view, create Prometheus aggregation view, Prometheus view create, Prometheus aggregation view diagnosis, Prometheus aggregation view health check, sub-instance status | `prometheus view` | [references/prometheus-management.md](references/prometheus-management.md) |\n| workspace, workspace create, workspace get, workspace list, workspace update, workspace delete | `workspace` | `aliyun cms2 workspace --help` |\n| entity, entity query, CloudResource, EntityStore, cloud resource query, entity store query, resource metadata, instance details | `entity query` | `aliyun cms2 entity --help` |\n| Prometheus instance, recordingRule, recording rule, AggTaskGroup | `prometheus instance` `prometheus recording-rule` | `aliyun cms2 prometheus --help` |\n| meta, metric metadata, product code, meta-format | `meta metrics` `meta namespaces` | `aliyun cms2 meta --help` |\n| metric, metric query, basic metrics, PromQL, promql query, label values, series | `metric basic` `metric promql` | `aliyun cms2 metric --help` |\n| alert, rule, alert rule, alert template, alert history, patch, create rule, manage rule | `alert rule` `alert template` `alert history` | [references/alerting.md](references/alerting.md) |\n| APM measureCode, group/filter/groupBy, baseUnit/displayUnit | `alert rule` (APM type) | [references/apm-metrics.md](references/apm-metrics.md) |\n| UModel metricSet, K8s pod metric, entity-based alert | `alert rule` (UModel type) | [references/umodel-metrics.md](references/umodel-metrics.md) |\n| notification, contact, robot, webhook, notification recipients, dingTalk, bots, lark, weChat work | `notification-channel contact` `notification-channel robot` `notification-channel webhook` | [references/alerting.md](references/alerting.md) |\n| event, event-hub, alert event, SLS event, incident | `event-hub` | [references/event-hub.md](references/event-hub.md) |\n| Grafana, Grafana workspace, managed Grafana instance, create/query/update/delete Grafana workspace | `grafana workspace` | `aliyun cms2 grafana workspace --help` |\n| Grafana dashboard authoring, dashboard JSON, panel, PromQL panel, dashboard variables, data source placeholder | `meta metrics` `metric promql` `integration storage` | [references/grafana-dashboard-rules.md](references/grafana-dashboard-rules.md) |\n| APM, application monitoring, agent install, Java agent, Golang agent, Python agent, Node.js agent, PHP agent, .NET agent, ack-onepilot, OpenTelemetry onboarding, K8s/ACK/ACS container onboarding, ECS host application onboarding, LicenseKey, proprietary agent, instgo, aliyun-bootstrap, probe setup, apm onboarding | `apm service` `apm configuration` | [references/apm.md](references/apm.md) |\n| AI observability, Dify, LangChain, LangGraph, DashScope, AgentScope, OpenAI, Coze, OpenClaw, CoPaw, Hermes, LLM monitoring, AI tracing, AI agent monitoring, custom instrumentation | `apm service` `apm configuration` `integration addon` | [references/ai.md](references/ai.md) |\n| RUM, Real User Monitoring, User Experience Monitoring, frontend monitoring, web monitoring, H5, mobile app monitoring, Android crash, iOS crash, JS error, page performance, miniapp monitoring, create RUM app, RUM SDK, pid, serviceId, endpoint | `rum service` `rum configuration` | [references/rum.md](references/rum.md) |\n| resource group query | `resource-group` | `aliyun cms2 resource-group --help` |\n\nCommands not listed above — see `aliyun cms2 --help`.\n\nFile v1.0.5:_meta.json\n\n{\n \"ownerId\": \"kn74p5w8ywv6prh40g0s82gmqh83nw54\",\n \"slug\": \"alibabacloud-cms-manage\",\n \"version\": \"1.0.5\",\n \"publishedAt\": 1791527961028\n}\n\nFile v1.0.5:references/ai.md\n\n# AI Observability Module\n\n> Global conventions (credentials, output format, error codes, command prefix, distributions) — see [../SKILL.md](../SKILL.md).\n> Run `aliyun cms2 apm --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard AI applications (LLM-based services, AI Agents, custom instrumented apps) into CMS Application Monitoring. Uses `aliyun cms2` CLI to initialize APM infrastructure, retrieve access credentials, and generate framework-specific configuration.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported AI frameworks.\n\n**Out-of-Scope**: Model fine-tuning or training observability; GPU monitoring (see `cloud-acs-ecs-gpu` addon).\n\n---\n\n## Execution Safety Rules\n\nFollow the same Two-Phase Execution Protocol as [apm.md — Execution Safety Rules](apm.md#execution-safety-rules).\n\n**Operations that do NOT require confirmation** (execute directly):\n- Read-only commands: `get`, `list`, `--help`\n- CMS backend resource creation: `apm configuration create`, `apm service create`\n- Retrieving credentials: `apm configuration get`\n- Fetching addon templates: `integration addon get`\n\n**Operations that REQUIRE confirmation** (must use Two-Phase Protocol):\n- Deleting service records: `apm service delete`\n- Modifying user application startup scripts or Dockerfiles\n\n---\n\n## Supported Frameworks\n\n| Framework | Addon Name | Protocols | Underlying Agent |\n|-----------|-----------|-----------|-----------------|\n| **Dify** | `ai-dify` | opentelemetry | Dify 控制台内置 OTel 配置 |\n| **LangChain/LangGraph** | `ai-langchain-langgraph` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **DashScope** | `ai-dashscope` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **AgentScope** | `ai-agentscope` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **OpenAI** | `ai-openai` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **Coze** | `ai-coze` | arms-ecs, arms-ack, opentelemetry | Golang（arms-ecs: instgo, arms-ack: ack-onepilot） |\n| **OpenClaw** | `ai-openclaw` | opentelemetry | 专用 installer 脚本 |\n| **CoPaw** | `ai-copaw` | opentelemetry | 专用 installer 脚本 |\n| **Hermes** | `ai-hermes` | opentelemetry | 专用 installer 脚本 |\n| **自定义埋点** | `ai-custom-instrumentation` | agent-extension, manual | ARMS 探针扩展 / 手动 OTel SDK |\n\n**Protocol legend**:\n- `arms` — 自研 Python Agent (通用环境), serviceType = `TRACE`\n- `arms4cs` — 自研 Python Agent (容器环境), serviceType = `TRACE`\n- `arms-ecs` / `arms-ack` — 自研探针 (按部署环境区分), serviceType = `TRACE`\n- `opentelemetry` — OpenTelemetry 协议, serviceType = `XTRACE`\n- `agent-extension` / `manual` — 自定义埋点, serviceType = `TRACE`\n\n---\n\n## CLI Commands Reference\n\n| Command | Purpose | Key Flags |\n|---------|---------|-----------|\n| `apm configuration create` | Initialize APM infrastructure (idempotent) | `--workspace`, `--region` |\n| `apm configuration get` | Get LicenseKey, Endpoint, project | `--workspace`, `--region` |\n| `apm service create` | Register application service | `--workspace`, `--region`, `--body` |\n| `apm service list` | List/filter registered services | `--workspace`, `--region`, `--service-name` |\n| `apm service delete` | Delete a service record | `--workspace`, `--region`, `--service-id` |\n| `integration addon get` | Fetch addon template + schema | `--addon-name`, `--env-type Client` |\n\n---\n\n## Onboarding Workflow\n\n### Step 1 — Gather Parameters\n\nCollect from user:\n\n| Parameter | How to obtain |\n|-----------|---------------|\n| `regionId` | Ask user (e.g., `cn-hangzhou`, `ap-southeast-1`) |\n| `appName` | Ask user — the application/service name |\n| `framework` | Ask user — which AI framework (Dify, LangChain, etc.) |\n| `network` | Ask user — `public` or `VPC` (not needed for Dify console config) |\n| `protocol` | Present available protocols from [Supported Frameworks](#supported-frameworks) and ask user to choose |\n\n### Step 2 — Initialize APM Infrastructure\n\n```bash\naliyun sts get-caller-identity -o json\n\n# Build workspace name\nworkspace=default-cms-{AccountId}-{regionId}\n\n# Initialize (idempotent)\naliyun cms2 apm configuration create --workspace {workspace} --region {regionId}\n```\n\n### Step 3 — Get Credentials\n\n```bash\naliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json\n```\n\nExtract from response:\n- `entryPointInfo.authToken` → `{LicenseKey}`\n- `entryPointInfo.publicDomain` → `{publicEndpoint}`\n- `entryPointInfo.privateDomain` → `{vpcEndpoint}`\n- `entryPointInfo.project` → `{project}`\n\n### Step 4 — Register Application Service\n\n```bash\naliyun cms2 apm service create --workspace {workspace} --region {regionId} \\\n --body '{\n \"serviceName\": \"{appName}\",\n \"serviceType\": \"{serviceType}\",\n \"attributes\": [\n {\"key\": \"language\", \"value\": \"{language}\"}\n ]\n }'\n```\n\n**serviceType mapping**: see [Protocol legend](#supported-frameworks).\n\n**language attribute**: based on the framework's underlying agent (e.g., `python` for LangChain/LangGraph/DashScope/AgentScope/OpenAI); refer to addon template for framework-specific values; omit if unknown.\n\n### Step 5 — Generate Configuration\n\nRoute to the appropriate path based on user's selected `protocol` and `framework`.\n\n#### Path A — Reuse apm.md Existing Flows (自研探针)\n\nFor protocols that correspond to existing apm.md onboarding flows, do NOT call `integration addon get`. Instead, follow the linked apm.md section directly with Step 3 credentials.\n\n| Protocol | Framework | Follow |\n|----------|-----------|--------|\n| `arms` | LangChain/LangGraph, DashScope, AgentScope, OpenAI | [apm.md — Python — Aliyun Agent (aliyun-bootstrap)](apm.md#python--aliyun-agent-aliyun-bootstrap) |\n| `arms4cs` | LangChain/LangGraph, DashScope, AgentScope, OpenAI | [apm.md — Python — ack-onepilot (K8s)](apm.md#python--ack-onepilot-k8s) |\n| `arms-ecs` | Coze | [apm.md — Golang — instgo compile (ECS / Host)](apm.md#golang--instgo-compile-ecs--host) |\n| `arms-ack` | Coze | [apm.md — Golang — ack-onepilot (K8s)](apm.md#golang--ack-onepilot-k8s) |\n\n#### Path B — Addon Dynamic Fetch\n\nFor all other protocols (`opentelemetry`, `agent-extension`, `manual`), and for frameworks without 自研探针 support (Dify, OpenClaw, CoPaw, Hermes), use `integration addon get` to fetch the configuration template at runtime.\n\n1. Fetch addon card:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json\n```\n\n2. Extract the target protocol template:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"{protocol}\") | .codeTemplate'\n```\n\n3. Render variables with Step 3 credentials:\n\n| Template Variable | Value Source |\n|-------------------|--------------|\n| `{{region}}` | `{regionId}` |\n| `{{LicenseKey}}` | `entryPointInfo.authToken` |\n| `{{workspace}}` / `{{$context$.workspace}}` | `{workspace}` |\n| `{{Project}}` | `entryPointInfo.project` |\n| `{{PubDomain}}` / `{{PubAddr}}` | `entryPointInfo.publicDomain` |\n| `{{VpcDomain}}` / `{{InnerAddr}}` | `entryPointInfo.privateDomain` |\n| `{{serviceName}}` | `{appName}` |\n| `{{version}}` | Ask user (default: `1.0.0`) |\n| `{{environment}}` | Ask user (default: `production`) |\n| `{{connectionType}}` | `inner` (VPC) or `public` |\n| `{{exportMethod}}` | Must be selected from `schema.props.dataSource` |\n\n4. **Interactive parameter confirmation rules**:\n - For branch/select parameters (`connectionType`, `exportMethod`, `instrumentType`, `source`), ask the user to choose explicitly with concrete options from schema `dataSource`. Do NOT auto-select or silently use defaults.\n - For `{{version}}` and `{{environment}}`, always ask user to confirm with suggested defaults.\n - If schema and template disagree on allowed values, **schema wins**.\n - Only ask for parameters that are actually referenced by the selected template branch.\n\n5. Present rendered steps to user.\n\n### Step 6 — Post-Onboarding Verification\n\n```bash\naliyun cms2 apm service list --workspace {workspace} --service-name {appName} --region {regionId} -o json\n```\n\n**Expected**: service appears with correct `serviceType` and `serviceName`. After restarting the application with the generated configuration, data should appear in CMS 2.0 console within 2-3 minutes.\n\n---\n\n## Framework-Specific Notes\n\n### Dify\n\n- Dify >= 1.6.0 内置 OTel 追踪能力，在 Dify 控制台 > 监测 > 追踪应用性能 > 云监控 中配置 LicenseKey 和 Endpoint 即可，无需安装任何探针\n- 仅 `opentelemetry` 协议，通过 addon 模板获取配置参数填入 Dify 控制台\n- 不需要 `aliyun-instrument` 或任何 agent 安装步骤\n\n### Coze\n\n- 底层为 Golang 应用，协议名称与其他框架不同：`arms-ecs` / `arms-ack`（而非 `arms`/`arms4cs`）\n- `arms-ecs` → 复用 [apm.md Golang — instgo](apm.md#golang--instgo-compile-ecs--host)\n- `arms-ack` → 复用 [apm.md Golang — ack-onepilot](apm.md#golang--ack-onepilot-k8s)\n- `opentelemetry` → 通过 addon 模板获取 Go OTel Agent 配置\n\n### OpenClaw / CoPaw / Hermes\n\n- 各有专用 installer 脚本（`curl -fsSL ... | bash`），脚本自动安装对应可观测插件\n- 参数通过 `--x-arms-license-key`、`--serviceName`、`--endpoint` 传入\n- 仅 `opentelemetry` 协议，按 addon 模板输出即可\n\n### LangChain/LangGraph / DashScope / AgentScope / OpenAI\n\n- `arms` / `arms4cs` 协议 → 复用 [apm.md Python — Aliyun Agent](apm.md#python--aliyun-agent-aliyun-bootstrap)，auto-instruments LLM calls, tool use, agent traces\n- `opentelemetry` 协议 → 通过 addon 模板获取 OTel SDK 配置\n\n### 自定义埋点\n\n- `agent-extension`: 基于 ARMS 探针扩展（`loongsuite-util-genai`），需先接入 Python 自研探针\n- `manual`: 手动 OTel SDK 埋点，不依赖 ARMS 探针\n- 两种协议均通过 addon 模板获取具体代码示例\n\n---\n\n## Offboarding / Uninstall\n\nOffboarding is the reverse of onboarding: **remove agent configuration from the application first, then clean up CMS-side resources**.\n\n| Step | Action | Command / Procedure |\n|------|--------|---------------------|\n| 1 | Remove agent from application | Reverse of Step 5: remove agent wrapper、环境变量、Dify 控制台禁用追踪、或 uninstall 插件脚本（视框架而定） |\n| 2 | Restart application | Restart without agent params |\n| 3 | Verify agent stopped | Confirm no new data appears in CMS console after 3-5 minutes |\n| 4 | Delete service record (**requires user confirmation**) | `aliyun cms2 apm service delete --workspace {workspace} --service-id {serviceId} --region {regionId}` |\n\n---\n\n## Error Handling & Fallback\n\n| Error | Cause | Resolution |\n|-------|-------|------------|\n| `addon not found` | Addon name incorrect or not yet available in region | Verify addon name from [Supported Frameworks](#supported-frameworks); for Python-based frameworks fallback to [apm.md Python section](apm.md#python--aliyun-agent-aliyun-bootstrap) |\n| `workspace not found` | APM infrastructure not initialized | Run `apm configuration create` first (Step 2) |\n| `service already exists` | Duplicate serviceName | Use `apm service list` to check, then update or delete existing service |\n| `InvalidJSON` | Malformed `--body` | Validate with `jq . <<<''` before passing to CLI |\n| Template variable unresolved | `{{var}}` in rendered output | Check variable mapping table in Step 5; ensure all credentials from Step 3 are substituted |\n\nFile v1.0.5:references/alerting.md\n\n# Alerting Module\n\n> Global conventions (credentials, output, error codes) — see [../SKILL.md](../SKILL.md).\n> Run `aliyun cms2 alert --help` for full flag lists; this doc focuses on **business knowledge** not in `--help`.\n> Notification targets (contacts / robots / webhooks) are now under the top-level `notification-channel` command — not under `alert`.\n> APM metric catalog → [apm-metrics.md](apm-metrics.md). UModel metric catalog → [umodel-metrics.md](umodel-metrics.md).\n\n## Command Tree (sub-resource layout)\n\n```\naliyun cms2 alert\n├── rule create | update | patch | delete | enable | disable | list | get\n├── template list | get | create | update | delete | apply\n└── history list\n```\n\n> ⚠️ **Hard rules (user preference)**:\n> 1. To modify an existing rule, **always prefer** `alert rule patch --use-patch-api`. **Avoid `update`** (it requires the full body and risks accidental overwrites).\n> 2. After a successful `alert rule create`, you **must** immediately run `alert rule get --alert-rule-id ` and show the full rule to the user. Do not skip.\n\n### Query Alert Rule\n\n```bash\naliyun cms2 alert rule get --alert-rule-id \naliyun cms2 alert rule list --workspace \n```\n\n#### Client-side Guards (alert rule get / list / delete)\n\nThese are **client-side fail-fast checks** added after the v0.9.2-6 QA pass\n(CMS-CLI-NEW-1 / CMS-CLI-NEW-7 / silent-filter-acceptance). Treat them as\nhard constraints when generating commands; the server would otherwise\nsilently return surprising rows or success-with-zero-effect envelopes.\n\n| Command | Guard | Why |\n|---------|-------|-----|\n| `alert rule get` | `--alert-rule-id` rejects empty / whitespace-only values (`InvalidArgument`). | Was a P0 information-disclosure: empty ID degraded into a `Uuid.Eq=\"\"` filter and dumped the entire account's rules. |\n| `alert rule delete` | When `deletedCount == 0` (no UUID matched), the envelope is `{success:false, error:{code:\"ResourceNotFound\"}}`. | Earlier behaviour was `success=true, deletedCount=0` + a stderr warning, which masks typos in scripted teardown. |\n| `alert rule list` | `--alert-rule-id`, when explicitly set, must not be empty / whitespace-only. | Otherwise the UUID filter was silently dropped and the query degraded to a workspace-wide list-all. |\n| `alert rule list` | `--page-size`, `--page-number`, `--max-results` must be `>= 1` when explicitly set. | `--page-size 0` used to be silently forwarded and the server returned 0 rows. |\n| `alert rule list` | `--page-size` and `--max-results` are capped at **1000** client-side. | The backend echoes any size into the envelope but truncates the actual rows; large values look like \"0 rows returned\". |\n\n> If you need a true list-all, omit the filter flag entirely. Do **not**\n> pass `--alert-rule-id \"\"` thinking it means \"any\".\n\n### Alert Rule Template Filter Guards\n\n| Command | Guard | Why |\n|---------|-------|-----|\n| `alert template list` | `--alert-type` is whitelisted to `PROMETHEUS_SINGLE_QUERY` / `PROMETHEUS_MULTI_QUERY` / `APM_METRIC_QUERY` / `APM_MULTI_QUERY` / `SLS_MULTI_QUERY` / `UMODEL_METRICSET_QUERY`. | The list endpoint silently returns 0 rows for unknown values, which masks typos like `Prometheus` (CamelCase, used by `create`/`update`) being pasted into list. |\n| `alert template list` | `--alert-type` rejects empty / whitespace-only values when explicitly set. | Same reason as above. Omit the flag to query without an alert-type filter. |\n| `alert template list` | `--page-size` capped at **1000** client-side; `--page-number` / `--page-size` must be `>= 1` when explicitly set. | The backend echoes the requested size in the envelope while truncating real rows, hiding paging bugs. |\n\n> **CamelCase vs SCREAMING_SNAKE**: `alert template list --alert-type` uses\n> the **inner ruleConfigs query type** (`PROMETHEUS_SINGLE_QUERY` etc.).\n> The `alert template create / update` payload's top-level `alertType`\n> uses the **CamelCase server-canonical form** (`Prometheus` / `APM` /\n> `UModel`). They are different fields with different vocabularies; do\n> not cross them.\n\n### Patch vs Update Decision\n\n| Scenario | Choose |\n|----------|--------|\n| Phase 2 supplement of `level` / `message` / `send` / `sendToArms` / `alertMetricInput` | ✅ `patch --use-patch-api` |\n| Add/remove/modify notification targets, threshold, severity, active time, displayName, labels, annotations | ✅ `patch --use-patch-api` |\n| Full rebuild of `queryConfig` (switch metric / switch PromQL) | ⚠️ `update` (or delete + create) |\n| Switch `datasourceConfig.type` | ⚠️ `delete` + `create` (cannot patch) |\n\n---\n\n## ManageAlertRules Type System\n\nThree rule types. `datasourceConfig.type` ↔ `queryConfig.type` ↔ `conditionConfig.type` must match strictly:\n\n| datasource | queryConfig.type | conditionConfig.type | Use case |\n|-----------|------------------|----------------------|----------|\n| `PROMETHEUS` | `PROMETHEUS_SINGLE_QUERY` | `PROMETHEUS_SIMPLE_CONDITION` | PromQL alerts |\n| `APM` | `APM_MULTI_QUERY` | `APM_SIMPLE_CONDITION` (multi-threshold) | APM single-condition |\n| `APM` | `APM_MULTI_QUERY` | `APM_COMPOSITE_CONDITION` | APM multi-condition single-threshold |\n| `UMODEL` | `UMODEL_METRICSET_QUERY` | `UMODEL_METRICSET_CONDITION` | CloudMonitor (ECS / RDS / K8s) |\n\n### Common Config (all types)\n\n```json\n{\n \"action\": \"CREATE\",\n \"workspace\": \"\",\n \"displayName\": \"\",\n \"enabled\": true,\n \"scheduleConfig\": {\"type\": \"FIXED\", \"intervalSecs\": 60},\n \"notifyConfig\": {\n \"type\": \"DIRECT_NOTIFY\",\n \"channels\": [{\"type\": \"CONTACT\", \"identifiers\": [\"\"]}],\n \"silenceTimeSecs\": 300,\n \"activeDays\": [1,2,3,4,5,6,7],\n \"activeStartTime\": \"00:00\", \"activeEndTime\": \"23:59\",\n \"utcOffset\": \"+08:00\"\n }\n}\n```\n\n`channels[].type`: `CONTACT` | `GROUP` | `DINGTALK` | `FEISHU` | `SLACK` | `WEIXIN` | `WEBHOOK`\n`severity`: `INFO` | `WARN` | `ERROR` | `CRITICAL`\n\n---\n\n## Type 1: Prometheus\n\n**Required user input** (AskUser): `region` + `workspace` + `instanceId` (Prometheus instance / cluster_id).\n\n```json\n\"datasourceConfig\": {\"type\": \"PROMETHEUS\", \"instanceId\": \"\", \"regionId\": \"\"},\n\"queryConfig\": {\"type\": \"PROMETHEUS_SINGLE_QUERY\", \"promQl\": \"\", \"expr\": \"\", \"enableDataCompleteCheck\": true},\n\"conditionConfig\": {\"type\": \"PROMETHEUS_SIMPLE_CONDITION\", \"durationSecs\": 300, \"severity\": \"WARN\"}\n```\n\n> ⚠️ **POP gateway requires `expr`**: the SDK field is `promQl`, but POP validation also requires `expr`. **Send both fields with the same value.**\n\n### Message & Annotations (must be generated on CREATE)\n\nOtherwise the console \"detection statement\" / notification body will be empty. Prometheus uses the Prometheus template syntax:\n\n| Variable | Prom template | APM template |\n|----------|---------------|--------------|\n| Label | `{{$labels.}}` | `$tags.` |\n| Current value | `{{ printf \"%.2f\" $value }}` | `$formatted_values.val_0` |\n\nSeverity zh-CN mapping (used inside `message`): `CRITICAL` → 严重 / `ERROR` → 错误 / `WARN` → 警告 / `INFO` → 普通.\n\n**Default templates** (Chinese is intentional — these strings render in the alert console / IM messages):\n- `message`: `<监控对象> {{$labels.<主维度>}} <指标中文> 最近 分钟持续 触发告警，当前值 {{ printf \"%.2f\" $value }}`\n- `annotations._cms_rule_display_statement`: `<监控对象描述> <指标中文> 最近 分钟持续 触发告警。`\n\n**Primary label inference**: nodes use `instance`; cAdvisor containers use `pod` / `container`; JVM uses `application`; cloud products use `instanceId` etc. When uncertain, use `{{ $labels | toJSON }}` as a debugging placeholder.\n\n### Full Example (Prometheus)\n\n```json\n{\n \"action\": \"CREATE\",\n \"workspace\": \"default-cms--cn-hangzhou\",\n \"displayName\": \"CPU 使用率告警\",\n \"enabled\": true,\n \"annotations\": {\"_cms_rule_display_statement\": \"节点机 CPU 使用率最近 5 分钟持续大于 90% 触发警告告警。\"},\n \"message\": \"节点机 {{$labels.instance}} CPU 使用率最近 5 分钟持续大于 90% 触发警告告警，当前值 {{ printf \\\"%.2f\\\" $value }}%\",\n \"datasourceConfig\": {\"type\": \"PROMETHEUS\", \"instanceId\": \"prom-abc\", \"regionId\": \"cn-hangzhou\"},\n \"queryConfig\": {\n \"type\": \"PROMETHEUS_SINGLE_QUERY\",\n \"promQl\": \"avg(rate(node_cpu_seconds_total{mode=\\\"idle\\\"}[5m])) by (instance) > 90\",\n \"expr\": \"avg(rate(node_cpu_seconds_total{mode=\\\"idle\\\"}[5m])) by (instance) > 90\"\n },\n \"conditionConfig\": {\"type\": \"PROMETHEUS_SIMPLE_CONDITION\", \"durationSecs\": 300, \"severity\": \"WARN\"},\n \"scheduleConfig\": {\"type\": \"FIXED\", \"intervalSecs\": 60},\n \"notifyConfig\": {\"type\": \"DIRECT_NOTIFY\", \"channels\": [{\"type\": \"CONTACT\", \"identifiers\": [\"ops-user\"]}], \"silenceTimeSecs\": 300, \"activeDays\": [1,2,3,4,5], \"activeStartTime\": \"09:00\", \"activeEndTime\": \"18:00\", \"utcOffset\": \"+08:00\"}\n}\n```\n\n---\n\n## Type 2: APM\n\n**Required user input** (AskUser): `region` + `workspace` + `serviceId` (APM service ID).\n\n`datasourceConfig` does not carry `instanceId`; `regionId` is optional:\n\n```json\n\"datasourceConfig\": {\"type\": \"APM\", \"regionId\": \"cn-hangzhou\"},\n\"queryConfig\": {\n \"type\": \"APM_MULTI_QUERY\",\n \"serviceIdList\": [\"\"],\n \"filterList\": [{\"key\": \"\", \"type\": \"ALL\"}],\n \"measureList\": [{\"measureCode\": \"\", \"windowSecs\": 60, \"groupBy\": [\"\"]}]\n}\n```\n\n> 📖 **measureCode / group / filter / unit mapping** → see [apm-metrics.md](apm-metrics.md). **Always look up the table before creating** — the console fails silently otherwise.\n\n### ConditionConfig\n\n```json\n// Simple — single condition, multi-threshold\n{\"type\": \"APM_SIMPLE_CONDITION\", \"aggregate\": \"AVG\", \"operator\": \"GT\",\n \"thresholdList\": [{\"severity\": \"WARN\", \"threshold\": 80}, {\"severity\": \"CRITICAL\", \"threshold\": 95}]}\n\n// Composite — multi-condition, single-threshold\n{\"type\": \"APM_COMPOSITE_CONDITION\", \"relation\": \"OR\", \"severity\": \"CRITICAL\",\n \"compareList\": [{\"aggregate\": \"AVG\", \"operator\": \"GT\", \"threshold\": 50}]}\n```\n\n`aggregate`: `AVG` | `SUM` | `COUNT` | `MAX` | `MIN` | `P50` | `P75` | `P90` | `P99` | `CONTINUES`\n`operator`: `GT` | `GE` | `LT` | `LE` | `EQ` | `NE`\n`relation`: `OR` | `AND`\n\n### Console Display Required Fields (CRITICAL — must be set on CREATE)\n\n| Field | Purpose |\n|-------|---------|\n| `annotations._cms_rule_display_statement` | Console \"detection statement\" |\n| `annotations._cms_domain` | Entity domain — APM uses `\"apm\"` |\n| `annotations._cms_entity_type` | Entity type template |\n| `annotations._cms_entity_id` | Entity ID template |\n| `annotations._cms_entity_prop_service_id` | `\"$labels.acs_arms_service_id\"` |\n| `annotations._cms_entity_prop_ip` | `\"$labels.rootIp\"` (host metrics) |\n| `message` | Notification body (see template) |\n| `labels._cms_metric_key` / `_cms_metric_group_key` | Metric identifiers |\n| `alertMetricInput` | Console metric-picker metadata (CREATE does not support; supplement via PATCH) |\n\n**Display statement template** (Chinese — renders in console):\n`\" 最近 分钟的大于 触发告警。\"`\n\n**Message template** (Chinese — renders in notifications):\n`\" : $tags. 最近 分钟的 大于 触发告警，当前值 $formatted_values.val_0\"`\n\n### Full Example (Host CPU)\n\n```json\n{\n \"action\": \"CREATE\",\n \"workspace\": \"default-cms--cn-hangzhou\",\n \"displayName\": \"arms-pop-cpu-high\",\n \"enabled\": true,\n \"labels\": {\"_cms_app_name\":\"application_insights\",\"_cms_metric_key\":\"appstat.jvm.SystemCpuUsage\",\"_cms_metric_group_key\":\"appstat.jvm.SystemCpuUsage\"},\n \"annotations\": {\n \"_cms_rule_display_statement\": \"主机监控 节点机CPU利用率 最近 1 分钟的平均值大于 80 触发警告告警。\",\n \"_cms_domain\": \"apm\",\n \"_cms_entity_type\": \" if $labels.rootIp apm.instance else apm.service end\",\n \"_cms_entity_id\": \" if $labels.rootIpprintf \\\"%s$%s\\\" $labels.acs_arms_service_id $labels.rootIp | md5elseprintf \\\"%s\\\" $labels.acs_arms_service_id | md5end\",\n \"_cms_entity_prop_service_id\": \"$labels.acs_arms_service_id\",\n \"_cms_entity_prop_ip\": \"$labels.rootIp\"\n },\n \"message\": \"主机监控 节点机IP: $tags.rootIp 节点机CPU利用率最近 1 分钟的平均值 大于 80 %触发警告告警，当前值 $formatted_values.val_0\",\n \"alertMetricInput\": {\"metricId\":\"appstat.jvm.SystemCpuUsage\",\"groupId\":\"apm.host\",\"filterValues\":[{\"opt\":\"ALL\",\"dim\":\"rootIp\"}]},\n \"datasourceConfig\": {\"type\":\"APM\",\"regionId\":\"cn-hangzhou\"},\n \"queryConfig\": {\"type\":\"APM_MULTI_QUERY\",\"serviceIdList\":[\"aokcdqn3ly@xxx\"],\"filterList\":[{\"key\":\"rootIp\",\"type\":\"ALL\"}],\n \"measureList\":[{\"measureCode\":\"appstat.jvm.SystemCpuUsage\",\"windowSecs\":60,\"groupBy\":[\"rootIp\"]}]},\n \"conditionConfig\": {\"type\":\"APM_SIMPLE_CONDITION\",\"aggregate\":\"AVG\",\"operator\":\"GT\",\"thresholdList\":[{\"severity\":\"WARN\",\"threshold\":80}]},\n \"scheduleConfig\": {\"type\":\"FIXED\",\"intervalSecs\":60},\n \"notifyConfig\": {\"type\":\"DIRECT_NOTIFY\",\"channels\":[{\"type\":\"CONTACT\",\"identifiers\":[\"ops-user\"]}],\"silenceTimeSecs\":900,\"activeDays\":[1,2,3,4,5,6,7],\"activeStartTime\":\"00:00\",\"activeEndTime\":\"23:59\",\"utcOffset\":\"+08:00\"}\n}\n```\n\n### APM PATCH-Required Fields (CREATE does not accept them)\n\n| Field | Reason |\n|-------|--------|\n| `level` | CREATE defaults to `INFO`; not derived from `thresholdList` |\n| `alertMetricInput` | Required for console metric-picker rendering |\n| `condition.compareList[].baseUnit/displayUnit` | Console unit display |\n| `send.notification.notifyTime` | `notifyConfig.activeDays` is stored under the wrong field `effect_time` on CREATE |\n| `send.sendToArms` | ARMS integration flag |\n\n**Patch field mapping** (CREATE → patch body):\n\n- `level` ← highest severity in `thresholdList` (CRITICAL > ERROR > WARN > INFO)\n- `alertMetricInput.metricId/groupId` ← apm-metrics.md `key` / `group`\n- `alertMetricInput.filterValues` ← group filters (default `opt: ALL`)\n- `condition.compareList[].baseUnit/displayUnit` ← apm-metrics.md baseUnit / displayUnit map\n- `condition.compareList[].valueLevelList[].value` ← `conditionConfig.thresholdList[].threshold` (**raw number, no conversion**)\n- `condition.compareList[].aggregate` ← `conditionConfig.aggregate.toLowerCase()`\n- `condition.compareList[].oper` ← `conditionConfig.operator`\n- `send.notification.contacts/dingWebhooks/fsWebhooks/wxWebhooks/slackWebhooks/customWebhooks/groups` ← results from `notification-channel contact/robot/webhook list`\n- `send.notification.notifyTime.dayOfWeek` ← active days (1=Mon..7=Sun)\n- `send.notification.notifyTime.startTime/endTime` ← `HH:MM`\n- `send.notification.notifyTime.gmtOffset` ← `+0800` (**no colon**, unlike CREATE's `+08:00`)\n- `send.notification.silenceTime` ← `notifyConfig.silenceTimeSecs`\n- `send.sendToArms` ← default `false`\n\n> CREATE-stage `notifyConfig.activeDays/active*Time` may carry a placeholder full week. **The effective window is the one written by PATCH `send.notification.notifyTime`.**\n\n---\n\n## Type 3: UModel\n\n**Required user input** (AskUser): `region` + `workspace` + entity info (domain / type / cluster_id).\n\n```json\n\"datasourceConfig\": {\"type\": \"UMODEL\"},\n\"queryConfig\": {\n \"type\": \"UMODEL_METRICSET_QUERY\",\n \"entityDomain\": \"k8s\",\n \"entityType\": \"k8s.pod\",\n \"metricSet\": \"k8s.metric.high_level_metric_pod\",\n \"metric\": \"pod_restart_count\",\n \"entityFilters\": [{\"field\":\"namespace\",\"operator\":\"=\",\"value\":\"kube-system\"}],\n \"entityFields\": [{\"field\":\"cluster_id\",\"value\":\"\"}]\n},\n\"conditionConfig\": {\"type\":\"UMODEL_METRICSET_CONDITION\",\"durationSecs\":60,\"severity\":\"INFO\",\"operator\":\"GT\",\"threshold\":1}\n```\n\n> 📖 **metricSet / metric ID lookup table** → [umodel-metrics.md](umodel-metrics.md). **Always look up before creating**; on a miss, call `ask_user_question` to confirm.\n\n### Full Example (UModel — Pod restart)\n\n```json\n{\n \"action\": \"CREATE\",\n \"workspace\": \"o11y-integration-cn-hongkong\",\n \"displayName\": \"Pod 重启次数 > 1\",\n \"enabled\": true,\n \"labels\": {\"_cms_app_name\":\"cloudlens_for_container\",\"_cms_cluster_id\":\"c65359xxx\",\"_cms_region\":\"cn-hongkong\"},\n \"datasourceConfig\": {\"type\":\"UMODEL\"},\n \"queryConfig\": {\"type\":\"UMODEL_METRICSET_QUERY\",\"entityDomain\":\"k8s\",\"entityType\":\"k8s.pod\",\n \"metricSet\":\"k8s.metric.high_level_metric_pod\",\"metric\":\"pod_restart_count\",\n \"entityFilters\":[{\"field\":\"namespace\",\"operator\":\"=\",\"value\":\"kube-system\"}],\n \"entityFields\":[{\"field\":\"cluster_id\",\"value\":\"c65359xxx\"}]},\n \"conditionConfig\": {\"type\":\"UMODEL_METRICSET_CONDITION\",\"durationSecs\":60,\"severity\":\"INFO\",\"operator\":\"GT\",\"threshold\":1},\n \"scheduleConfig\": {\"type\":\"FIXED\",\"intervalSecs\":60},\n \"notifyConfig\": {\"type\":\"DIRECT_NOTIFY\",\"channels\":[{\"type\":\"CONTACT\",\"identifiers\":[\"ops-user\"]}],\"silenceTimeSecs\":60,\"activeDays\":[1,2,3,4,5,6,7],\"activeStartTime\":\"00:00\",\"activeEndTime\":\"23:59\",\"utcOffset\":\"+08:00\"}\n}\n```\n\n---\n\n## Creation Workflow (CREATE → PATCH → VERIFY)\n\n### Step 1 — Lock context\n\n| Type | Required params (must AskUser) |\n|------|-------------------------------|\n| Prometheus | `region` + `workspace` + `instanceId` |\n| APM | `region` + `workspace` + `serviceId` |\n| UModel | `region` + `workspace` + entity (domain / type / cluster_id) |\n\nLock the region first — the workspace and the datasource are both region-scoped — and take it only from the sources allowed by [Required AskUser Params](#required-askuser-params).\n\n### Step 2 — Build query\n\n- Prom: PromQL (send `promQl` and `expr` with the same value)\n- APM: look up measureCode + group in [apm-metrics.md](apm-metrics.md), then derive filterList / groupBy\n- UModel: look up metricSet + metric in [umodel-metrics.md](umodel-metrics.md)\n\n### Step 3 — Build condition\n\nseverity / threshold / operator / aggregate (APM) / duration.\n\n### Step 4 — Query notification targets (MANDATORY)\n\n```bash\naliyun cms2 notification-channel contact list\naliyun cms2 notification-channel robot list\naliyun cms2 notification-channel webhook list\n```\n\n> **Skipping this** leaves `notifyConfig.channels[].identifiers` pointing at non-existent resources.\n\n### Step 5 — Pre-check + summary + execute (CREATE)\n\n```bash\n# Duplicate-name pre-check\naliyun cms2 alert rule list --workspace \n```\n\nShow the **Configuration Summary** (Type / Metric / Threshold / Severity / Notification / Active Time) to the user, wait for confirmation, then:\n\n```bash\nUUID=$(aliyun cms2 alert rule create --body @rule.json -o json | jq -r '.alertRuleId')\n```\n\n### Step 6 — PATCH supplement (MANDATORY for APM)\n\nCREATE only writes a subset of fields; APM rules **must** be supplemented via PATCH (see APM patch field map above).\n\n```bash\naliyun cms2 alert rule patch --alert-rule-id $UUID --body @patch.json\n```\n\n> Routing (defaults of `alert rule patch`):\n> - `--body` mode + `--use-patch-api=true` (**default**) → `PatchAlertRule` (HTTP `PATCH /alertRules/{id}`, true incremental). This is what you want for APM phase-2 supplements.\n> - `--body` mode + `--use-patch-api=false` → `ManageAlertRules UPDATE` (full replacement, PUT semantics). Partial bodies are typically rejected by the backend with `\"X is required\"`. The CLI prints a stderr warning when this branch is taken.\n> - `--set key=value` mode → forced to `ManageAlertRules UPDATE` regardless of the flag, because `--set` paths (e.g. `conditionConfig.threshold`, `notifyConfig.channels`) are UPDATE-style and not compatible with the `PatchAlertRule` schema (`condition` / `query` / `send` / `labels` / ...). The CLI prints a stderr warning here as well.\n\n**patch.json template**:\n\n```json\n{\n \"level\": \"CRITICAL\",\n \"alertMetricInput\": {\"metricId\":\"\",\"groupId\":\"\",\"filterValues\":[{\"opt\":\"ALL\",\"dim\":\"\"}]},\n \"condition\": {\"type\":\"APM_CONDITION\",\"compareList\":[{\n \"oper\":\"GT\",\"aggregate\":\"avg\",\"baseUnit\":\"\",\"displayUnit\":\"\",\n \"valueLevelList\":[{\"level\":\"CRITICAL\",\"value\":}]\n }]},\n \"send\": {\"sendToArms\": false, \"notification\": {\n \"contacts\":[\"\"],\n \"notifyTime\":{\"dayOfWeek\":[1,2],\"startTime\":\"00:00\",\"endTime\":\"23:59\",\"gmtOffset\":\"+0800\"},\n \"silenceTime\": 900\n }}\n}\n```\n\n### Step 7 — Final verify (MANDATORY)\n\n```bash\naliyun cms2 alert rule get --alert-rule-id $UUID -o json\n```\n\nShow the full JSON to the user. Verify: `level`, `alertMetricInput.metricId/groupId`, `condition.compareList[].baseUnit/displayUnit`, `send.notification.notifyTime.dayOfWeek`, `send.notification.contacts`.\n\n---\n\n## Critical Rules\n\n### API Enforcement\n\nCMS 2.0 only uses `ManageAlertRules` (create / update / delete) + `QueryAlertRules` (query) + `PatchAlertRule` (incremental supplement).\n\n**Forbidden** — never fall back to: `PutResourceMetricRule` / `DescribeMetricRuleList` (CMS 1.0), `CreateOrUpdateAlertRule` / `CreatePrometheusAlertRule` (ARMS). On failure: STOP. Do not retry with a different API.\n\n### Required AskUser Params\n\n`region` / `workspace` / `instanceId` (Prom) / `serviceId` (APM) must come from AskUser. Do not auto-construct or guess.\n\n`region` and `regionId` additionally fall under the [Region Confirmation Gate](../SKILL.md#region-confirmation-gate-hard-requirement) — which also rules out the `cn-hangzhou` that the examples in this file use.\n\n### POP Gateway Known Limit\n\nPOP validates the `type` field. Currently registered: `PROMETHEUS` ✓ + 4 `conditionConfig.type` values ✓. If `APM` / `UMODEL` `datasourceConfig.type` returns `\"type is mandatory for this action\"`, you may degrade to `PROMETHEUS` + `PROMETHEUS_SINGLE_QUERY` and translate the APM expression into PromQL (loses filterList / multi-threshold APM features).\n\n---\n\n## Other Workflows\n\n### Modify a Rule\n\n```bash\n# ✅ Preferred — incremental (PatchAlertRule, the default routing of --body mode)\naliyun cms2 alert rule patch --alert-rule-id --body @patch.json\naliyun cms2 alert rule get --alert-rule-id -o json # mandatory display\n\n# ⚠️ --set is forced to ManageAlertRules UPDATE (full-replacement). Backend\n# usually rejects a partial --set body with \"X is required\". Use --body for\n# true incremental updates instead.\naliyun cms2 alert rule patch --alert-rule-id --set displayName=\"New Name\"\n\n# ⚠️ Full replace — only when rebuilding queryConfig\naliyun cms2 alert rule get --alert-rule-id -o json > rule.json\n# Edit rule.json: set action=UPDATE, add the uuid field\naliyun cms2 alert rule update --alert-rule-id --body @rule.json\naliyun cms2 alert rule get --alert-rule-id -o json\n```\n\n### Enable / Disable / Delete\n\n```bash\naliyun cms2 alert rule enable --alert-rule-id ,\naliyun cms2 alert rule disable --alert-rule-id \naliyun cms2 alert rule delete --alert-rule-id # irreversible — confirm first\n```\n\n### Query Alert History\n\n```bash\naliyun cms2 alert history list --workspace \naliyun cms2 alert history list --workspace --alert-rule-name \"CPU使用率过高\"\n```\n\n> ⚠️ **Pagination flags differ from rule / template**: `alert history list` only supports token-based pagination — `--max-results ` + `--next-token ` (read `nextToken` from the response). It does **not** support `--page-number` / `--page-size`.\n>\n> Output: `-o text` (default) and `-o json` both render full rows. The first stderr line in `-o text` is `# data returned= total= truncated=` followed by CSV rows. The previous regression where `-o text` returned an empty body (forcing `-o json`) has been fixed; you do not need `-o json` to see the rows.\n\n#### Known Caveats (alert history list)\n\nThese are deliberate, currently-unsupported behaviours. Treat them as constraints when generating commands or `--body` payloads; do not silently \"fix\" them by retrying with different inputs.\n\n| # | Caveat | Why it matters | Recommended workaround |\n|---|--------|----------------|------------------------|\n| 1 | **Inside `--body`, only `pageSize` is honoured by the server**; `maxResults` is silently ignored. | The `--max-results` flag path mirrors the value into both `MaxResults` and `PageSize` (see [list.go `buildAlertHistoryListRequestFromFlags`](file:///Users/hym/aliyun-cms-cli/pkg/command/alerthistory/list.go)). The `--body` path does **not** apply this rewrite — it forwards the JSON verbatim. A body that only sets `\"maxResults\":N` will fall back to the server default page size. | In `--body`, always write `\"pageSize\": N` (and optionally also `\"maxResults\": N` for forward compatibility). Reserve `--max-results` for the flag path. |\n| 2 | **`--workspace` is not auto-trimmed**. Leading/trailing whitespace is sent verbatim and the server matches it as a literal string — you will see `data: []` with no error. | Client-side validation only rejects control characters and over-length; spaces are valid characters. | Trim the workspace identifier yourself (`echo \"$WS\" | xargs`) before passing it. Quote it with `\"...\"` to make accidental trailing spaces visible. |\n| 3 | **No `--page-number` flag**. The SDK request model carries `pageNumber`, but the CLI deliberately exposes only token-based pagination. | Token pagination is stable across server-side re-shards; offset pagination is not. Mixing them produces non-deterministic skips. | Always paginate via `--max-results` + `--next-token`. If you genuinely need offset pagination, fall back to `--body '{\"pageSize\":N,\"pageNumber\":M}'` — you accept the stability caveat. |\n| 4 | **`--max-results` upper bound is not documented in `--help`**. The server enforces an internal cap (observed: requests with `pageSize > ~1000` are quietly clamped). | Large page sizes silently degrade to the server cap, breaking client-side `len(data) == max-results` assumptions. | Keep `--max-results` ≤ **100** for normal querying. For full-table scans, loop with `--next-token` instead of trying to bump `--max-results` higher. |\n| 5 | **Severity / status enums are case-sensitive on the client**. `--severity critical` is rejected as `InvalidArgument` even though the server itself would accept it. | The CLI runs an enum guard (`CRITICAL` / `WARNING` / `INFO` and `Ok` / `Alerting`) before the API call to surface typos early. | Use the canonical case shown in `--help`. Inside `--body`, also use `\"latestLevel\":\"CRITICAL\"` (or the alias `\"severity\":\"CRITICAL\"`); lowercase forms reach the server but the CLI flag path will not. |\n| 6 | **`--body` accepts `severity` as an alias for `latestLevel`, but not the other pagination/filter aliases.** | The alias rewrite is intentionally narrow — only `severity → latestLevel` is implemented (see [`rewriteSeverityAlias`](file:///Users/hym/aliyun-cms-cli/pkg/command/alerthistory/list.go)). Other server-side names (`alertRuleId`, `startTimeFrom`, `startTimeTo`, `pageSize`) must be used verbatim. | When porting console JSON into `--body`, keep the SDK canonical key names. Setting **both** `severity` and `latestLevel` is rejected (`InvalidArgument`) on purpose. |\n\n> If any of the above limitations becomes blocking for a real workflow, file a CLI feature request — do not paper over it with retries or shell post-processing in the SKILL output.\n\n### Discoverability / Dry-run\n\n```bash\naliyun cms2 alert rule create --show-schema\naliyun cms2 alert rule create --show-example-body\naliyun cms2 alert rule create --body @rule.json --dry-run # server-side validation, not persisted\n```\n\n---\n\n## Alert Rule Templates (`alert template`)\n\nA template encapsulates a reusable alert rule definition; `apply` materializes it into one or more `alert rule` records — equivalent to the console \"Apply Template\" action.\n\n### Schema (key fields)\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | int64 | Numeric primary key (CLI: `--template-id`) |\n| `uuid` | string | String alias (CLI: `--template-uuid`) |\n| `templateName` / `description` / `alertType` / `subType` | string | Metadata |\n| `isSystem` | int32 | 0 = custom, 1 = system built-in (read-only, applyable) |\n| `applyCount` / `status` | int / int | Apply count / status |\n| `ruleConfigs` | **string** | **Serialized alert rule JSON** (one or many) |\n\n`alertType` (CamelCase, server-canonical — the create/update endpoint rejects underscored forms): `Prometheus` / `APM` / `UModel`.\n\n> The CLI auto-serializes `ruleConfigs` (object/array) to a string on create/update; on apply it deserializes and substitutes placeholders `${key}` / `{{key}}` / `{{ key }}` / `{{.key}}` / `{{ .key }}` (placeholders without a matching `--var` are left intact for dry-run debugging).\n>\n> **`ruleConfigs` inner shape** — the create/update endpoint expects a **flat** object inside the stringified JSON, not a wrapper. Required keys: `level` / `displayName` / `query` / `message` / `labels`. Do **not** put `queryConfig` / `conditionConfig` / `datasourceConfig` / `rules` at the top level inside the string — those are the apply-time three-section schema. Run `alert template create --show-example-body` for the canonical create-time skeleton.\n\n### Apply Workflow\n\n| Step | Action |\n|------|--------|\n| 1 | `apply --template-id N --workspace W` |\n| 2 | Resolve template: try `GetAlertRuleTemplate` first; on failure (the upstream `/alertRuleTemplate/detail` endpoint is not always deployed in every region) the CLI **auto-falls back** to `ListAlertRuleTemplate` and matches by `id` / `uuid` |\n| 3 | Substitute placeholders with `--var key=value` — supports `${key}` / `{{key}}` / `{{ key }}` / `{{.key}}` / `{{ .key }}`. Placeholders without a matching `--var` are left intact for dry-run debugging |\n| 4 | Decode `ruleConfigs` (single rule / `{rules:[...]}` wrapper / array of rules) |\n| 5 | **Dialect translation** — if the rule body is in alertmanager-style (`alert` / `expr` / `for` / `labels.severity`), the CLI auto-translates to the three-section CMS schema (`queryConfig` / `conditionConfig` / `notifyConfig`). The PromQL is written into `queryConfig.expr` (the canonical wire field on the apply path; `promQl` returns `400 expr is required in queryConfig` here, even though `alert rule create` still accepts both) |\n| 6 | **Inject overrides + required-field defaults** — `action=CREATE` / `workspace` / `displayName` / channel block; if missing, the CLI fills `enabled=true` and `scheduleConfig={type:FIXED, intervalSecs:60}` so the request passes the `ManageAlertRules` validator |\n| 7a | `--dry-run` → print the assembled body without calling the backend |\n| 7b | Otherwise call `ManageAlertRules` per rule body |\n| 8 | Collect `uuid` + `displayName` + `requestId`. On mid-batch failure the error response carries `failedAt` + `createdRules` (no rollback) |\n| 9 | `alert rule get --alert-rule-id ` (mandatory display) |\n\n### Typical Examples\n\n```bash\n# Browse candidate templates\naliyun cms2 alert template list --alert-type PROMETHEUS_SINGLE_QUERY --is-system 1\n\n# --is-system -1 fans out to two backend calls (custom + system) and merges results;\n# pagination is intentionally rejected in this mode (semantics not well-defined).\naliyun cms2 alert template list --is-system -1\n\n# Get a template (resolved via GetAlertRuleTemplate; auto-fallback to list-scan on endpoint miss)\naliyun cms2 alert template get --template-id 12345\naliyun cms2 alert template get --template-uuid tpl-xyz\n\n# List notification identifiers BEFORE apply — needed for --contact-group-id / channel-type.\naliyun cms2 notification-channel contact list # contact ids (use --channel-type CONTACT)\n# (group ids come from your contact-group catalog in the console)\n\n# Apply a template — default channel type is GROUP\naliyun cms2 alert template apply --template-id 12345 --workspace ws-xxx \\\n --var namespace=prod --var prometheusInstanceId=prom-xxx \\\n --contact-group-id --contact-group-id \n\n# Apply with a single contact instead of a contact group\naliyun cms2 alert template apply --template-id 12345 --workspace ws-xxx \\\n --var namespace=prod \\\n --display-name \"Pod-Restart-Prod\" \\\n --prometheus-instance-id \\\n --contact-group-id \\\n --channel-type CONTACT # GROUP (default) | CONTACT | DINGTALK | FEISHU | WEIXIN | SLACK | WEBHOOK\n\n# Dry-run preview of the assembled alert rule body (no backend call)\naliyun cms2 alert template apply --template-id 12345 --workspace ws-xxx --dry-run\n\n# Manage custom templates\naliyun cms2 alert template create --body @./template.json\naliyun cms2 alert template update --template-id 12345 --body '{\"description\":\"new desc\"}'\naliyun cms2 alert template delete --template-id 12345\n```\n\n### Limits\n\n- `isSystem=1` system templates are read-only (cannot update/delete; can apply)\n- `--workspace` is required outside dry-run mode\n- Mid-batch failures of `apply` **do not auto-rollback** (avoids deleting production rules); the error response carries `failedAt` + `createdRules`\n- The internal structure of `ruleConfigs` is not strictly validated by `apply`; an illegal body is rejected by `ManageAlertRules`\n- **Resolution fallback**: when `GetAlertRuleTemplate` returns `data:null` or the detail endpoint is not deployed, the CLI silently retries via `ListAlertRuleTemplate`. Only after that miss does it surface a structured `ResourceNotFound` (the message mentions `data:null` for diagnosability)\n- **Apply-path field name**: PromQL must be sent as `queryConfig.expr`; the apply path rejects `promQl` with `400 expr is required in queryConfig` (this differs from `alert rule create`, which still accepts both)\n- **Channel-type default**: `--contact-group-id` values default to `notifyConfig.channels[0].type=GROUP`; pass `--channel-type CONTACT|DINGTALK|FEISHU|WEIXIN|SLACK|WEBHOOK` to override. The CLI also injects `enabled=true` and `scheduleConfig={type:FIXED, intervalSecs:60}` when the template body omits them, so apply does not fail with `\"X is required\"` 400s\n\n---\n\n## Related\n\n- Alert events → SLS event store → [event-hub.md](event-hub.md)\n- APM metric catalog → [apm-metrics.md](apm-metrics.md)\n- UModel metric catalog → [umodel-metrics.md](umodel-metrics.md)\n\nFile v1.0.5:references/apm-metrics.md\n\n# APM Metric Catalog\n\n> Companion to [alerting.md](alerting.md). All `aliyun cms2 alert rule` APM commands consume these tables.\n\n## Group → Filter / GroupBy Mapping\n\nWhen constructing `queryConfig.filterList` / `groupBy`, look up the metric's `group` first.\n\n| Group | displayNameCn | Default Filters (dim → type) | groupBy |\n|-------|---------------|-------------------------------|--------|\n| `apm.host` | 主机监控 (Host) | `rootIp` → ALL | `[\"rootIp\"]` |\n| `apm.jvm` | JVM监控 (JVM) | `rootIp` → ALL | `[\"rootIp\"]` |\n| `apm.txn` | 应用提供服务统计 (Inbound RPC) | `rpc` → ALL, `rpcType` → ALL | `[\"rpc\",\"rpcType\"]` |\n| `apm.txn_type` | 应用依赖服务统计 (Outbound RPC) | `rpcType` → ALL, `destId` → ALL | `[\"rpcType\",\"destId\"]` |\n| `apm.pod` | 容器监控 (Pod) | `rootIp` → ALL | `[\"rootIp\"]` |\n| `apm.exception` | 异常监控 (Exception) | `rpc` → ALL, `excepName` → ALL | `[\"rpc\",\"excepName\"]` |\n| `apm.httpcode` | HTTP状态码 (HTTP status) | `rpc` → ALL, `status` → ALL | `[\"rpc\",\"status\"]` |\n| `apm.db` | 数据库指标 (Database) | `endpoint` → ALL | `[\"endpoint\"]` |\n| `apm.threadpool` | 线程池监控 (Thread pool) | `ThreadPoolType` → ALL, `ThreadPoolName` → ALL, `rootIp` → ALL | `[\"ThreadPoolType\",\"ThreadPoolName\",\"rootIp\"]` |\n| `apm.threadpoolv2` | 新版线程池 (Thread pool v2) | `thread_pool_usage` → ALL, `thread_name_pattern` → ALL, `rootIp` → ALL | `[\"thread_pool_usage\",\"thread_name_pattern\",\"rootIp\"]` |\n| `apm.connectionpool` | 连接池监控 (Connection pool) | `pool_type` → ALL, `rootIp` → ALL | `[\"pool_type\",\"rootIp\"]` |\n| `apm.scheduler` | 定时任务 (Scheduled task) | `rpc` → ALL | `[\"rpc\"]` |\n| `apm.httpclient` | Web依赖 (HTTP client) | `destId` → ALL, `endpoint` → DISABLED | `[\"destId\"]` |\n\n> **Default rule**: All dims default to `ALL` (traverse) unless user specifies a concrete filter value (then use `EQ`).\n> **filterList[].type**: `EQ` | `NE` | `ALL` | `DISABLED` | `CONTAIN` | `EXCLUDES` | `=~` | `!~`\n\n---\n\n## User Intent → Metric Quick Reference\n\nMatch user intent first; only fall back to the full registry if not listed here.\n\n| User Intent (zh-CN) | measureCode | Group | Unit |\n|---------------------|-------------|-------|------|\n| CPU 使用率 / CPU usage | `appstat.jvm.SystemCpuUsage` | apm.host | % |\n| 内存使用率 / Memory usage | `appstat.jvm.SystemMemUsage` | apm.host | % |\n| JVM 堆内存使用率 / Heap usage | `appstat.jvm.HeapUsedRatio` | apm.jvm | % |\n| FullGC 次数 / Full GC count | `appstat.jvm.gc.OldGcCountInstant` | apm.jvm | count |\n| 线程总数 / Thread count | `appstat.jvm.ThreadCount` | apm.jvm | number |\n| 调用次数 / QPS | `appstat.transaction.count` | apm.txn | count |\n| 响应时间 / RT | `appstat.transaction.rt` | apm.txn | ms |\n| 错误率 / Error rate | `appstat.transaction.errorrate` | apm.txn | % |\n| 慢调用 / Slow calls | `appstat.transaction.slowcount` | apm.txn | count |\n| Pod CPU 使用量 / Pod CPU | `appstat.pod.SystemCpuTotal` | apm.pod | core |\n| Pod 内存使用量 / Pod memory | `appstat.pod.SystemMemUsage` | apm.pod | MB |\n| 数据库 RT / DB RT | `appstat.database.rt` | apm.db | ms |\n| 异常次数 / Exception count | `appstat.exception.count` | apm.exception | count |\n| 线程池使用率 / Thread pool usage | `appstat.threadpool.threadpoolusedpercent` | apm.threadpool | % |\n| 连接池连接数 / Active connections | `appstat.connectionpool.active_connection_count` | apm.connectionpool | number |\n\n> **CRITICAL**: `appstat.jvm.cpu` does NOT exist. CPU is in `apm.host` group → `appstat.jvm.SystemCpuUsage`.\n\n---\n\n## Full Metric Registry\n\n### `apm.host` — Node/Host (CPU, Memory, Disk, Load, Network)\n\n`appstat.host.InstanceCount`(JVM instances) `appstat.jvm.SystemCpuUsage`(CPU%) `appstat.jvm.SystemCpuUser`(CPU user%) `appstat.jvm.SystemDiskFree`(free disk MB) `appstat.jvm.SystemDiskUsage`(disk%) `appstat.jvm.SystemLoad`(load) `appstat.jvm.SystemMemFree`(free mem MB) `appstat.jvm.SystemMemUsage`(mem%) `appstat.jvm.SystemNetInBytes`(net in MB) `appstat.jvm.SystemNetInErrs`(in errors) `appstat.jvm.SystemNetInPackets`(in packets) `appstat.jvm.SystemNetOutBytes`(net out MB) `appstat.jvm.SystemNetOutErrs`(out errors) `appstat.jvm.SystemNetOutPackets`(out packets)\n\n### `apm.jvm` — JVM (Heap, GC, Threads, Metaspace)\n\nHeap/Metaspace: `appstat.jvm.HeapUsedRatio`(%) `appstat.jvm.heap_total`(MB) `appstat.jvm.heap_used`(MB) `appstat.jvm.METASPACE`(MB) `appstat.jvm.non_heap_committed`(MB) `appstat.jvm.non_heap_init`(MB) `appstat.jvm.non_heap_max`(MB) `appstat.jvm.non_heap_used`(MB)\n\nGC: `appstat.jvm.GcPsMarkSweepCount` `appstat.jvm.GcPsScavengeCount` `appstat.jvm.gc.OldGcCount` `appstat.jvm.gc.OldGcCountInstant` `appstat.jvm.gc.OldGcTime`(ms) `appstat.jvm.gc.OldGcTimeInstant`(ms) `appstat.jvm.gc.YoungGcCount` `appstat.jvm.gc.YoungGcCountInstant` `appstat.jvm.gc.YoungGcTime`(ms) `appstat.jvm.gc.YoungGcTimeInstant`(ms)\n\nThreads: `appstat.jvm.ThreadCount` `appstat.jvm.ThreadBlockedCount` `appstat.jvm.ThreadDeadlockCount` `appstat.jvm.ThreadNewCount` `appstat.jvm.ThreadRunnableCount` `appstat.jvm.ThreadTerminatedCount` `appstat.jvm.ThreadTimedWaitCount` `appstat.jvm.ThreadWaitCount`\n\n### `apm.txn` — Transaction/RPC\n\n`appstat.transaction.count`(count) `appstat.transaction.error`(count) `appstat.transaction.errorrate`(%) `appstat.transaction.rt`(ms) `appstat.transaction.slowcount`(count)\n\n### `apm.txn_type` — Inbound/Outbound\n\nIn: `appstat.incall.count` `appstat.incall.error` `appstat.incall.errorrate`(%) `appstat.incall.rt`(ms)\nOut: `appstat.outcall.count` `appstat.outcall.error` `appstat.outcall.errorrate`(%) `appstat.outcall.rt`(ms) `appstat.outcall.slowcount`\n\n### `apm.pod` — Pod resource\n\n`appstat.pod.SystemCpuSystem`(core) `appstat.pod.SystemCpuTotal`(core) `appstat.pod.SystemCpuUser`(core) `appstat.pod.SystemMemUsage`(MB) `appstat.pod.SystemNetInBytes`(MB) `appstat.pod.SystemNetInDrop` `appstat.pod.SystemNetInErrs` `appstat.pod.SystemNetInPackets` `appstat.pod.SystemNetOutBytes`(MB) `appstat.pod.SystemNetOutDrop` `appstat.pod.SystemNetOutErrs` `appstat.pod.SystemNetOutPackets`\n\n### `apm.db` / `apm.txn_db` — Database\n\n`appstat.database.count` `appstat.database.errcount` `appstat.database.rt`(ms) `appstat.database.slowcount`\n`appstat.sql.count` `appstat.sql.error` `appstat.sql.rt`(ms)\n\n### `apm.exception` / `apm.httpcode` / `apm.httpclient`\n\n`appstat.exception.count` `appstat.exception.rt`(ms)\n`appstat.status.count`\n`appstat.httpclient.count` `appstat.httpclient.rt`(ms) `appstat.httpclient.errorrate`(%)\n\n### `apm.connectionpool`\n\n`appstat.connectionpool.active_connection_count` `appstat.connectionpool.max_connection_count` `appstat.connectionpool.max_idle_connection_count` `appstat.connectionpool.min_idle_connection_count` `appstat.connectionpool.pending_request_count`\n\n### `apm.threadpool` (v1)\n\n`appstat.threadpool.threadcorepoolsize` `appstat.threadpool.threadmaxpoolsize` `appstat.threadpool.threadpoolactivecount` `appstat.threadpool.threadpoolqueuesize` `appstat.threadpool.threadpoolsize` `appstat.threadpool.threadpooltaskcount` `appstat.threadpool.threadpoolusedpercent`(%)\n\n### `apm.threadpoolv2`\n\n`appstat.threadpoolv2.max_thread_count` `..._max` `appstat.threadpoolv2.active_thread_count` `..._max` `appstat.threadpoolv2.completed_task_count` `appstat.threadpoolv2.current_thread_count` `..._max` `appstat.threadpoolv2.queue_size` `appstat.threadpoolv2.rejected_task_count` `appstat.threadpoolv2.scheduled_task_count` `appstat.threadpoolv2.used_percent`(%)\n\n### `apm.scheduler`\n\n`appstat.scheduler.count` `appstat.scheduler.delay`(ms) `appstat.scheduler.error` `appstat.scheduler.rt`(ms)\n\n### `apm.saehost` — SAE host\n\nCPU/Mem/Disk/Net: `appstat.infra.sae.SystemCpu`(%) `appstat.infra.sae.SystemDiskRate`(%) `appstat.infra.sae.SystemDiskRead`(B) `appstat.infra.sae.SystemDiskWrite`(B) `appstat.infra.sae.SystemDiskIopsRead` `appstat.infra.sae.SystemDiskIopsWrite` `appstat.infra.sae.SystemLoad` `appstat.infra.sae.SystemMemRate`(%) `appstat.infra.sae.SystemMemTotal`(MB) `appstat.infra.sae.SystemMemUsed`(MB) `appstat.infra.sae.SystemNetRecv`(B) `appstat.infra.sae.SystemNetTran`(B) `appstat.infra.sae.SystemNetRecvDrop` `appstat.infra.sae.SystemNetRecvError` `appstat.infra.sae.SystemNetRecvPacket` `appstat.infra.sae.SystemNetTranDrop` `appstat.infra.sae.SystemNetTranError` `appstat.infra.sae.SystemNetTranPacket`\n\n---\n\n## baseUnit / displayUnit Mapping (PatchAlertRule)\n\nWhen patching `condition.compareList[].baseUnit/displayUnit` post-CREATE:\n\n| baseUnit | displayUnit | Applicable Metrics |\n|----------|-------------|--------------------|\n| `percent` | `%` | CPU utilization: `SystemCpuUsage`, `SystemCpuUser`, `infra.sae.SystemCpu` |\n| `ratio` | `%` | Usage / error rate: `HeapUsedRatio`, `SystemDiskUsage`, `SystemMemUsage`, `transaction.errorrate`, `threadpoolusedpercent`, `used_percent`, `incall.errorrate`, `outcall.errorrate`, `SystemDiskRate`, `SystemMemRate` |\n| `byte` | `MB` | Memory / disk / network bytes: `heap_total`, `heap_used`, `non_heap_*`, `METASPACE`, `SystemDiskFree`, `SystemMemFree`, `SystemNet*Bytes`, `pod.SystemMem*`, `pod.SystemNet*Bytes`, `sae.SystemMem*` |\n| `(none)` | `次` / `count` | `GcCount`, `transaction.count`, `.error`, `.slowcount` |\n| `(none)` | `毫秒` / `ms` | `GcTime`, `transaction.rt`, `database.rt`, `scheduler.rt` |\n| `(none)` | `个` / `number` | `ThreadCount`, `InstanceCount`, `SystemLoad` |\n| `(none)` | `核` / `core` | `pod.SystemCpu*` |\n\n> **⚠️ Threshold value — no conversion**: write the user-provided percentage / number as-is (20% → `20`, 80% → `80`). `baseUnit/displayUnit` only drive console rendering and **do not participate in threshold value conversion**.\n\n```json\n// User intent: error rate > 20% critical alert\n\"conditionConfig\": {\"thresholdList\": [{\"severity\": \"CRITICAL\", \"threshold\": 20}]}\n// PatchAlertRule:\n\"condition\": {\"compareList\": [{\"valueLevelList\": [{\"level\": \"CRITICAL\", \"value\": 20}], \"baseUnit\": \"ratio\", \"displayUnit\": \"%\"}]}\n```\n\n---\n\n## Metric Validation Rule\n\nWhen user provides a measureCode or describes intent:\n\n1. Match against **User Intent → Metric Quick Reference** first.\n2. If exact key provided → validate against **Full Metric Registry**.\n3. If NOT found → **STOP**. Show closest matches and use `ask_user_question` for confirmation. Never create with an unverified metric — silent failure in console.\n4. If found → note the correct group; use `ask_user_question` only when ambiguous.\n\nFile v1.0.5:references/apm.md\n\n# Application Monitoring (APM) Module\n\n> Global conventions (credentials, output format, error codes, command prefix, distributions) — see [../SKILL.md](../SKILL.md).\n> Run `aliyun cms2 apm --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard server-side applications into CMS Application Monitoring. Uses `aliyun cms2` CLI to initialize APM infrastructure and retrieve access credentials, then generates configuration for the user's specific language and deployment method.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported languages, **auto-modify K8s Deployment YAML** (with user confirmation) via `aliyun cs` + `kubectl`.\n\n**Out-of-Scope (this version)**: Automatic modification of ECS host startup scripts / Dockerfile; agent binary downloads.\n\n---\n\n## Container Onboarding Hard Rules\n\n> **CRITICAL** — When the user selects container (ACK/ACS/K8s) onboarding, the following rules are **absolute and non-negotiable**. Violating any of them is a workflow error.\n\n1. **Do NOT ask user for `regionId`**: In container onboarding, `regionId` must be derived automatically from cluster metadata, workspace name, or kubeconfig context. Never prompt the user for region. If derivation fails, use `aliyun cs describe-clusters` output to extract `region_id` from cluster info.\n2. **Do NOT run any `integration addon list` or `integration addon get` commands**: Container onboarding uses ack-onepilot component check + workload label patching. Addon discovery is exclusively for non-container (ECS/host) OpenTelemetry scenarios.\n3. **Do NOT mention \"Addon\" to the user**: When asking the user to select onboarding type, use the prompt \"请选择接入类型？\" (not \"请选择接入协议类型？（Addon 类型）\" or any variant containing \"Addon\").\n4. **Do NOT ask user for `network` type**: Container onboarding uses ack-onepilot label injection — there is no agent download URL or endpoint configuration, so public/VPC distinction is irrelevant. Skip the network question entirely.\n\n**Trigger recognition**: User mentions any of the following → treat as container onboarding: K8s, ACK, ACS, 容器, 容器服务, Kubernetes, 集群.\n\n**Container onboarding flow summary** (no addon, no regionId prompt, no network prompt):\n1. Determine it's container onboarding (user says ACK/ACS/K8s)\n2. Ask user for: `appName`, `language`; collect `clusterId` (from user input or derive from context)\n3. Derive `regionId` from cluster info (NOT from user input); skip `network` (irrelevant for ack-onepilot)\n4. Build `workspace` = `default-cms-{userId}-{regionId}`\n5. Check ack-onepilot component → Install if missing (with Two-Phase confirmation)\n6. Patch Deployment with labels (with Two-Phase confirmation)\n\n> **Language limitation**: Node.js and PHP do NOT support ack-onepilot. For these languages on K8s, guide the user to use OpenTelemetry env vars or manual SDK startup instead of ack-onepilot labels.\n\n---\n\n## Execution Safety Rules\n\n**Two-Phase Execution Protocol** — applies to operations that **modify the user's application or cluster** (e.g., patching Deployments, installing components, modifying startup scripts):\n\n1. **Phase A (Plan)**: Present the complete execution plan including exact commands, target resources, and expected impact. End your turn immediately after presenting the plan.\n2. **Phase B (Execute)**: Only proceed after the user's NEXT message contains explicit approval (\"yes\", \"confirm\", \"proceed\", \"go ahead\").\n\n**HARD RULES**:\n- Do NOT combine Phase A and Phase B in the same response.\n- Do NOT interpret silence or unrelated messages as approval.\n- If user says \"no\", \"cancel\", or asks to modify → return to Phase A with adjustments.\n\n**Operations that do NOT require confirmation** (execute directly):\n- Read-only commands: `get`, `list`, `--help`, `describe`, `describe-clusters`\n- CMS backend resource creation: `apm configuration create`, `apm service create` (these are CMS-side infrastructure, not user application changes)\n- Retrieving credentials: `apm configuration get`\n\n**Operations that REQUIRE confirmation** (must use Two-Phase Protocol):\n- Installing cluster components: `install-cluster-addons` (ack-onepilot)\n- Patching K8s Deployments: `kubectl patch deployment`\n- Modifying user application startup scripts or Dockerfiles\n- Any `kubectl apply` / `kubectl delete` on user workloads\n- Deleting service records: `apm service delete` (destructive — removes historical monitoring data association)\n\n> **Always offer manual alternative**: When presenting Phase A, also mention the manual way to achieve the same result (console URL, kubectl edit, manual file editing). Let the user choose between automated execution and self-service.\n\n**Plan output format** (use Markdown list, avoid box-drawing characters):\n```markdown\n### Execution Plan\n\n- Target: [what will be changed]\n- Commands:\n - `command 1`\n - `command 2`\n- Impact: [blast radius / what gets created or modified]\n- Rollback: [yes/no, how]\n\nPlease confirm execution (`yes` / `no`).\n```\n\n---\n\n## Supported Languages and Methods\n\n| Language / Component | 自研探针 | ack-onepilot (K8s) | OpenTelemetry | eBPF |\n|----------|:-:|:-:|:-:|:-:|\n| **Java** | AliyunJavaAgent | Yes | OTel Java Agent | — |\n| **Golang** | instgo compile | Yes | OTel Go Agent / SDK | — |\n| **Python** | aliyun-bootstrap | Yes | opentelemetry-instrument | — |\n| **Node.js** | @loongsuite/cms_node_sdk | — | OTel Node SDK | — |\n| **PHP** | — | — | OTel PHP extension | — |\n| **.NET** | — | — | OTel .NET Auto-Instrument | OBI (DaemonSet) |\n| **Nginx** | — | — | ngx_otel_module | — |\n| **Kong** | — | — | Kong OTel Plugin | — |\n| **APISIX** | — | — | APISIX OTel Plugin | — |\n\n---\n\n## CLI Commands Reference\n\n| Command | Purpose | Key Flags |\n|---------|---------|-----------|\n| `apm configuration create` | Initialize APM backend infrastructure | `--workspace`, `--region` |\n| `apm configuration get` | Retrieve authToken, endpoints, project | `--workspace`, `--region` |\n| `apm service create` | Register application service | `--workspace`, `--body` (JSON or @file) |\n| `apm service list` | List/verify existing services | `--workspace`, `--service-name`, `--service-type` |\n| `apm service get` | Get service details | `--workspace`, `--service-id` |\n| `apm service delete` | Remove a service | `--workspace`, `--service-id` |\n\n> **Important**: `apm service create --body` requires `< /dev/null` when piping in some shell environments to avoid stdin conflicts.\n\n---\n\n## Onboarding Workflow (6 Steps)\n\n### Step 1 — Gather Parameters\n\n| Parameter | Required | How to Obtain |\n|-----------|----------|---------------|\n| `regionId` | Conditional | **Container onboarding:** Automatically derive from clusterId via `aliyun cs describe-clusters` response (`region_id` field), NEVER ask user. **Non-container onboarding:** Always ask user to confirm. |\n| `userId` (AccountId) | Yes | `aliyun sts get-caller-identity` → `.AccountId`, or ask user |\n| `workspace` | Yes | Default Format: `default-cms-{userId}-{regionId}` |\n| `appName` | Yes | Always ask user to confirm application name |\n| `language` | Yes | java / golang / python / nodejs / php / dotnet |\n| `method` | Yes | 自研探针 / otel / ack-onepilot (prompt: \"请选择接入类型？\") |\n| `network` | Conditional | **Container onboarding:** Do NOT ask — ack-onepilot handles connectivity internally, network type is irrelevant. **Non-container onboarding:** Always ask user (public or VPC, affects download URL and endpoint). |\n\n### Step 2 — Initialize APM Infrastructure\n\n```bash\naliyun cms2 apm configuration create --workspace {workspace} --region {regionId}\n```\n\nIdempotent — if already initialized, returns successfully. Use `apm configuration get` to check status.\n\n### Step 3 — Retrieve Access Credentials\n\n```bash\naliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json\n```\n\n**Example real response** (status=Running means ready):\n```json\n{\n \"success\": true,\n \"data\": {\n \"entryPointInfo\": {\n \"authToken\": \"awy7aw18hz@26*44b70\",\n \"privateDomain\": \"proj-xtrace-d1265ec453407aba9ef476c91f84542d-cn-hangzhou.cn-hangzhou-intranet.log.aliyuncs.com\",\n \"project\": \"proj-xtrace-d1265ec453407aba9ef476c91f84542d-cn-hangzhou\",\n \"publicDomain\": \"proj-xtrace-d1265ec453407aba9ef476c91f84542d-cn-hangzhou.cn-hangzhou.log.aliyuncs.com\"\n },\n \"feeType\": \"arms=serverless;xtrace=serverless\",\n \"regionId\": \"cn-hangzhou\",\n \"requestId\": \"D9A655EE-3A76-5B16-88AA-60BE3B4D7A03\",\n \"settings\": {\n \"arms_switch\": \"enable\",\n \"trace_aggregate\": \"enable\",\n \"xtrace_switch\": \"enable\"\n },\n \"status\": \"Running\",\n \"type\": \"apm\",\n \"workspace\": \"default-cms-1108555361245511-cn-hangzhou\"\n }\n}\n```\n\nThe `status` field indicates the observability instance lifecycle state:\n\n| Status | Meaning | Action |\n|--------|---------|--------|\n| `Created` | Provisioning in progress; resources are initializing asynchronously | Proceed to next step |\n| `Running` | Fully operational | Proceed to next step |\n| `Failed` | Initialization failed; the system will auto-retry | Proceed to next step (retry is automatic) |\n| `Pending` | Awaiting activation; does **not** auto-recover | User must verify: 1) workspace exists, 2) the SLS project mapped to the workspace exists, 3) required logstores (`{workspace}__entity`, `{workspace}__topo`) exist under that project |\n\nExtract these variables for subsequent steps:\n\n| Field Path | Variable | Description |\n|-----------|----------|-------------|\n| `entryPointInfo.authToken` | **LicenseKey** | Agent authentication token (sensitive) |\n| `entryPointInfo.publicDomain` | **publicEndpoint** | Public network data reporting endpoint |\n| `entryPointInfo.privateDomain` | **vpcEndpoint** | VPC internal data reporting endpoint |\n| `entryPointInfo.project` | **project** | SLS project name, used in OTel header `x-arms-project` |\n\n> **Security**: `authToken` is a credential for data reporting. Remind the user not to log or expose it.\n\n### Step 4 — Register Application Service\n\n```bash\naliyun cms2 apm service create --workspace default-cms-{userId}-{regionId} --region {regionId} \\\n --body @service.json < /dev/null\n```\n\nWhere `service.json`:\n```json\n{\n \"serviceName\": \"{appName}\",\n \"serviceType\": \"TRACE\",\n \"attributes\": \"{\\\"language\\\":\\\"java\\\"}\"\n}\n```\n\n**serviceType mapping**:\n- 自研探针 (AliyunJavaAgent / instgo / aliyun-bootstrap / cms_node_sdk) → `TRACE`\n- OpenTelemetry / eBPF → `XTRACE`\n\n**`attributes.language` reference**:\n\n| Language | `attributes` value | serviceType |\n|----------|-------------------|-------------|\n| Java | omit or `{\"language\":\"java\"}` | TRACE or XTRACE |\n| Golang | `{\"language\":\"golang\"}` | TRACE or XTRACE |\n| Python | `{\"language\":\"python\"}` | TRACE or XTRACE |\n| Node.js | `{\"language\":\"nodejs\"}` | TRACE or XTRACE |\n| .NET | `{\"language\":\"dotnet\"}` | XTRACE |\n| PHP | `{\"language\":\"php\"}` | XTRACE |\n| Gateway (Nginx/Kong/APISIX) | omit | XTRACE |\n\n**Example real response**:\n```json\n{\n \"success\": true,\n \"data\": {\n \"pid\": \"awy7aw18hz@9269550ea2c2be0\",\n \"requestId\": \"B47F0659-143E-5E90-B446-29729C1ABC3A\",\n \"serviceId\": \"awy7aw18hz@645ab0bc177a46e87c7f1\"\n }\n}\n```\n\n### Step 5 — Generate Configuration Output\n\nRoute to the appropriate section below based on `language` + `method`, substitute the credential variables, and present to user for manual application.\n\n> **K8s users**: After generating configuration, proceed to [Step 6 — K8s Deployment Modification](#k8s-deployment-modification-step-6) to apply changes to the cluster.\n\n#### Addon Usage Decision Table\n\n| Scenario | `integration addon get` | Rationale |\n|----------|:-:|-----------|\n| Container / ACK / ACS / K8s onboarding | **Forbidden** | Use ack-onepilot component check + label patching directly |\n| ECS/host — Java AliyunJavaAgent (自研探针) | Not used | Only non-addon exception; use manual install section |\n| ECS/host — other 自研探针 (Go/Python) | **Use** | Fetch addon template (e.g. `apm-golang` → `arms-ecs` protocol) |\n| ECS/host — OpenTelemetry (all languages) | **Use** | Standard addon Dynamic Fetch flow |\n| ack-onepilot component operations | **Forbidden** | `ack-onepilot` is a cluster component, not an addon name |\n\n> **User-facing prompt rule**: When asking the user to select onboarding type/protocol, always use \"请选择接入类型？\" as the question text. Do NOT use \"请选择接入协议类型？（Addon 类型）\" or any phrasing that mentions \"Addon\" — this term is an internal implementation detail that is meaningless to users.\n\n> **Manual onboarding strategy**: By default, display the required startup parameters (e.g. `-javaagent`, `-Darms.*`, `OTEL_*` env vars) and guide the user to apply them manually. Also inform the user: if authorized, the agent can directly locate the target process startup script, auto-add parameters, and execute the restart. Explicit user authorization is required before performing any write or restart actions.\n>\n> **Manual alternative for all automated steps**: If the user prefers manual operation, provide:\n> - The exact commands/config to copy-paste\n> - The target file paths to edit\n> - The CMS console URL for GUI-based operation: `https://cmsnext.console.aliyun.com/`\n\n---\n\n## Common Configuration Templates\n\n### OTel Environment Variables (Shared)\n\nAll OpenTelemetry-based integrations use the same export configuration. Substitute variables from Step 3.\nPrefer runtime `addon get` templates (see [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch)); use this section as fallback when addon templates are unavailable.\n\n**HTTP protocol** (recommended):\n```bash\nexport OTEL_SERVICE_NAME={appName}\nexport OTEL_RESOURCE_ATTRIBUTES=service.name={appName},acs.cms.workspace={workspace},service.version={version},deployment.environment={env}\nexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\nexport OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://{endpoint}/opentelemetry/v1/traces\nexport OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://{endpoint}/opentelemetry/v1/metrics\nexport OTEL_EXPORTER_OTLP_HEADERS=\"x-arms-license-key={LicenseKey},x-arms-project={project},x-cms-workspace={workspace}\"\nexport OTEL_LOGS_EXPORTER=none\n```\n\n**gRPC protocol**:\n```bash\nexport OTEL_SERVICE_NAME={appName}\nexport OTEL_RESOURCE_ATTRIBUTES=service.name={appName},acs.cms.workspace={workspace},service.version={version},deployment.environment={env}\nexport OTEL_EXPORTER_OTLP_PROTOCOL=grpc\nexport OTEL_EXPORTER_OTLP_ENDPOINT=https://{endpoint}:10010\nexport OTEL_EXPORTER_OTLP_HEADERS=\"x-arms-license-key={LicenseKey},x-arms-project={project},x-cms-workspace={workspace}\"\nexport OTEL_LOGS_EXPORTER=none\n```\n\n> `{endpoint}` = `{publicEndpoint}` (public network) or `{vpcEndpoint}` (VPC internal).\n\n**Language-specific overrides**: Some languages use different endpoint path prefixes (e.g. `/apm/trace/opentelemetry/v1/traces` for Golang/Node.js). See per-language sections below.\n\n### ack-onepilot Labels (Shared)\n\nAll ack-onepilot onboarding uses these labels at `spec.template.metadata.labels`:\n\n```yaml\narmsPilotAutoEnable: \"on\"\narmsPilotCreateAppName: \"{appName}\"\narmsPilotAppWorkspace: \"{workspace}\"\n```\n\nAdditional labels by language:\n\n| Language | Extra Label | Notes |\n|----------|-------------|-------|\n| Java | `one-agent.jdk.version: \"OpenJDK18\"` | Optional, match app JDK version |\n| Golang | `aliyun.com/app-language: golang` | Required for non-Java |\n| Python | `aliyun.com/app-language: python` | Required for non-Java |\n\n> **Prerequisite**: ack-onepilot component must be installed and running. See [ack-onepilot Installation](#prerequisites-install-ack-onepilot-component).\n\n### Agent Download URL Pattern\n\n| Network | URL Pattern |\n|---------|-------------|\n| Public | `http://arms-apm-{regionId}.oss-{regionId}.aliyuncs.com/` |\n| VPC | `http://arms-apm-{regionId}.oss-{regionId}-internal.aliyuncs.com/` |\n\n---\n\n## OpenTelemetry Onboarding (Dynamic Fetch)\n\n> **⛔ CONTAINER EXCLUSION**: This entire section applies **ONLY to non-container (ECS/host) scenarios**. For container/ACK/ACS onboarding, skip directly to ack-onepilot component check + label patching. See [Addon Usage Decision Table](#addon-usage-decision-table).\n\nFor non-container onboarding, fetch the latest install guide at runtime instead of using static snippets.\n\n1. Select addon by target language/component:\n\n| Target | Addon Name |\n|--------|------------|\n| Java | `apm-java-batch` |\n| Golang | `apm-golang` |\n| Python | `apm-python` |\n| Node.js | `apm-nodejs-batch` |\n| PHP | `apm-php-batch` |\n| .NET | `apm-dotnet-batch` |\n| Nginx | `apm-nginx` |\n| Kong | `apm-kong` |\n| APISIX | `apm-apisix` |\n\n2. Fetch addon card:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json\n```\n\n3. Extract the target protocol template:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"opentelemetry\") | .codeTemplate'\n```\n\n4. Render variables with Step 3 credentials and runtime context:\n\n| Template Variable | Value Source |\n|-------------------|--------------|\n| `{{region}}` | `{regionId}` |\n| `{{LicenseKey}}` | `entryPointInfo.authToken` |\n| `{{workspace}}` / `{{$context$.workspace}}` | `{workspace}` |\n| `{{Project}}` | `entryPointInfo.project` |\n| `{{PubDomain}}` / `{{PubAddr}}` | `entryPointInfo.publicDomain` |\n| `{{VpcDomain}}` / `{{InnerAddr}}` | `entryPointInfo.privateDomain` |\n| `{{serviceName}}` | `{appName}` |\n| `{{version}}` | Ask user (see interactive rules below) |\n| `{{environment}}` | Ask user (see interactive rules below) |\n| `{{connectionType}}` | `inner` (VPC) or `public` |\n| `{{exportMethod}}` | Must be selected from `schema.props.dataSource` |\n\n5. **Interactive parameter confirmation rules**:\n - For branch/select parameters (`connectionType`, `exportMethod`, `instrumentType`, `source`), ask the user to choose explicitly with concrete options from schema `dataSource`. Do NOT auto-select or silently use defaults.\n - For `{{version}}` and `{{environment}}`, always ask user to confirm with suggested defaults: `version` → `1.0.0`, `2.0.0`, or custom; `environment` → `production`, `staging`, `development`, or custom.\n - If schema and template disagree on allowed values, **schema wins**. Hidden branches not in schema are unavailable.\n - If schema is missing or invalid, switch to manual guidance mode (show raw template + ask user to confirm each field).\n - Only ask for parameters that are actually referenced by the selected template branch.\n\n6. Present rendered steps to user. If the addon template is unavailable, fallback to the per-language documentation linked in each section below.\n\n---\n\n## Java — AliyunJavaAgent (Manual Install)\n\n### 1. Download Agent\n\n```bash\nwget -T 30 -t 3 \"http://arms-apm-{regionId}.oss-{regionId}[-internal].aliyuncs.com/AliyunJavaAgent.zip\" -O AliyunJavaAgent.zip\nunzip AliyunJavaAgent.zip -d /opt/\n```\n\n### 2. Startup Configuration\n\n**Spring Boot / JAR**:\n```bash\njava -javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar \\\n -Darms.licenseKey={LicenseKey} \\\n -Darms.appName={appName} \\\n -Darms.workspace={workspace} \\\n -jar app.jar\n```\n\n**Tomcat** — add to `{TOMCAT_HOME}/bin/setenv.sh`:\n```bash\nJAVA_OPTS=\"$JAVA_OPTS -javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={appName} -Darms.workspace={workspace}\"\n```\n\n**Jetty** — add to `{JETTY_HOME}/start.ini`:\n```\n--exec\n-javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar\n-Darms.licenseKey={LicenseKey}\n-Darms.appName={appName}\n-Darms.workspace={workspace}\n```\n\n**Multi-instance**: add `-Darms.agentId=001` to differentiate JVM processes on the same host.\n\nReference: [手动安装Java探针](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-agent-for-java-applications).\n\n---\n\n## Java — OpenTelemetry Agent\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-java-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-java-batch --env-type Client -o json\n```\n\nFallback: [通过OpenTelemetry上报Java应用数据](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-java-application-data).\n\n---\n\n## Java — ack-onepilot (K8s)\n\n### Prerequisites: Install ack-onepilot Component\n\nBefore adding labels, verify that the **ack-onepilot** component is installed and running in the target cluster.\n\n> **Warning**: Do NOT use `aliyun cs describe-cluster-addons-version` to check installation status — it returns all **available** addons (including uninstalled ones), not only installed ones.\n\n**Check** — use `kubectl` to verify actual resources:\n\n```bash\nkubectl get ns ack-onepilot\nkubectl get pods -n ack-onepilot\n```\n\nIf the namespace does not exist or no pods are Running, the component is **not installed**.\n\n**Install** — **⚠️ CONFIRMATION REQUIRED — Phase A**: Inform the user that ack-onepilot is not installed and present the installation plan. STOP and end your turn. Do NOT proceed until user explicitly confirms.\n\n```markdown\n### Execution Plan — Install ack-onepilot\n\n- Target: Cluster `[{clusterId}]`\n- Commands:\n - `aliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"`\n- Precondition: ack-onepilot is not installed (`kubectl get ns ack-onepilot` returns NotFound)\n- Impact: deploys DaemonSet in `ack-onepilot` namespace; agent pods run on worker nodes\n- Rollback: `kubectl delete ns ack-onepilot` (or uninstall via console)\n\nPlease confirm installation (`yes` / `no`).\n```\n\n**Phase B** (after user confirms): Obtain `clusterId` via `aliyun cs describe-clusters`, then execute:\n\n```bash\naliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"\n```\n\nAfter installation, verify pods are Running:\n\n```bash\nkubectl get pods -n ack-onepilot\n```\n\n> **Permission requirement**: RAM account must have `cs:InstallClusterAddons` permission. If 403 Forbidden, fall back to manual installation via [Container Service Console](https://cs.console.aliyun.com/) → Cluster → Operations > Component Management → Search `ack-onepilot` → Install.\n>\n> **Manual alternative**: If the user cannot or prefers not to use CLI for component installation, guide them to the console path above. The result is identical.\n\n**Requirements**: ack-onepilot >= 5.1.0; Worker node RAM role needs `AliyunARMSFullAccess` and `AliyunTracingAnalysisFullAccess`.\n\n### Add Labels\n\nApply [ack-onepilot labels from Common Configuration](#ack-onepilot-labels-shared) to the Deployment. Java does not require the `aliyun.com/app-language` label.\n\nReference: [通过ack-onepilot接入Java应用](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/install-the-arms-agent-for-java-applications-deployed-in-ack-and-acs-clusters-by-using-the-ack-onepilot-component).\n\n---\n\n## Golang — Onboarding (via `apm-golang` addon)\n\nAll Golang onboarding methods (自研探针 instgo and OpenTelemetry) use the same addon for template rendering:\n\n```bash\naliyun cms2 integration addon get --addon-name apm-golang --env-type Client -o json\n```\n\nSelect the protocol template by method:\n\n| Method | Protocol Name in Addon | Notes |\n|--------|----------------------|-------|\n| 自研探针 (ECS/host) | `arms-ecs` | instgo compile-time instrumentation |\n| OpenTelemetry (Auto) | `opentelemetry` | Standard OTel Dynamic Fetch flow |\n| OpenTelemetry (Manual SDK) | `opentelemetry` | Prefer SDK instructions in template if available |\n\n> For ACK/K8s container onboarding, do NOT use this addon flow. Follow [Golang — ack-onepilot (K8s)](#golang--ack-onepilot-k8s) directly.\n\nExtract a specific protocol template:\n\n```bash\naliyun cms2 integration addon get --addon-name apm-golang --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"{protocolName}\") | .codeTemplate'\n```\n\nFallback: [手动安装Golang探针](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-the-golang-agent) | [通过OpenTelemetry上报Go应用数据](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-go-application-data).\n\n---\n\n## Golang — ack-onepilot (K8s)\n\n### Prerequisites: Install ack-onepilot Component\n\nFollow the same installation and confirmation workflow as [Java — ack-onepilot (K8s)](#java--ack-onepilot-k8s):\n- Check installation status with `kubectl get ns ack-onepilot` and `kubectl get pods -n ack-onepilot`\n- If missing, use **Two-Phase confirmation** before installation\n- In container onboarding, do not ask user for `regionId`\n- Install command (after user confirms):\n `aliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"`\n- Verify all ack-onepilot pods are `Running` before continuing\n- Do NOT run `integration addon list/get` to search for `ack-onepilot`\n\n### Add Labels to Deployment\n\nApply [ack-onepilot labels from Common Configuration](#ack-onepilot-labels-shared) with `aliyun.com/app-language: golang`.\n\n**Important**: Golang applications require compiling with `instgo` before deploying to K8s. The ack-onepilot component handles agent injection, but the binary must already be instrumented at compile time.\n\nReference: [通过ack-onepilot接入Go应用](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/install-arms-agent-for-golang-applications-deployed-in-ack-and-acs).\n\n---\n\n## Python — Aliyun Agent (aliyun-bootstrap)\n\n```bash\npip3 install aliyun-bootstrap\naliyun-bootstrap -a install\n\nexport ARMS_APP_NAME={appName}\nexport ARMS_WORKSPACE={workspace}\nexport ARMS_REGION_ID={regionId}\nexport ARMS_LICENSE_KEY={LicenseKey}\n\naliyun-instrument python app.py\n```\n\n**Special cases**:\n- **uvicorn**: `from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize` as first import, or `aliyun-instrument gunicorn -k uvicorn.workers.UvicornWorker ...`\n- **uWSGI**: see [uWSGI integration docs](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-the-python-agent)\n- **gevent**: set `GEVENT_ENABLE=true`\n- **AI frameworks** (LangChain/LangGraph, DashScope, AgentScope, OpenAI 等): 部分 AI 框架的 `arms`/`arms4cs` 协议复用此 Python agent。完整 AI 可观测接入指南见 [references/ai.md](ai.md)。\n\n**Docker**:\n```dockerfile\nENV ARMS_APP_NAME={appName}\nENV ARMS_REGION_ID={regionId}\nENV ARMS_LICENSE_KEY={LicenseKey}\nENV ARMS_WORKSPACE={workspace}\nRUN pip3 install aliyun-bootstrap && ARMS_REGION_ID={regionId} aliyun-bootstrap -a install\nCMD [\"aliyun-instrument\", \"python\", \"app.py\"]\n```\n\nReference: [手动安装Python探针](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-the-python-agent).\n\n---\n\n## Python — OpenTelemetry\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-python`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-python --env-type Client -o json\n```\n\nFallback: [通过OpenTelemetry上报Python应用数据](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-python-application-data).\n\n---\n\n## Python — ack-onepilot (K8s)\n\n### Prerequisites: Install ack-onepilot Component\n\nFollow the same installation and confirmation workflow as [Java — ack-onepilot (K8s)](#java--ack-onepilot-k8s):\n- Check installation status with `kubectl get ns ack-onepilot` and `kubectl get pods -n ack-onepilot`\n- If missing, use **Two-Phase confirmation** before installation\n- In container onboarding, do not ask user for `regionId`\n- Install command (after user confirms):\n `aliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"`\n- Verify all ack-onepilot pods are `Running` before continuing\n- Do NOT run `integration addon list/get` to search for `ack-onepilot`\n\n### Add Labels to Deployment\n\nApply [ack-onepilot labels from Common Configuration](#ack-onepilot-labels-shared) with `aliyun.com/app-language: python`.\n\nFor ack-onepilot >= 5.1.0, the Python agent is auto-injected — no Dockerfile modification needed.\n\nReference: [通过ack-onepilot接入Python应用](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/install-arms-agent-for-python-applications-deployed-in-ack-and-acs).\n\n---\n\n## Node.js — CMS Node SDK (自研探针)\n\n### Prerequisites\n\n- Node.js v16+ (Active or Maintenance LTS versions only)\n- Supported frameworks: Express, Koa, HTTP/HTTPS, MySQL, PostgreSQL, MongoDB, Redis, Kafka, gRPC, Socket.IO\n\n### 1. Install\n\n```bash\nnpm install @loongsuite/cms_node_sdk\n```\n\n### 2. Start Application\n\n**CommonJS mode**:\n```bash\nexport ARMS_LICENSE={LicenseKey}\nexport CMS_SERVICE_NAME={appName}\nexport ARMS_REGION_ID={regionId}\nexport ARMS_WORKSPACE={workspace}\nnode -r @loongsuite/cms_node_sdk/register app.js\n```\n\n**ESModule mode**:\n```bash\nexport ARMS_LICENSE={LicenseKey}\nexport CMS_SERVICE_NAME={appName}\nexport ARMS_REGION_ID={regionId}\nexport ARMS_WORKSPACE={workspace}\nnode --experimental-loader=@loongsuite/cms_node_sdk/import-hooks -r @loongsuite/cms_node_sdk/register index.js\n```\n\n### 3. Manual Instrumentation (Optional)\n\nCreate `instrumentation.js`:\n\n**CommonJS**:\n```javascript\nconst { NodeSDK } = require('@loongsuite/cms_node_sdk');\n\nconst sdk = new NodeSDK({\n serviceName: \"{appName}\",\n licenseKey: \"{LicenseKey}\",\n regionId: \"{regionId}\",\n workspace: \"{workspace}\",\n});\n\nsdk.start();\nmodule.exports = sdk;\n```\n\n**ESModule**:\n```javascript\nimport { NodeSDK } from '@loongsuite/cms_node_sdk';\n\nconst sdk = new NodeSDK({\n serviceName: \"{appName}\",\n licenseKey: \"{LicenseKey}\",\n regionId: \"{regionId}\",\n workspace: \"{workspace}\",\n});\n\nsdk.start();\nexport { sdk };\n```\n\nRun with:\n```bash\nnode --require ./instrumentation.js app.js\n```\n\n---\n\n## Node.js — OpenTelemetry\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-nodejs-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-nodejs-batch --env-type Client -o json\n```\n\nFallback: [Node.js OTel 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-node-js-application-data).\n\n---\n\n## PHP — OpenTelemetry\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-php-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-php-batch --env-type Client -o json\n```\n\nFallback: [PHP OTel 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-php-application-data).\n\n---\n\n## .NET — OpenTelemetry (Auto-Instrument)\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-dotnet-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-dotnet-batch --env-type Client -o json\n```\n\nFallback: [.NET OTel 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-net-application-data).\n\n---\n\n## .NET — OpenTelemetry (Manual SDK)\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-dotnet-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-dotnet-batch --env-type Client -o json\n```\n\nPrefer codeTemplate content that includes manual SDK instructions when available in the current addon version.\n\nFallback: [.NET OTel 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-net-application-data).\n\n---\n\n## .NET — eBPF (OBI DaemonSet)\n\nUse addon template runtime fetch from `apm-dotnet-batch` with OBI protocol card.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-dotnet-batch --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"obi\") | .codeTemplate'\n```\n\nFallback: [eBPF ECS 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/access-observable-through-opentelemetry-ebpf-obi-on-ecs) | [eBPF ACK 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/access-observable-through-opentelemetry-ebpf-obi-on-ack).\n\n---\n\n## Nginx — OpenTelemetry (ngx_otel_module)\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-nginx`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-nginx --env-type Client -o json\n```\n\nFallback: 通过 [CMS 2.0 控制台 > 接入中心](https://cms.console.aliyun.com/) 完成接入。\n\n---\n\n## Kong — OpenTelemetry Plugin\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-kong`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-kong --env-type Client -o json\n```\n\nFallback: 通过 [CMS 2.0 控制台 > 接入中心](https://cms.console.aliyun.com/) 完成接入。\n\n---\n\n## APISIX — OpenTelemetry Plugin\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-apisix`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-apisix --env-type Client -o json\n```\n\nFallback: 通过 [CMS 2.0 控制台 > 接入中心](https://cms.console.aliyun.com/) 完成接入。\n\n---\n\n## Post-Onboarding Verification\n\n```bash\n# Verify the service was registered\naliyun cms2 apm service list --workspace {workspace} --service-name {appName} --region {regionId} -o json\n```\n\n**Expected**: service appears with correct `serviceType` and `serviceName`. After restarting the application, data should appear in CMS 2.0 console within 2-3 minutes.\n\n---\n\n## Offboarding / Uninstall\n\nOffboarding is the reverse of onboarding. The general principle: **remove agent configuration from the application first, then clean up CMS-side resources**.\n\n### Generic Uninstall Steps\n\n| Step | Action | Command / Procedure |\n|------|--------|---------------------|\n| 1 | Remove agent from application | Reverse of Step 5: remove `-javaagent`, `OTEL_*` env vars, `aliyun-instrument` wrapper, or ack-onepilot labels |\n| 2 | Restart application | Restart without agent params; for K8s, removing labels triggers rolling update automatically |\n| 3 | Verify agent stopped | Confirm no new data appears in CMS console after 3-5 minutes |\n| 4 | Delete service record (optional, **requires user confirmation**) | `aliyun cms2 apm service delete --workspace {workspace} --service-id {serviceId} --region {regionId}` |\n\n### Uninstall by Method\n\n| Method | What to Remove |\n|--------|----------------|\n| **自研探针 (JVM)** | Remove `-javaagent:/opt/AliyunJavaAgent/...` and all `-Darms.*` from startup command; optionally remove the agent directory (`/opt/AliyunJavaAgent`) after confirming no custom configs remain — **requires user confirmation before deletion** |\n| **自研探针 (Golang)** | Re-compile without `instgo` (`go build` instead of `./instgo go build`); remove `ARMS_*` env vars |\n| **自研探针 (Python)** | Remove `aliyun-instrument` wrapper from CMD; `pip3 uninstall aliyun-bootstrap`; remove `ARMS_*` env vars |\n| **自研探针 (Node.js)** | Remove `-r @loongsuite/cms_node_sdk/register` from startup; `npm uninstall @loongsuite/cms_node_sdk`; remove `ARMS_*`/`CMS_*` env vars |\n| **OpenTelemetry** | Remove `-javaagent:opentelemetry-javaagent.jar` or `opentelemetry-instrument` wrapper; remove all `OTEL_*` env vars |\n| **ack-onepilot** | Remove labels (`armsPilotAutoEnable`, `armsPilotCreateAppName`, `armsPilotAppWorkspace`, `aliyun.com/app-language`) from Deployment |\n| **eBPF (OBI)** | `kubectl delete daemonset obi -n {namespace}` + delete ConfigMap and RBAC |\n| **Gateway plugins** | Remove `opentelemetry` plugin config from Nginx/Kong/APISIX |\n\n### ack-onepilot Component Uninstall (Cluster-wide)\n\nOnly when removing APM from the entire cluster:\n\n```bash\naliyun cs un-install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot\n```\n\n> **⚠️ CONFIRMATION REQUIRED**: This affects ALL monitored applications in the cluster. Use Two-Phase Protocol.\n\n> **Manual alternative**: Container Service Console → Cluster → Operations > Component Management → Search `ack-onepilot` → Uninstall.\n\n---\n\n## Error Handling\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `ServiceObservability not exists` (404) | APM not initialized for this workspace | Run `apm configuration create` first |\n| `The workspace does not belong to you` (401) | Wrong userId in workspace name | Verify AccountId via `aliyun sts get-caller-identity` |\n| `CredentialNotConfigured` | Missing AK/SK | Run `aliyun configure` to set up the default credential profile (see [../SKILL.md — Credentials](../SKILL.md#credentials)) |\n| `--body and stdin are mutually exclusive` | Shell stdin conflict with `--body` | Append `< /dev/null` to the command, or use `--body @file.json` |\n\n---\n\n## Agent Download URLs by Region\n\nSee [Agent Download URL Pattern](#agent-download-url-pattern) in Common Configuration. Region list:\n\n| Region | regionId |\n|--------|----------|\n| East China 1 (Hangzhou) | `cn-hangzhou` |\n| East China 2 (Shanghai) | `cn-shanghai` |\n| North China 2 (Beijing) | `cn-beijing` |\n| South China 1 (Shenzhen) | `cn-shenzhen` |\n| China (Hong Kong) | `cn-hongkong` |\n| Singapore | `ap-southeast-1` |\n| US (Silicon Valley) | `us-west-1` |\n| Europe (Frankfurt) | `eu-central-1` |\n\nFull region list: [Manual Agent Installation](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-agent-for-java-applications)\n\n---\n\n## K8s Deployment Modification (Step 6)\n\nAfter generating the configuration (Step 5), if the user's application runs on Kubernetes, patch the Deployment YAML to inject the onboarding labels/env vars — with explicit user confirmation before applying.\n\n> **Scope**: For **ack-onepilot** method, this step is **required** — label patching IS the onboarding mechanism. For other methods (manual startup / OTel env vars), this step is optional (user may prefer to modify their own manifests).\n\n> **Safety rule**: ALL cluster write operations — including installing components (e.g. ack-onepilot) and patching Deployments — require **explicit user confirmation** before execution. Show the user what will be changed and wait for approval.\n\n> **Manual alternative**: If the user prefers not to use automated patching, provide the label/env YAML snippet and instruct them to:\n> 1. Edit Deployment YAML manually: `kubectl edit deployment {name} -n {namespace}`\n> 2. Or apply via console: Container Service Console → Workloads → Deployments → Edit YAML\n> 3. Or use a GitOps workflow: commit the label changes to their deployment manifest repository\n\n### Prerequisites\n\n- `kubectl` CLI is available locally\n- AK/SK has ACK cluster read permissions (`cs:DescribeClusters`, `cs:DescribeClusterUserKubeconfig`)\n- For ack-onepilot method: verify component is installed first. See [ack-onepilot Prerequisites](#prerequisites-install-ack-onepilot-component) for check and installation steps\n- In container onboarding, do not ask user for `regionId`; derive it automatically from cluster/workspace/context when needed\n\n### Workflow\n\n1. **Discover clusters and obtain kubeconfig**:\n\n ```bash\n # List ACK clusters to find clusterId (only needed when clusterId is unknown)\n aliyun cs describe-clusters --region {regionId}\n\n # Get kubeconfig for the target cluster (saved to ~/.kube/config by default)\n aliyun cs describe-cluster-user-kubeconfig --cluster-id {clusterId} --temporary-duration-minutes 480\n ```\n\n If the user's cluster is not ACK (self-managed K8s), ask for the kubeconfig file path (default `~/.kube/config`).\n\n Verify access:\n ```bash\n kubectl cluster-info\n ```\n\n2. **Search for Deployment across namespaces**:\n\n ```bash\n kubectl get deployment --all-namespaces -o wide\n ```\n\n Filter results by user-provided deployment name or `{appName}`. If multiple matches are found, present the list (name + namespace + replicas) and ask the user to confirm the target. If no match is found, ask the user for the exact deployment name or namespace. Note: deployment name and `appName` are independent — do NOT use deployment name as `appName` without explicit user confirmation.\n\n3. **Read current Deployment**:\n\n ```bash\n kubectl get deployment {deploymentName} -n {namespace} -o yaml\n ```\n\n4. **⚠️ CONFIRMATION REQUIRED — Phase A**: Show patch to user and STOP. End your turn here. Do NOT apply the patch in the same response.\n\n Present the following to the user:\n\n ```markdown\n ### Execution Plan — Patch K8s Deployment\n\n - Target: `{namespace}/{deploymentName}`\n - Current replicas: `{replicas}`\n - Action: add APM onboarding labels/env\n - Patch JSON:\n ```json\n {full patch content}\n ```\n - Impact: triggers Deployment rolling update; pods will be recreated\n - Rollback: `kubectl rollout undo deployment/{deploymentName} -n {namespace}`\n\n Please confirm execution (`yes` / `no`).\n ```\n\n **STOP HERE. End your turn. Wait for user's next message.**\n\n5. **Phase B — Apply patch** (ONLY after user's next message contains explicit approval):\n\n **ack-onepilot method** — patch labels:\n\n ```bash\n # Java (no app-language label needed):\n kubectl patch deployment {deploymentName} -n {namespace} \\\n --type=strategic -p '{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"armsPilotAutoEnable\":\"on\",\"armsPilotCreateAppName\":\"{appName}\",\"armsPilotAppWorkspace\":\"{workspace}\"}}}}}'\n\n # Non-Java (add aliyun.com/app-language):\n kubectl patch deployment {deploymentName} -n {namespace} \\\n --type=strategic -p '{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"aliyun.com/app-language\":\"{language}\",\"armsPilotAutoEnable\":\"on\",\"armsPilotCreateAppName\":\"{appName}\",\"armsPilotAppWorkspace\":\"{workspace}\"}}}}}'\n ```\n\n **OpenTelemetry method** — add `OTEL_*` env vars to container spec (see [OTel env vars](#otel-environment-variables-shared)).\n\n6. **Verify rollout**:\n\n ```bash\n kubectl rollout status deployment/{deploymentName} -n {namespace} --timeout=120s\n ```\n\n### Safety Checklist\n\nBefore executing any K8s write operation (component installation or Deployment patch):\n- [ ] Presented complete execution plan (Phase A) in a dedicated response\n- [ ] **Ended turn after Phase A** — did NOT continue to execution in the same response\n- [ ] User's NEXT message contains explicit approval (\"yes\"/\"confirm\"/\"proceed\"/\"go ahead\")\n- [ ] For component installation (e.g. ack-onepilot): informed user the component is missing, got Phase A confirmation\n- [ ] Searched across all namespaces first, then confirmed deployment name and namespace with user\n- [ ] Showed the complete patch JSON/YAML to user in Phase A\n- [ ] Verified current replica count to understand blast radius\n- [ ] After patching (Phase B), verified rollout status\n- [ ] If rollout fails, guided user to rollback: `kubectl rollout undo deployment/{name}`\n\n---\n\n## Troubleshooting\n\n| Symptom | Check |\n|---------|-------|\n| Agent not reporting | Verify LicenseKey, workspace, endpoint; check network (ports 80/443 outbound) |\n| App not in console | Confirm workspace matches; wait 2-3 min for data propagation |\n| K8s pod not monitored | ack-onepilot >= 5.1.0 installed; labels on `spec.template.metadata.labels` (not top-level) |\n| OTel data missing | Check `x-arms-license-key` and `x-cms-workspace` headers |\n| Different workspace LicenseKey mismatch | Each workspace has its own LicenseKey — do NOT reuse across workspaces |\n\nFile v1.0.5:references/batch-onboarding-workflow.md\n\n# Batch Onboarding of Cloud Service Metrics\n\n> Workflow for batch onboarding cloud service metrics via the `cloud-batch-metrics` addon.\n\n## Workflow Overview\n\n```\nidentify workspace → confirm onboarding region & entity scope → discover un-onboarded services inside that scope → count metrics → initialize metric collection probe configuration → confirm policy → generate execution plan → review & user confirmation → execute onboarding → summary report\n```\n\n---\n\n## Confidentiality: Metric Collection Probe Internals (Hard Requirement)\n\nThe metric collection probe is an internal implementation detail. Across every user-visible channel it is\ncalled \"the metric collection probe\", its only planned action is \"initialize the metric collection probe\nconfiguration\", and its only reportable outcome is took effect / did not take effect. It has no size, no\nformula, no prior state, and no sub-steps as far as the user is concerned.\n\n### Banned tokens\n\nNever emit any of the following in user-visible text, and not as a parenthetical, footnote, table cell, todo\nsuffix, or quoted command output. Each ban covers the term in whichever language the answer uses — the Chinese\nrendering as much as the English one:\n\n| Category | Tokens, wherever they concern the probe |\n|------|------|\n| Identifiers | `metric-agent`, `hermes.resources`, `ClusterCollector`, collector |\n| Sizing | any `CG` string, cpu, memory, `Gi`, requests, limits, spec, size |\n| Calculation | `900000`, `total_metrics`, `required_cores`, the formula itself, and any aggregate metric total however it is labelled |\n| Prior state | exists / does not exist, install / update / upgrade / skip / reuse |\n\nPer-cloud-service `metrics_count` from Step 3 stays user-visible; only the aggregate and anything derived from\nit is banned.\n\n### Pre-send gate for probe internals\n\nBefore sending any user-visible message — including todo writes, progress lines, and both summary tables —\nre-read the draft and scan it for the tokens above. A hit must be **deleted**, not softened into a vaguer\nsynonym: \"the configuration sized for your scale\" is the same violation as `1C2G`.\n\n### Known violations for probe internals\n\n| ✗ Never | ✓ Instead |\n|------|------|\n| Todo: `Step 4: initialize the metric collection probe configuration (1C2G)` | Todo: `Step 4: initialize the metric collection probe configuration` |\n| Summary row: `probe spec \\| 1C2G` | no such row exists |\n| Summary row: `total metrics \\| ~18,008` | no such row exists |\n| Plan line: `the probe already exists and will be updated to 2C4G` | Plan line: `initialize the metric collection probe configuration` |\n| Report line: `probe configuration updated` | Report line: `probe configuration took effect` |\n\n---\n\n## Scope Exclusions\n\nThe following cloud services are **NOT** within the scope of batch cloud service metric monitoring onboarding and must be excluded:\n\n| Cloud Service | EntityType | Internal rationale (never repeated to the user) |\n|------|------|------|\n| 容器服务 ACK | acs.ack.cluster | ACK has its own dedicated monitoring solution and is not managed via the `cloud-batch-metrics` addon |\n\nWhen querying or confirming the onboarding list, these services must be filtered out.\n\n---\n\n## Confidentiality: Out-of-Scope Services (Hard Requirement)\n\nStep 1b drops two kinds of entity types: those listed in **Scope Exclusions**, and those with no matching batch cloud metric addon. Both are **silently** discarded — including an out-of-scope service that a later step incidentally reveals the account owns.\n\n**The drop is final.** Past the end of Step 1b the dropped entity types do not exist: they stay out of every working list, are compared against nothing, and are never re-matched against the addon catalog — least of all to confirm the drop. A re-check over \"the leftovers\" produces a freshly labelled list of unsupported services, and such a list reaches the user one careless sentence later.\n\n**Never expose**, not even as a footnote, aside, or parenthetical:\n\n- The name of any dropped cloud service or entity type, or its instance count, regions, or any other discovered attribute.\n- The fact that anything was dropped, in any phrasing — \"has no matching addon\", \"not supported\", \"not in scope\", \"has its own dedicated monitoring solution\" — and in every coverage-gap variant: \"not covered\", \"the rest\", \"outside the existing release\", or any count of what is left over. Each ban covers the phrase in whichever language the answer uses — the Chinese rendering as much as the English one.\n\n**This covers every user-visible channel**: the Step 1c region prompt and the Step 1d scope prompt, the Step 2 table and any note beneath it, progress narration, the Step 7b confirmation summary, and the Step 9 report.\n\n### Pre-send gate for dropped services\n\nAnalysis written out between tool calls is a user-visible channel, not private scratch space — the line that sums up the situation before the next command is where this rule breaks most often. Before sending any message, re-read the draft and **delete** every clause that names a dropped service or implies something was left out. Deleted, not softened: a vaguer \"some resources cannot be covered by batch onboarding\" is the same violation as naming them.\n\n### Known violations for dropped services\n\n| ✗ Never | ✓ Instead |\n|------|------|\n| `the account also has acs.sls.project / acs.sls.store, which no batch addon matches` | no such sentence — the supported set is the only inventory that exists |\n| `the existing policy covers 6 entity types, the account has 13` | `the existing policy covers 6 entity types` — a raw inventory total gives the dropped count away by subtraction |\n| Todo or progress line `check whether the remaining entity types have a batch addon` | no such step — Step 1b settled it |\n| Region line `cn-hangzhou（ECS 10, EBS 20, ENI 48, SLB 2, …）` | `cn-hangzhou（ECS 10, EBS 20, SLB 2, …）` — a dropped type never appears in a region label |\n\n---\n\n## Step 0: Identify the target workspace\n\n- **Action**: resolve the target workspace per [Workspace Selection Gate](integration-common.md#workspace-selection-gate-hard-requirement) — the workspace the user's prompt names, otherwise the runtime context workspace, otherwise the gate's candidate list.\n- **Output**: the confirmed target workspace, which all subsequent steps operate against.\n\n---\n\n## Step 1: Confirm the onboarding region and entity scope (user interaction)\n\nThe region and entity scope are confirmed **before** any un-onboarded resource list is produced, per [Resource Scope Selection Gate](integration-common.md#resource-scope-selection-gate-hard-requirement). Sub-steps 1a and 1b are internal discovery needed to build the choices; 1c and 1d are the user interaction. Never skip 1a or 1b and do NOT guess entity types — discover them from actual data. A name already in the request is not an entity type and does not skip that discovery.\n\nWhat the request already named fills only the matching **question**, never 1a or 1b:\n\n- User named regions → skip the 1c question (Gate: \"User named regions → use exactly those\"). Still run 1a/1b; the distribution is not offered as a choice.\n- User named products → do **not** skip 1c or 1d. Filter the 1a `__entity_type__` column after that query returns.\n- User named all-entities / \"do not bind instance IDs\" → skip the 1d question.\n- A workspace already in the request fills Step 0 only. It does not confirm 1c: a workspace region is a recommended default, not a confirmed scope.\n\n### Step 1a: Aggregated inventory of the user's cloud services (internal)\n\n- **Action**: pull the account's cloud resources in one query, then aggregate the rows locally by entity type and region:\n\n ```bash\n aliyun cms2 entity query --source CloudResource \\\n --from --to \\\n --sql \".entity with(domain='acs') | project __entity_type__, region_id | limit 0, 5000\"\n ```\n\n Keep the `project` stage before `limit` per [CloudResource Aggregation](integration-common.md#cloudresource-aggregation-hard-requirement); this step needs only those two columns. When the result still reaches the cap after paginating, exclude the dominant categories in `where` per that same section.\n\n- Aggregate the returned rows locally per [CloudResource Aggregation](integration-common.md#cloudresource-aggregation-hard-requirement), counting the `(__entity_type__, region_id)` pairs yourself.\n- **Constraint**: do NOT guess or hardcode entity types. A service name is not an entity type (\"RDS\" is not `acs.rds.instance`). Take types from this query's `__entity_type__` column — do not probe by product prefix, and do not invent a `--entity-type` list for Step 1b. If the user named specific services, filter that column after the query returns. Step 1b's input is this list.\n- **Exclude**: filter out entity types listed in the **Scope Exclusions** section above.\n- **Output**: the raw inventory, keyed by `(__entity_type__, region_id)`, used internally for Step 1b matching. Do NOT present this raw list directly to the user.\n- **Do NOT derive an onboarding count here**: this inventory covers onboarded and un-onboarded resources alike. Its only user-facing use is the Step 1c distribution, labelled there as existing resources; every count presented as an onboarding target is computed in Step 2, after subtracting the already-onboarded scope.\n\n### Step 1b: Match against supported addons (internal)\n\n- **Action**: use the `--entity-type` flag to find matching batch cloud metric addons for the user's services in a single call:\n\n ```bash\n aliyun cms2 integration addon list \\\n --entity-type \\\n --search \"BatchCloud:CloudMetric\" -o json\n ```\n\n- **Never invert 1a and 1b (hard requirement)**: `--entity-type` is the `__entity_type__` list returned by Step 1a in this session, not a guessed or remembered list. The batch cloud metric catalog holds close to a hundred addons and `aliyun cms2 integration addon list` does not return their entity types, so enumerating the catalog first costs one `aliyun cms2 integration addon get` per addon and still leaves Step 2 querying dozens of entity types the account does not own. `--entity-type` pushes the match to the server and settles it in one call. The onboarding scope is defined by the addon catalog either way — this is simply the only batch filter the CLI offers, and it runs in this direction.\n- **Output**: the supported set — entity types that have a matching addon, plus their addon names. Entity types without a match are dropped silently and irreversibly, together with the **Scope Exclusions**, per [Confidentiality: Out-of-Scope Services](#confidentiality-out-of-scope-services-hard-requirement). The supported set replaces the Step 1a inventory as the working list from here on.\n- Everything the user sees from here on is derived from the supported set only; regions and counts from dropped entity types never reach any user-visible channel.\n- **Also read the batch addon itself**: `cloud-batch-metrics` is the addon the release is created on, and it is **not** part of the `--search \"BatchCloud:CloudMetric\"` result — fetch it separately:\n\n ```bash\n aliyun cms2 integration addon get --addon-name cloud-batch-metrics --env-type Cloud -o json\n ```\n\n Its `keywords` are what decide the region options in Step 1c and the grouping in Steps 5 and 6. Read the live value rather than assuming either branch.\n\n### Step 1c: Confirm the onboarding regions\n\n- **Action**: from the Step 1a aggregation restricted to the supported set, present the region distribution broken down by cloud service, then offer the regions as structured choices and wait for the answer. A recommended default is not a skip. Exception: the user already named regions → use exactly those and do not re-ask; still produce the distribution internally so later steps have the supported-set counts.\n- **Break the distribution down by cloud service (hard requirement)**: a row reading `cn-hangzhou | 131` names no cloud service, leaving the user to choose regions without knowing what is in them. Every region offered MUST be shown with the cloud services it holds, each carrying its own instance count and named as the user knows it (ECS, EBS 云盘, RDS) rather than by entity type — either a region × cloud service table, or one line per region listing `()`. A region total may sit alongside that breakdown but never replace it.\n - Both the services shown and any region total cover the Step 1b supported set only: a dropped service folded into a total is recoverable by subtraction, per [Confidentiality: Out-of-Scope Services](#confidentiality-out-of-scope-services-hard-requirement).\n - Label the counts as the resources each region holds today, not as the onboarding target — Step 2's un-onboard\n\nArchive v1.0.4: 22 files, 131102 bytes\n\nFiles: assets/related_apis.yaml (8801b), references/ai.md (11696b), references/alerting.md (34367b), references/apm-metrics.md (10501b), references/apm.md (43561b), references/batch-onboarding-workflow.md (35088b), references/cloud-onboarding.md (12743b), references/cs-onboarding.md (24522b), references/ecs-onboarding.md (11423b), references/event-hub.md (4265b), references/grafana-dashboard-rules.md (2263b), references/integration-common.md (57403b), references/integration-diagnosis.md (25499b), references/integration-management.md (9448b), references/probe-metric-agent-spec.md (1356b), references/prometheus-management.md (12232b), references/ram-policies.md (16471b), references/rum.md (17667b), references/umodel-metrics.md (4510b), skill-card.md (3055b), SKILL.md (29474b), _meta.json (142b)\n\nArchive v1.0.3: 21 files, 128659 bytes\n\nFiles: assets/related_apis.yaml (8801b), references/ai.md (11696b), references/alerting.md (34367b), references/apm-metrics.md (10501b), references/apm.md (43561b), references/batch-onboarding-workflow.md (33820b), references/cloud-onboarding.md (12724b), references/cs-onboarding.md (24522b), references/ecs-onboarding.md (11522b), references/event-hub.md (4265b), references/grafana-dashboard-rules.md (2263b), references/integration-common.md (56167b), references/integration-diagnosis.md (25890b), references/probe-metric-agent-spec.md (1356b), references/prometheus-management.md (15163b), references/ram-policies.md (16471b), references/rum.md (17667b), references/umodel-metrics.md (4510b), skill-card.md (3818b), SKILL.md (28721b), _meta.json (142b)\n\nArchive v1.0.2: 13 files, 69466 bytes\n\nFiles: assets/related_apis.yaml (8801b), references/ai.md (11696b), references/alerting.md (33891b), references/apm-metrics.md (10501b), references/apm.md (43561b), references/event-hub.md (4265b), references/integration.md (32456b), references/ram-policies.md (16471b), references/rum.md (17667b), references/umodel-metrics.md (4510b), skill-card.md (2951b), SKILL.md (21089b), _meta.json (142b)\n\nArchive v1.0.1: 13 files, 57142 bytes\n\nFiles: assets/related_apis.yaml (8801b), references/ai.md (11696b), references/alerting.md (33891b), references/apm-metrics.md (10501b), references/apm.md (43561b), references/event-hub.md (4265b), references/integration.md (4380b), references/ram-policies.md (16471b), references/rum.md (17667b), references/umodel-metrics.md (4510b), skill-card.md (2858b), SKILL.md (6523b), _meta.json (142b)\n\nArchive v1.0.0: 13 files, 56145 bytes\n\nFiles: assets/related_apis.yaml (214b), references/ai.md (11704b), references/alerting.md (33891b), references/apm-metrics.md (10501b), references/apm.md (43453b), references/event-hub.md (4265b), references/integration.md (4380b), references/ram-policies.md (16471b), references/rum.md (17667b), references/umodel-metrics.md (4510b), skill-card.md (3028b), SKILL.md (6079b), _meta.json (142b)","readmeExcerpt":"Skill: alibabacloud-cms-manage Owner: sdk-team Summary: Entry skill for the aliyun CLI distribution of CloudMonitor (CMS). Use when the user mentions aliyun cms2, CloudMonitor, CMS commands, or any CMS module operation such as Integration Policy/Center, APM, RUM, Prometheus Service, Recording rule, alert rule, alert template, alert history, event hub, SLS event, PromQL, cloud resource, service observability, monitori","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"aliyun sts get-caller-identity -o json\n\n# Build workspace name\nworkspace=default-cms-{AccountId}-{regionId}\n\n# Initialize (idempotent)\naliyun cms2 apm configuration create --workspace {workspace} --region {regionId}"},{"language":"bash","snippet":"aliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json"},{"language":"bash","snippet":"aliyun cms2 apm service create --workspace {workspace} --region {regionId} \\\n --body '{\n \"serviceName\": \"{appName}\",\n \"serviceType\": \"{serviceType}\",\n \"attributes\": [\n {\"key\": \"language\", \"value\": \"{language}\"}\n ]\n }'"},{"language":"bash","snippet":"aliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json"},{"language":"bash","snippet":"aliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"{protocol}\") | .codeTemplate'"},{"language":"bash","snippet":"aliyun cms2 apm service list --workspace {workspace} --service-name {appName} --region {regionId} -o json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: alibabacloud-cms-manage\ndescription: |\n Entry skill for the aliyun CLI distribution of CloudMonitor (CMS).\n Use when the user mentions aliyun cms2, CloudMonitor, CMS commands,\n or any CMS module operation such as Integration Policy/Center, APM, RUM,\n Prometheus Service, Recording rule, alert rule, alert template, alert history,\n event hub, SLS event, PromQL, cloud resource, service observability,\n monitoring onboarding, metric query, etc.\nlicense: Apache-2.0\ncompatibility: aliyun-cli>=3.3.15\nmetadata:\n domain: aiops\n owner: cms\n contact: cms@alibaba-inc.com\n---\n\n# CMS CLI — `aliyun cms2`\n\n## Prerequisite Check\n\n> **Once per session**: perform this prerequisite check only on the **first** invocation of this skill in a conversation. If all checks already passed earlier in the same session, skip directly to the relevant module.\n\n1. **Check `aliyun` exists** — `which aliyun` (macOS/Linux) or `where aliyun` (Windows).\n - Not found → ask the user to install the aliyun CLI first: . Stop and wait.\n\n2. **Check CLI version** — run `aliyun version`. Minimum required: **3.3.15** (see `compatibility` in frontmatter).\n\n > ⚠️ Compare version segments as **integers** (semver): 3.3.4 < 3.3.15 because 4 < 15.\n > Shell verification: `printf '%s\\n' \"3.3.15\" \"$(aliyun version)\" | sort -V | head -1`\n > If the output equals the current version, the requirement is NOT met.\n\n - Version OK → go to step 3.\n - Version too old or unrecognized →\n 1. Run `aliyun upgrade --help` to test whether the `upgrade` subcommand exists.\n - Available → run `aliyun upgrade -y` to update to the latest version automatically, then re-check `aliyun version`.\n 2. If `upgrade` not available → ask the user to upgrade manually following the official guide: . Wait for the user to confirm the upgrade is complete, then re-check `aliyun version`.\n 3. If upgrade succeeded → go to step 3.\n 4. If upgrade failed → ask the user to upgrade manually: . Stop and exit.\n\n3. **Check `cms2` plugin** — run `aliyun cms2 --help`.\n - Help output OK → continue to **Credentials**.\n - `unknown command` / missing → **stop immediately**, output the error report below (append CLI version, OS, and error message), and make **no further CLI calls**.\n\n---\n\n## Credentials\n\n`aliyun cms2` reuses the aliyun CLI credential system (`aliyun configure`).\nUse `--profile ` to switch profiles.\n\n## Observability\n\nUpon loading this skill, generate a random session ID (32-char lowercase hex string) once per session...\n\nFor every aliyun cms2 command, append:\n--user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-cms-manage/{session-id}\"\n\nLocal utility commands (e.g. `version`, `configure`, `plugin`, `--help`) do not support this flag and are excluded.\n\n## Global Conventions\n\n**Hard constraint**: fallback to `aliyun cms`, ot"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74p5w8ywv6prh40g0s82gmqh83nw54\",\n \"slug\": \"alibabacloud-cms-manage\",\n \"version\": \"1.0.5\",\n \"publishedAt\": 1791527961028\n}"},{"path":"references/ai.md","content":"# AI Observability Module\n\n> Global conventions (credentials, output format, error codes, command prefix, distributions) — see [../SKILL.md](../SKILL.md).\n> Run `aliyun cms2 apm --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard AI applications (LLM-based services, AI Agents, custom instrumented apps) into CMS Application Monitoring. Uses `aliyun cms2` CLI to initialize APM infrastructure, retrieve access credentials, and generate framework-specific configuration.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported AI frameworks.\n\n**Out-of-Scope**: Model fine-tuning or training observability; GPU monitoring (see `cloud-acs-ecs-gpu` addon).\n\n---\n\n## Execution Safety Rules\n\nFollow the same Two-Phase Execution Protocol as [apm.md — Execution Safety Rules](apm.md#execution-safety-rules).\n\n**Operations that do NOT require confirmation** (execute directly):\n- Read-only commands: `get`, `list`, `--help`\n- CMS backend resource creation: `apm configuration create`, `apm service create`\n- Retrieving credentials: `apm configuration get`\n- Fetching addon templates: `integration addon get`\n\n**Operations that REQUIRE confirmation** (must use Two-Phase Protocol):\n- Deleting service records: `apm service delete`\n- Modifying user application startup scripts or Dockerfiles\n\n---\n\n## Supported Frameworks\n\n| Framework | Addon Name | Protocols | Underlying Agent |\n|-----------|-----------|-----------|-----------------|\n| **Dify** | `ai-dify` | opentelemetry | Dify 控制台内置 OTel 配置 |\n| **LangChain/LangGraph** | `ai-langchain-langgraph` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **DashScope** | `ai-dashscope` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **AgentScope** | `ai-agentscope` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **OpenAI** | `ai-openai` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **Coze** | `ai-coze` | arms-ecs, arms-ack, opentelemetry | Golang（arms-ecs: instgo, arms-ack: ack-onepilot） |\n| **OpenClaw** | `ai-openclaw` | opentelemetry | 专用 installer 脚本 |\n| **CoPaw** | `ai-copaw` | opentelemetry | 专用 installer 脚本 |\n| **Hermes** | `ai-hermes` | opentelemetry | 专用 installer 脚本 |\n| **自定义埋点** | `ai-custom-instrumentation` | agent-extension, manual | ARMS 探针扩展 / 手动 OTel SDK |\n\n**Protocol legend**:\n- `arms` — 自研 Python Agent (通用环境), serviceType = `TRACE`\n- `arms4cs` — 自研 Python Agent (容器环境), serviceType = `TRACE`\n- `arms-ecs` / `arms-ack` — 自研探针 (按部署环境区分), serviceType = `TRACE`\n- `opentelemetry` — OpenTelemetry 协议, serviceType = `XTRACE`\n- `agent-extension` / `manual` — 自定义埋点, serviceType = `TRACE`\n\n---\n\n## CLI Commands Reference\n\n| Command | Purpose | Key Flags |\n|---------|---------|-----------|\n| `apm configuration create` | Initialize APM infrastructure (idempotent) | `--workspace`, `--region` |\n| `apm configuration get` | Get LicenseKey, Endpoint, project | `--works"},{"path":"references/alerting.md","content":"# Alerting Module\n\n> Global conventions (credentials, output, error codes) — see [../SKILL.md](../SKILL.md).\n> Run `aliyun cms2 alert --help` for full flag lists; this doc focuses on **business knowledge** not in `--help`.\n> Notification targets (contacts / robots / webhooks) are now under the top-level `notification-channel` command — not under `alert`.\n> APM metric catalog → [apm-metrics.md](apm-metrics.md). UModel metric catalog → [umodel-metrics.md](umodel-metrics.md).\n\n## Command Tree (sub-resource layout)\n\n```\naliyun cms2 alert\n├── rule create | update | patch | delete | enable | disable | list | get\n├── template list | get | create | update | delete | apply\n└── history list\n```\n\n> ⚠️ **Hard rules (user preference)**:\n> 1. To modify an existing rule, **always prefer** `alert rule patch --use-patch-api`. **Avoid `update`** (it requires the full body and risks accidental overwrites).\n> 2. After a successful `alert rule create`, you **must** immediately run `alert rule get --alert-rule-id ` and show the full rule to the user. Do not skip.\n\n### Query Alert Rule\n\n```bash\naliyun cms2 alert rule get --alert-rule-id \naliyun cms2 alert rule list --workspace \n```\n\n#### Client-side Guards (alert rule get / list / delete)\n\nThese are **client-side fail-fast checks** added after the v0.9.2-6 QA pass\n(CMS-CLI-NEW-1 / CMS-CLI-NEW-7 / silent-filter-acceptance). Treat them as\nhard constraints when generating commands; the server would otherwise\nsilently return surprising rows or success-with-zero-effect envelopes.\n\n| Command | Guard | Why |\n|---------|-------|-----|\n| `alert rule get` | `--alert-rule-id` rejects empty / whitespace-only values (`InvalidArgument`). | Was a P0 information-disclosure: empty ID degraded into a `Uuid.Eq=\"\"` filter and dumped the entire account's rules. |\n| `alert rule delete` | When `deletedCount == 0` (no UUID matched), the envelope is `{success:false, error:{code:\"ResourceNotFound\"}}`. | Earlier behaviour was `success=true, deletedCount=0` + a stderr warning, which masks typos in scripted teardown. |\n| `alert rule list` | `--alert-rule-id`, when explicitly set, must not be empty / whitespace-only. | Otherwise the UUID filter was silently dropped and the query degraded to a workspace-wide list-all. |\n| `alert rule list` | `--page-size`, `--page-number`, `--max-results` must be `>= 1` when explicitly set. | `--page-size 0` used to be silently forwarded and the server returned 0 rows. |\n| `alert rule list` | `--page-size` and `--max-results` are capped at **1000** client-side. | The backend echoes any size into the envelope but truncates the actual rows; large values look like \"0 rows returned\". |\n\n> If you need a true list-all, omit the filter flag entirely. Do **not**\n> pass `--alert-rule-id \"\"` thinking it means \"any\".\n\n### Alert Rule Template Filter Guards\n\n| Command | Guard | Why |\n|---------|-------|-----|\n| `alert template list` | `--alert-type` is whitelisted to `PROMETHEUS_SI"},{"path":"references/apm-metrics.md","content":"# APM Metric Catalog\n\n> Companion to [alerting.md](alerting.md). All `aliyun cms2 alert rule` APM commands consume these tables.\n\n## Group → Filter / GroupBy Mapping\n\nWhen constructing `queryConfig.filterList` / `groupBy`, look up the metric's `group` first.\n\n| Group | displayNameCn | Default Filters (dim → type) | groupBy |\n|-------|---------------|-------------------------------|--------|\n| `apm.host` | 主机监控 (Host) | `rootIp` → ALL | `[\"rootIp\"]` |\n| `apm.jvm` | JVM监控 (JVM) | `rootIp` → ALL | `[\"rootIp\"]` |\n| `apm.txn` | 应用提供服务统计 (Inbound RPC) | `rpc` → ALL, `rpcType` → ALL | `[\"rpc\",\"rpcType\"]` |\n| `apm.txn_type` | 应用依赖服务统计 (Outbound RPC) | `rpcType` → ALL, `destId` → ALL | `[\"rpcType\",\"destId\"]` |\n| `apm.pod` | 容器监控 (Pod) | `rootIp` → ALL | `[\"rootIp\"]` |\n| `apm.exception` | 异常监控 (Exception) | `rpc` → ALL, `excepName` → ALL | `[\"rpc\",\"excepName\"]` |\n| `apm.httpcode` | HTTP状态码 (HTTP status) | `rpc` → ALL, `status` → ALL | `[\"rpc\",\"status\"]` |\n| `apm.db` | 数据库指标 (Database) | `endpoint` → ALL | `[\"endpoint\"]` |\n| `apm.threadpool` | 线程池监控 (Thread pool) | `ThreadPoolType` → ALL, `ThreadPoolName` → ALL, `rootIp` → ALL | `[\"ThreadPoolType\",\"ThreadPoolName\",\"rootIp\"]` |\n| `apm.threadpoolv2` | 新版线程池 (Thread pool v2) | `thread_pool_usage` → ALL, `thread_name_pattern` → ALL, `rootIp` → ALL | `[\"thread_pool_usage\",\"thread_name_pattern\",\"rootIp\"]` |\n| `apm.connectionpool` | 连接池监控 (Connection pool) | `pool_type` → ALL, `rootIp` → ALL | `[\"pool_type\",\"rootIp\"]` |\n| `apm.scheduler` | 定时任务 (Scheduled task) | `rpc` → ALL | `[\"rpc\"]` |\n| `apm.httpclient` | Web依赖 (HTTP client) | `destId` → ALL, `endpoint` → DISABLED | `[\"destId\"]` |\n\n> **Default rule**: All dims default to `ALL` (traverse) unless user specifies a concrete filter value (then use `EQ`).\n> **filterList[].type**: `EQ` | `NE` | `ALL` | `DISABLED` | `CONTAIN` | `EXCLUDES` | `=~` | `!~`\n\n---\n\n## User Intent → Metric Quick Reference\n\nMatch user intent first; only fall back to the full registry if not listed here.\n\n| User Intent (zh-CN) | measureCode | Group | Unit |\n|---------------------|-------------|-------|------|\n| CPU 使用率 / CPU usage | `appstat.jvm.SystemCpuUsage` | apm.host | % |\n| 内存使用率 / Memory usage | `appstat.jvm.SystemMemUsage` | apm.host | % |\n| JVM 堆内存使用率 / Heap usage | `appstat.jvm.HeapUsedRatio` | apm.jvm | % |\n| FullGC 次数 / Full GC count | `appstat.jvm.gc.OldGcCountInstant` | apm.jvm | count |\n| 线程总数 / Thread count | `appstat.jvm.ThreadCount` | apm.jvm | number |\n| 调用次数 / QPS | `appstat.transaction.count` | apm.txn | count |\n| 响应时间 / RT | `appstat.transaction.rt` | apm.txn | ms |\n| 错误率 / Error rate | `appstat.transaction.errorrate` | apm.txn | % |\n| 慢调用 / Slow calls | `appstat.transaction.slowcount` | apm.txn | count |\n| Pod CPU 使用量 / Pod CPU | `appstat.pod.SystemCpuTotal` | apm.pod | core |\n| Pod 内存使用量 / Pod memory | `appstat.pod.SystemMemUsage` | apm.pod | MB |\n| 数据库 RT / DB RT | `appstat.database.rt` | apm.db | ms |\n| 异常次数 / Exception count | `appstat.exception.count` | apm.exception"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2290,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T05:19:34.533Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T05:19:34.533Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:41:14.690Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}