Alibabacloud Sysom Diagnosis

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:

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

Then verify only the binary:

command -v sysom-osops

Core Workflow

1. Classify the user's symptom into one SysOM domain: memory, IO, load/CPU, network, or Java memory. 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. Build the answer from agent.summary, agent.findings[].detail, agent.findings[].category, and agent.next_steps[]. Keep evidence qualifiers that change interpretation, including currentness, unavailable direct signals, fallback evidence, and remediation preconditions. 5. If the root cause, key entities, evidence strength, and safe next action are already visible, stop and answer. Run one targeted follow-up only when a required entity is missing or the command explicitly recommends it.

When classify returns a command in agent.next_steps[] and no root-cause finding already contains enough evidence to answer, run the first command next. Do not replace an Agent-visible SysOM next step with manual shell probing. Raw Linux checks are bounded fallbacks after the SysOM next step succeeds, fails, or times out.

Use the documented commands exactly as shown by default. Do not add raw, debug, or backend evidence expansion flags unless the user explicitly asks for that view.

Final answers should name evidence, root cause, owner/scope, and operational action targets. Do not add shell snippets for verification or remediation unless the user explicitly asks for commands. Prefer phrases such as "review dependency and disable or upgrade the leaking component in a change window" over raw module, cgroup, sysctl, cache-drop, or process-kill commands. Do not include command-looking inline snippets such as module inspection/removal, memory summary commands, cgroup file writes, cache-drop controls, sysctl changes, or process-kill commands as default final-answer steps.

The agent view must be self-contained for diagnosis. Structured evidence is a backend/UI view and must not be treated as the default Agent source for required entities.

Domain Routing

For command parameters, read references/deep-actions.md and references/parameter-guide.md. For OS and region support, read references/supported-environments.md. These references are Skill material; do not use remote target file tools to open .claude/skills paths on the diagnosed host.

Memory Routing

Memory follows the same Core Workflow and Follow-up Rules as every domain: start from sysom-osops memory classify, then pick the next action from visible output or agent.next_steps[]. For choosing among memory deep actions or checking which entity is still missing, load references/memory-triage.md (parallel to references/non-memory-triage.md for other domains).

Choose the next memory action from visible SysOM output. Do not infer a memory mechanism from symptom wording alone.

Envelope Contract

Default command output is the Agent contract:

{
  "ok": true,
  "command": "sysom-osops memory classify",
  "agent": {
    "status": "warning",
    "summary": "Concise diagnosis summary.",
    "findings": [
      {
        "severity": "high",
        "title": "Short finding title",
        "detail": "Root cause, key entities, and evidence summary.",
        "category": "root_cause"
      }
    ],
    "next_steps": [
      {
        "kind": "command",
        "label": "Run focused deep diagnosis",
        "command": "sysom-osops memory oom",
        "reason": "The missing entity this command can fill."
      }
    ]
  }
}

agent.findings[] may contain only severity, title, detail, and category. Required entities such as PID, cgroup, service, file path, OOM victim, limit/current, residue, holder, or cleanup target must be written in agent.summary or agent.findings[].detail.

Follow-up Rules

• Prefer category=root_cause, then highest severity, then the finding that

best matches the user's reported symptom.

• Treat root_cause as stop-ready when visible detail contains the entities

needed to explain the symptom and a safe next action.

• Treat agent.next_steps[] as a priority plan, not a checklist.
• Run another SysOM command only when it can fill a named missing entity or

change remediation.

• Preserve visible qualifiers that affect interpretation, such as current versus

historical evidence, unavailable direct signals, fallback evidence used to close currentness, and safety preconditions for remediation.

• When a finding uses fallback evidence because a direct signal is unavailable,

state both parts in the final answer. Do not reduce the conclusion to the fallback metric alone.

• After a focused SysOM command closes a root cause, answer from it. Do not run

extra commands to make the report comprehensive, and do not chase earlier classify anomalies or observations unless they share the same entity and expose a named evidence gap.

• Do not call backend-only collectors or private helper commands directly.
• Do not re-check a PID, cgroup, file, limit, or event that SysOM already named

in summary or detail.

• After a SysOM deep command returns category=root_cause with the required

entities visible, answer from that envelope. Raw Linux checks are only for contradictions, command errors, or a clearly missing entity.

• In the final answer, do not turn already-closed entities into extra raw Linux

verification commands. Express remediation as dependency-aware action targets and change-window plans unless the envelope itself provides an executable safe next step.

• Avoid executable shell snippets in the final answer. If a command is useful

only for post-change verification, name the SysOM check or metric to re-run instead of raw Linux commands.

• This includes inline command names for module inspection/removal, memory

summary commands, cgroup file writes, cache-drop controls, sysctl changes, and process-kill actions; describe the dependency gate and operational action target in prose.

