/alibabacloud-sysom-diagnosis

name: alibabacloud-sysom-diagnosis
description: >
  Use when troubleshooting Linux server performance or stability issues —
  CPU saturation, high load, scheduling delay, memory pressure, OOM events,
  high RSS, page cache / shared memory growth, memory cgroup residue, Java
  heap issues, disk IO saturation or latency, packet loss, network jitter,
  or a server that is slow, stuck, or unstable. Performs diagnosis and
  surfaces recommendations; does not apply fixes automatically.
license: Apache-2.0
compatibility: >
  Requires sysom-osops CLI. The control host running the CLI can be Linux or
  macOS (x86_64 or aarch64); Windows is not supported. Remote diagnosis targets
  a Linux ECS instance and requires Alibaba Cloud credentials through AK/SK or
  an ECS RAM Role, an online Cloud Assistant on the target ECS, and a supported
  China Mainland or Hong Kong region.
metadata:
  domain: aiops
  product: sysom
  supported_domains:
    - cpu
    - io
    - memory
    - network
    - java
  owner: sysom-team
  contact: sysom-team@alibaba-inc.com
allowed-tools: Bash Read

alibabacloud-sysom-diagnosis

Use SysOM CLI and backend envelopes as the diagnosis source of truth. This Skill replaces the older SysOM diagnosis Skill and is the single entry point for SysOM ECS performance and stability diagnosis.

Immediate Route

When the user reports a symptom and has not provided fresh SysOM envelope output, run the matching SysOM command from **Domain Routing** below before ad hoc Linux inspection or manual probing. Then follow the returned `agent.summary`, `agent.findings[].detail/category`, and `agent.next_steps[]`. Raw Linux commands are bounded fallbacks only when a SysOM command is unavailable, outputs contradict each other, or a required entity remains missing after the focused SysOM command.

Credential Security

Never print, echo, or ask for AccessKey ID or AccessKey Secret values. Remote commands perform their own authentication checks. If a command returns an authentication or permission error, explain the error and point the user to `references/ram-policies.md`; credential setup must happen outside the conversation.

CLI Setup

Check whether the CLI is available:

command -v sysom-osops

If it is missing, install it. The installer runs on **Linux or macOS** — it does not run on Windows. The target ECS being diagnosed must be Linux (see `references/supported-environments.md`), but the control host can be either OS.

System-wide install (needs write access to `/usr/local/bin`, typically via `sudo`):

curl -fsSL --connect-timeout 1000 https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/skill_cli/install.sh \
  | sudo bash

User-local install — no sudo, no root-owned paths. Works on both Linux and macOS, and is the recommended path when you do not have administrator privileges:

mkdir -p ~/.local/bin
curl -fsSL --connect-timeout 1000 https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/skill_cli/install.sh \
  | bash -s -- -d "$HOME/.local/bin"

Then make sure the install directory is on your PATH (e.g. `~/.bashrc` / `~/.zshrc`):

export PATH="$HOME/.local/bin:$PATH"

Then verify only the binary:

command -v sysom-osops

On macOS, the installer performs ad-hoc codesign and strips quarantine attributes automatically. If you are on Apple Silicon running an x86_64 shell under Rosetta, the installer detects the mismatch; pass `-f` to override only when you know the binary will run under translation.

Command Visibility Depends On Credentials

Only local commands such as `memory classify` are always present. Every remote deep command is discovered at runtime from the SysOM skills catalog, which needs credentials. On a machine without credentials configured, expect:

• `sysom-osops memory --help` to list only `classify`, with the deep memory

commands absent.

• The top-level `sysom-osops --help` to omit the `io`, `net`, and `load` groups

entirely.

This is a visibility limitation, not a capability limitation. Treat `references/deep-actions.md` as the authoritative command inventory for this Skill, and never infer from `--help` output that a domain or command is unsupported. Use `sysom-osops precheck` to report auth status.

Core Workflow

1. Classify the user's symptom into one SysOM domain: memory, IO, load/CPU, network, or Java (GC/memory/CPU). 2. Run the smallest SysOM command that matches that domain. Prefer a local memory classify for unclear memory symptoms; for other domains, use the matching documented remote action. 3. Read only the default envelope fields: `ok`, `error`, `command`, and `agent`. 4. **Load domain references before building the answer.** This step is mandatory and must not be skipped even when `agent.findings` and `agent.next_steps` appear complete. Which references to load depends on the domain:

• Java (any type: gc/memory/cpu) → read `references/java/README.md` first

for symptom routing and parameter validation; then by type:

• gc: `references/java/gc/gc-guide.md`
• memory: `references/java/memory/memory-guide.md` (then glossary, envelope

guide, profiling playbook, decision tree under `references/java/memory/`)

• cpu: `references/java/cpu/cpu-guide.md`
• Other domains → load the matching reference from the References table below.

References add interpretation rules, entity definitions, and answer-shaping guidance that the envelope alone does not convey. Do not infer Java terms, native memory categories, or profiling semantics from raw envelope text. 5. Relay the hop as visible progress: present `agent.summary` (plus key findings) to the user, interpreted through the reference material loaded in step 4. Keep evidence qualifiers that change interpretation, including currentness, unavailable direct signals, fallback evidence, and remediation preconditions. 6. Branch on `agent.status`:

• `