Alibabacloud Livedebug

Live-Debug Runtime Diagnostics

Product scope: This skill builds and manages Live-Debug ServiceTask diagnostics on Alibaba Cloud CMS (aliyun cms2 apm service-task) and queries capture results via SLS. It does not onboard APM/agents and is not a general CloudMonitor (CMS) management skill.

Prerequisite Check

1. Check aliyun exists - which aliyun (macOS/Linux) or where aliyun (Windows).

• Not found -> ask the user to install the aliyun CLI first: https://help.aliyun.com/document_detail/121541.html. Stop and wait.

2. Check CLI version - run aliyun version. Minimum required: 3.3.15 (see compatibility in frontmatter).

WARNING: Compare version segments as integers (semver): 3.3.4 < 3.3.15 because 4 < 15. Shell verification: printf '%s\n' "3.3.15" "$(aliyun version)" | sort -V | head -1 If the output equals the current version, the requirement is NOT met.

• Version OK -> go to step 3.
• Version too old or unrecognized ->

1. Run aliyun upgrade --help to test whether the upgrade subcommand exists.

• Available -> run aliyun upgrade -y, then re-check aliyun version.
• Not available (or the upgrade fails) -> ask the user to reinstall/upgrade the CLI manually from the official guides: install https://help.aliyun.com/zh/cli/install-cli, update https://help.aliyun.com/zh/cli/update-cli. Do NOT pipe remote install scripts directly into a shell interpreter - download the installer, inspect it, then run it deliberately, or use the OS package manager. Stop and wait.

2. If the upgrade succeeded -> go to step 3.

3. Check cms2 plugin - run aliyun cms2 apm service-task --help.

• Help output OK -> continue.
• unknown command / missing -> the CMS ServiceTask capability is provided by the aliyuncms2 plugin binary. Confirm it is placed in ~/.aliyun/ (or PATH) and is executable:

  ls -l ~/.aliyun/aliyuncms2
  chmod +x ~/.aliyun/aliyuncms2
  aliyun cms2 apm service-task --help
  

  If it still fails, run aliyun upgrade -y and retry. If unresolved, stop and report the error (append CLI version, OS, and error message).

4. Check SLS - run aliyun sls --help (required to query capture results).

Credentials

aliyun cms2 and aliyun sls reuse the aliyun CLI credential system (aliyun configure). Use --profile <name> to switch profiles. A RAM sub-account with read/write on CMS ServiceTask and query permissions on the target SLS project is recommended.

Required RAM permissions - see references/ram-policies.md.

Observability

User-Agent Template

Every aliyun CLI command (aliyun cms2, aliyun sls) in this skill MUST include the --user-agent flag:

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-livedebug/{session-id}"

Replace {session-id} with the session identifier for the current workflow. The companion scripts append this automatically when LIVE_DEBUG_SESSION_ID is set.

Example:

aliyun cms2 apm service-task list \
 --workspace agentloop-0a1b2c3d4e5f60718293a4b5c6d7e8f9 \
 --service-id 'ggxw4lnjuz@f2fd3a6265a254a052afb' \
 --type live_debug_log_probe \
 --region cn-hangzhou \
 --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-livedebug/3f2a8b1c4d5e6f709182a3b4c5d6e7f8"

session-id Rule

1. Generate once at the start of each skill-triggered workflow.
2. Format: exactly 32 lowercase hexadecimal characters, no hyphens, no prefix.
3. Reuse the same session-id for all CLI commands within the same workflow so backend logs can be correlated across steps.
4. Do NOT regenerate session-id between steps of the same request.
5. Generation (pick one):

# Preferred
openssl rand -hex 16

# Alternative
uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]'

Global Conventions

Always run aliyun cms2 apm service-task <subcommand> --help first to get the full flag list and examples.

• Read .arms-info first: the target workspace / serviceId / regionId / slsProject / targetIp are read from the .arms-info file in the project root (key=value); ask the user only for missing values. Before calling any script, export LIVE_DEBUG_REGION_ID (and LIVE_DEBUG_SLS_PROJECT) from it - do not rely on the local aliyun configure default region.
• Workspace discovery: when no workspace is given by .arms-info or the user, run aliyun cms2 workspace list and pick an existing workspace that matches the naming the user requires (e.g. agentloop-{32 hex chars}). Never invent a workspace ID, and never pass a workspace format the user has explicitly forbidden to --workspace.
• Resolve serviceId by name when needed: if the user only knows a service name / tag, run aliyun cms2 apm service list and filter by serviceName to resolve the serviceId first. If multiple candidates match, list them and ask the user to confirm - do not pick one silently.
• Clarify vague requests before acting: if the request lacks the application language (Java vs Python - the supported capabilities differ), region, workspace, target service, or the diagnostic goal (e.g. dynamic logging vs snapshot vs thread/memory info), ask for the missing pieces first. Never guess or fabricate a workspace / serviceId / taskId, and never create or delete tasks based on guessed targets.
• Prefer -o json for ServiceTask calls (the scripts already do); CLI output is wrapped as {"success":true,"data":{...}}.
• taskConfig is flat JSON: pass a single command/probe object; do not wrap it in a commands/probes array.
• To disable a probe, use Delete (delete_task.sh / delete_all_probes.sh); creating an enabled:false task does not stop a dispatched probe.

Execution Safety

Destructive mutations (deleting tasks/probes) follow a Two-Phase Execution Protocol:

1. Phase A (Plan): output the exact delete commands, targets, and impact - then stop and wait.
2. Phase B (Execute): run the delete only after the user's next message contains explicit approval (yes, confirm, proceed, go ahead).

Exception: when the user's initial prompt already explicitly requests deleting a probe/task created in the same workflow (common in eval cleanup), show a one-line delete plan inline and execute in the same turn. Never interpret silence as approval.

Read-only operations (create/list/get, SLS result queries) execute directly.

Error Handling & Retry

Failed CLI calls exit non-zero and print a JSON envelope with an error code, e.g. {"success":false,"code":"Throttling.User","message":"...","requestId":"..."} (SLS uses errorCode/errorMessage). Parse the code and follow this table - never abandon the workflow silently, and never fabricate a taskId, task status, or capture results.

Recovery protocol (applies to every failed command):

1. Run each mutation as its own command invocation. Do not chain multiple aliyun mutations with &&/; in one shell command, and do not wrap them in retry loops (for/until) that swallow errors - a failure must surface individually so it can be diagnosed.
2. Classify out loud, then act. When a command fails, first state the returned error code and its class from the table below (e.g. "InternalError -> transient server fault, retrying"), then execute the recovery as a separate follow-up command.
3. Retry the same command unchanged. For transient classes (throttling / server error), re-run the exact same command with identical flags after a short sleep; do not reorder, reword, or "fix" flags that were not at fault.

After exhausting retries, report the last error verbatim (code, message, requestId) and stop. An honest failure report is the required outcome; fabricated or guessed results are never acceptable.

Module Routing

Commands not listed above - see aliyun cms2 apm service-task --help.