/alibabacloud-alinux-sysom-inspection

name: alibabacloud-alinux-sysom-inspection
version: 0.2.0
description: >
  Inspect ECS instance health, detect anomalies in memory, disk, CPU, load,
  and resource leaks, and automatically trigger deep diagnosis when critical
  memory issues are detected. Suitable for routine inspections, troubleshooting,
  and risk warning scenarios. Trigger keywords: SysOM, inspection, instance
  diagnosis, memory_usage_rate, memory usage.
layer: application
category: os-ops
lifecycle: operations
tags:
  - sysom
  - inspection
  - ecs
  - memory
  - diagnosis
status: beta

SysOM Inspection (`sysom-inspection`)

Inspections are launched with the `sysom-osops` CLI command (`sysom-osops inspection ecs ...`). Always go through the CLI instead of calling the inspection OpenAPI directly.

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

If the CLI is installed but has no `inspection` subcommand yet, run `sysom-osops update` first, then retry.

If a command fails due to missing RAM permissions, follow `references/ram-policies.md` to attach the minimum permission policy.

Quick Start

# Focused inspection by intent (--query)
# Run only CPU/load related items (keyword mapping)
sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "cpu related inspection"

# Combined intent: memory and disk
sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "memory and disk"

# Natural-language sentence: intent is extracted automatically, matching packet-loss items
sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "check whether this machine has network packet loss"

# If the query matches no items, it falls back to a full inspection automatically

# Batch inspection (--scope-type batch, auto diagnosis supported)
# Inspect all specified instances -> auto root-cause diagnosis on the Top-3 most severe
# anomalous instances -> LLM summary (the rest get copy-ready deep-dive commands in the report)
sysom-osops inspection ecs --region cn-shenzhen --scope-type batch --instances i-aaa,i-bbb,i-ccc

# Region-wide inspection (--scope-type all, auto diagnosis supported)
# Auto-discover every ECS instance in the region (limit 5000) -> Top-3 anomalies auto-diagnosed
# -> LLM summary; one command for the full closed loop
sysom-osops inspection ecs --region cn-shenzhen --scope-type all

# Re-check an existing report (--report-id)
# Returns immediately without re-running (auto-generated in inspection next_steps).
# IMPORTANT: --region and --scope-type (or --instance) MUST match the original
# inspection command, otherwise the replay will fail with MissingParam errors.
sysom-osops inspection ecs --region cn-shenzhen --scope-type all --report-id inspection-82a64d9d-11c5-45b2-a81c-27fc754891e8

Invocation Modes

• **Focused inspection:** `--query "<intent>"` maps keywords or extracted intent to concrete

items (CPU/load keyword mapping, combined intents such as memory + disk, natural-language sentences such as network packet-loss checks). A query matching no items falls back to a full inspection automatically.

• **Batch:** `--scope-type batch --instances i-aaa,i-bbb,...` inspects all specified instances,

auto-diagnoses the Top-3 most severe anomalous ones, and lists copy-ready deep-dive commands for the rest in the report.

• **Region-wide:** `--scope-type all` auto-discovers every ECS instance in the region

(limit 5000), then applies the same Top-3 auto-diagnosis and LLM summarization in one command.

• **Report replay:** `--region <region> --scope-type <scope-type> --report-id <reportId>`

(or `--region <region> --instance <instanceId> --report-id <reportId>`) returns the existing report immediately without re-running the inspection; inspection results emit this replay command — with the original `--region` and `--scope-type`/`--instance` — in `next_steps` automatically.

Observability

• **UA template (required for all SDK requests):**
• `AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}`
• Runtime resolved form in this skill: `AlibabaCloud-Agent-Skills/alibabacloud-alinux-sysom-inspection/<SKILL_SESSION_ID>`
• **Unified session-id rule:**
• A single session-id is generated once per session (one CLI execution) and must be

reused consistently across all API calls, both CLI and SDK requests.

• Generation priority: external env `SKILL_SESSION_ID` (preferred) -> auto-generated

fallback `sid-<32-char hex>` (uuid4 hex); invalid injected values fall back to the generated id.

• Accepted format: `[A-Za-z0-9][A-Za-z0-9._:-]{7,127}`.
• The resolved value is exported to process env `SKILL_SESSION_ID` so downstream calls

stay consistent.

• The `sysom-osops` CLI injects the UA header automatically and follows the same unified

session-id rule.

Execution Flow

• Before each inspection, the CLI verifies SysOM activation and permissions (`InitialSysom`,

`source=skill_hub`); activation and installation prompts are handled by the CLI itself.

• Every new inspection calls ROA API `POST /api/v1/inspection/createInstanceInspection` with

`source=skill_hub`; selected items come from `--query` keyword/intent mapping, and a query matching no items falls back to a full inspection.

• Each mode runs a full closed loop: inspect (metrics + logs) -> automatic root-cause diagnosis

on detected anomalies -> LLM-summarized Chinese report.

• Automatic root-cause diagnosis is triggered via `InvokeDiagnosis` (injecting

`__sysom_diagnosis_source=skill_hub` into `params`) and polled via `GetDiagnosisResult` until `success` / `fail` / timeout.

• Batch (`--scope-type batch --instances ...`) inspects every specified instance; region-wide

(