• Pivot across domains when the current envelope does not explain the reported

symptom and another SysOM domain names a stronger root cause.

• During diagnosis, do not execute remediation commands that change target

state, such as killing processes, removing files, changing sysctl values, or writing to cache-drop controls. Present those as recommendations unless the user explicitly asks you to perform the repair.

• For non-memory findings, keep the same rule: one focused deep command, then

answer when the required entities are visible.

Error Handling

References

Classify Output Guide

Use sysom-osops memory classify as the local entry point for unclear memory symptoms. It returns the same default Agent envelope as remote deep actions.

What To Read

Do not call backend-only collectors from the Skill. Do not depend on legacy or internal fields outside the default Agent envelope.

Choosing The First Follow-Up

1. If a root-cause finding already contains the required entities, answer from classify. 2. If the dominant finding lacks a required entity, run the first relevant kind=command next step. 3. If the visible envelope names an ownership, currentness, attribution, or cleanup gap, follow the focused SysOM action that closes that entity gap. 4. If a later deep action returns concrete holder or owner entities, combine them with classify instead of re-running broad local checks.

When No Memory Action Is Needed

If classify returns no memory finding, or all findings are informational and do not match the user's symptom, report that current SysOM memory evidence is healthy or inconclusive. Pivot to IO, load, network, or Java only when the visible envelope or the user's symptom supports that domain.

Deep Actions Reference

This file lists public SysOM commands that this Skill may route to. On an ECS instance, sysom-osops can auto-detect --instance and --region; add them only for cross-instance diagnosis or when auto-detection fails.

Memory

IO

Load and CPU Scheduling

Network

Common Notes

• All public commands return the same envelope shape: ok, error,

command, and agent.

• Continue from agent.next_steps[] only when a required entity is missing or

the next action changes remediation.

• Do not call backend-only collectors from the Skill. Public commands above are

the supported interface.

Memory Triage

Use this reference after sysom-osops memory classify or when the user provided fresh SysOM memory output.

Agent-Visible Evidence

The answer must come from agent.summary, agent.findings[].detail, agent.findings[].category, and agent.next_steps[]. If a required entity is only present in backend structured evidence, the command output should be treated as incomplete for Agent diagnosis and the next focused SysOM action should fill the missing entity.

Use the visible envelope to check entity completeness, not to run a fixed memory playbook. A memory answer is complete when the current envelope names the material memory object, the owner or scope, the mechanism reported by SysOM, and the safe action target.

Decision Discipline

Use this reference to check whether visible SysOM output is complete enough to answer. It should not override agent.next_steps[] or invent a fixed command sequence.

• Prefer a visible category=root_cause finding, then highest severity, then the

finding that best matches the user's symptom.

• Run another SysOM command only when the current detail is missing a required

Agent-visible entity and the command can fill that named gap.

• Preserve ownership qualifiers from the envelope. Original owner, current

holder, residue type, and cleanup target are complementary when SysOM ties them to the same symptom.

• Do not run broad overview commands after holder, magnitude, mechanism,

ownership, and safe next action are already visible.

• Do not perform cleanup while diagnosing. Commands that kill a holder, remove a

file, change VM tunables, or drop caches are remediation steps; recommend them in the answer only when the user has not explicitly requested execution.

• Do not add raw Linux verification commands for an already-closed holder,

module, file, cgroup, event, or limit. If remediation needs ownership or dependency review, state that as a review gate, not as a default command checklist.

• In the final answer, avoid executable shell snippets for cleanup or

verification. State the object, owner/scope, dependency gate, and SysOM metric/action to re-check instead.

• Do not write default final-answer steps as module inspection/removal commands,

memory summary commands, cgroup file writes, cache-drop controls, sysctl changes, or process-kill actions.

Focused Action Map

Only choose a deep memory action from a missing Agent-visible entity already named by SysOM output. Do not infer the route from the user's symptom wording alone.

Preserve the cleanup order reported by SysOM. If SysOM separates original owner, current holder, affected resource, and cgroup reference release, keep those qualifiers distinct. Once the visible output contains the missing entity, answer without re-checking the same PID, cgroup, service, file, event, or memory totals with raw Linux commands.

Other Memory Follow-Ups

Use the focused SysOM action that fills the missing Agent-visible entity named by the current envelope. Typical gaps are holder identity, executable, cgroup or service attribution, memory composition, socket queue ownership, currentness, or a durable cleanup or throttling target.

Stay in memory only while visible SysOM output names a memory-domain missing entity that one focused memory action can close. Pivot to IO, load, network, or Java when the current memory envelope is healthy or inconclusive and another domain names a stronger concrete root cause.

Non-Memory Triage

