alibabacloud-alinux-sysom-inspection

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 (--scope-type all) auto-discovers all ECS instances in the region (limit 5000). Both automatically diagnose the Top-3 most severe anomalous instances and include copy-ready deep-dive commands for the remaining ones in the report.
• Report lookup uses ROA API GET /api/v1/inspection/getInspectionReport; the CLI polls until the report succeeds or times out.
• --region <region> --scope-type <scope-type> --report-id <reportId> (or with --instance instead of --scope-type) skips task creation and directly fetches the existing report; inspection results emit this replay command in next_steps automatically, including the original --region and --scope-type/--instance.
• Local threshold/event-rule configuration is not used; anomaly decisions come from the server-side inspection report.

Error Handling

When a CLI invocation fails, classify the failure by the error text (Error: <Code>: ...) and handle it as follows instead of blind retries:

• Permission (Forbidden.RAM): explain that sysom:InitialSysom / sysom:InvokeAgentCli is missing and point the user to references/ram-policies.md for the minimum policy; do not retry.
• Parameter (InvalidParameter, invalid argument): identify the offending argument and guide the user to verify the instance id and region; do not attribute it to the service.
• Throttling (Throttling): tell the user the request was rate-limited and advise retrying later; do not retry automatically in a loop.
• Internal (InternalError): report the temporary service failure honestly and suggest retrying later; do not attribute it to user input.
• Empty region (no ECS instances found): not an error. Report that the region has no ECS instances and skip the inspection; never fabricate a report.

Extensibility Notes

• Inspection focus is controlled by --query (keyword/intent mapping to concrete items); unmatched queries fall back to a full inspection.
• Use --scope-type batch --instances ... for batch inspection and --scope-type all for the whole region (limit 5000 instances); both auto-diagnose the Top-3 most severe anomalies.
• Use --region <region> --scope-type <scope-type> --report-id <reportId> (or with --instance instead of --scope-type) to re-check an existing report without re-execution; the replay command is emitted automatically in inspection next_steps with the original --region and --scope-type/--instance.
• A local Python CLI (./scripts/osops.sh inspection) is kept only as a fallback for environments where sysom-osops is unavailable.
• Memory anomaly trigger logic of the fallback path stays implemented in scripts/sysom_cli/inspection/command.py.
• To add more post-inspection specialized diagnosis actions, reuse the InvokeDiagnosis integration pattern.