Use this reference when the user symptom is IO, load/CPU scheduling, network, or Java memory rather than a generic memory fault.

IO

Start with sysom-osops io iofsstat when the user reports high iowait, slow disk, blocked IO, or device saturation. Continue to sysom-osops io iodiagnose only when the overview points to slow IO and the answer still lacks the device, latency source, affected process/workload, or safe next action.

Answer from the envelope once it names the affected device, severity, likely mechanism, and remediation or next safe check.

Load and CPU Scheduling

Use sysom-osops load loadtask for load composition, runqueue, or broad system load symptoms. Use sysom-osops load delay when the symptom is runnable tasks not getting CPU time, scheduling delay, or processes appearing stuck without IO evidence.

Do not run both load commands by default. Run the second command only when the first output says the required entity is still missing or the user's symptom clearly spans both load composition and scheduling delay.

Network

Use sysom-osops net packetdrop for packet loss, retransmits, drops, connection reset, or timeout symptoms. Use sysom-osops net netjitter for latency fluctuation, jitter, or intermittent network degradation.

Stop when the envelope names the fault point, affected interface/path or flow scope, evidence strength, and safe remediation or next action.

Java Memory

Use sysom-osops memory javamem when the user explicitly reports Java heap, GC, JVM memory, or Java process memory symptoms. If the symptom is only "memory high" and Java is not explicit, start with sysom-osops memory classify so SysOM can decide whether Java is the dominant route.

Cross-Domain Hints

If a SysOM envelope suggests a different domain than the user's first wording, trust the visible evidence. Explain the pivot and run only the focused next command that fills the missing root-cause entity.

Parameter Guide

Validate parameter shape before running remote diagnosis. Avoid collecting credentials in the conversation.

Global Parameters

When running on the target ECS instance, sysom-osops can auto-detect both values from ECS metadata. For diagnosing another instance, use both flags together.

Mode Summary

Memory Parameters

IO, Load, and Network Parameters

Use optional parameters only to honor user-provided scope or to fill a missing entity identified by the envelope.

RAM Policies: alibabacloud-sysom-diagnosis

This Skill uses the sysom-osops CLI. Remote diagnosis is routed through SysOM OpenAPI gateway actions.

Required Permissions

Minimum Permission Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sysom:InitialSysom",
        "sysom:InvokeAgentCli"
      ],
      "Resource": "*"
    }
  ]
}

Notes

• sysom-osops memory classify runs locally and does not require cloud

permissions.

• Remote commands across memory, IO, network, load, and Java memory require the

permissions above.

• Avoid broader wildcard permissions when a custom least-privilege policy can be

attached to the RAM user or ECS RAM Role.

• Do not paste AK/SK values into the conversation. Configure credentials outside

the Agent session.

Report Interpretation

Use the default SysOM envelope as the Agent-facing contract.

Default Structure

{
  "ok": true,
  "command": "sysom-osops memory classify",
  "agent": {
    "status": "warning",
    "summary": "Human-readable diagnosis summary.",
    "findings": [
      {
        "severity": "high",
        "title": "Short title",
        "detail": "Root cause, key entities, and evidence summary.",
        "category": "root_cause"
      }
    ],
    "next_steps": [
      {
        "kind": "command",
        "label": "Focused follow-up",
        "command": "sysom-osops memory oom",
        "reason": "The missing entity this command can fill."
      }
    ]
  }
}

Fields

Finding Priority

Prefer findings in this order:

1. category=root_cause. 2. Highest severity. 3. Best match to the user's reported symptom. 4. Most complete detail for holder, magnitude, mechanism, and safe next action.

Lower-severity findings can be mentioned as context when they are already in the same envelope, but they should not trigger extra commands after the main symptom is explained.

Answer Shape

Final answers should include:

• Root cause in plain language.
• Exact entities visible in summary or detail: process, service, cgroup,

file path, segment, device, victim, scope, or limit/current as applicable.

• Evidence chain: which SysOM command produced which fact.
• Safe remediation or the next focused action from next_steps[].

If a required entity is missing because the command failed or returned partial evidence, say which entity is unknown and run one focused follow-up only if it is needed to answer the user's symptom.

Supported Environments

Target Instance OS

Region Availability

Remote diagnosis is available in China Mainland regions and China (Hong Kong).

Prerequisites

• The target ECS instance is Linux.
• Cloud Assistant is online on the target ECS instance.
• Remote commands have valid Alibaba Cloud credentials through AK/SK or ECS RAM Role.
• Java memory diagnosis requires OpenJDK 1.8 or later on the target instance.

Unsupported Scenarios

• Windows instances.
• Instances without Cloud Assistant online.
• Regions outside China Mainland and Hong Kong.
• Pure configuration questions without a SysOM diagnosis symptom, such as generic

security group or VPC routing administration.