alibabacloud-sysom-diagnosis

alibabacloud-sysom-diagnosis

SysOM CLI とバックエンドのエンベロープを、診断の信頼できる情報源として使用します。このスキルは従来の SysOM 診断スキルに代わるもので、SysOM ECS のパフォーマンスと安定性を診断するための唯一のエントリーポイントです。

即時ルート

ユーザーが症状を報告しており、最新の SysOM エンベロープ出力を提示していない場合は、その場しのぎの Linux 調査や手動での確認を行う前に、以下のドメイン別ルーティングから該当する SysOM コマンドを実行してください。その後、返された agent.summary、agent.findings[].detail/category、agent.next_steps[] に従ってください。生の Linux コマンドは、SysOM コマンドを利用できない場合、出力同士が矛盾する場合、または対象を絞った SysOM コマンドの実行後も必要な対象が不明なままの場合に限り、代替手段として使用します。

認証情報のセキュリティ

AccessKey ID または AccessKey Secret の値を表示、エコー、または要求してはいけません。リモートコマンドは独自に認証を確認します。コマンドで認証エラーまたは権限エラーが返された場合は、そのエラーを説明し、ユーザーに references/ram-policies.md を案内してください。認証情報の設定は会話の外で行う必要があります。

CLI のセットアップ

CLI が利用可能か確認します。

command -v sysom-osops

インストールされていない場合は、インストールしてください。インストーラーはLinux または macOSで実行できます。Windows では実行できません。診断対象の ECS は Linux である必要があります（references/supported-environments.md を参照）が、操作元ホストの OS は問いません。

システム全体へのインストール（通常は sudo を使用して /usr/local/bin への書き込み権限が必要です）：

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

ユーザー領域へのインストール（sudo 不要、root 所有のパスは使用しません）。Linux と macOS の両方で動作し、管理者権限がない場合に推奨される方法です。

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"

次に、インストール先のディレクトリが PATH に含まれていることを確認します（例：~/.bashrc／~/.zshrc）。

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

続いて、バイナリのみを確認します。

command -v sysom-osops

macOS では、インストーラーがアドホック署名を行い、隔離属性を自動的に削除します。Apple Silicon 上で Rosetta を使って x86_64 シェルを実行している場合、インストーラーが不一致を検出します。バイナリが変換実行されることを把握している場合に限り、-f を指定して上書きしてください。

コマンドの表示は認証情報に依存します

memory classify などのローカルコマンドのみ、常に表示されます。リモートの詳細コマンドはすべて、認証情報を必要とする SysOM スキルカタログから実行時に検出されます。認証情報が設定されていないマシンでは、次のようになります。

• sysom-osops memory --help には classify のみが表示され、詳細なメモリーコマンドは表示されません。
• トップレベルの sysom-osops --help には io、net、load の各グループが表示されません。

これは表示上の制限であり、機能上の制限ではありません。このスキルで利用できるコマンドの正式な一覧として references/deep-actions.md を参照し、--help の出力から、ドメインやコマンドがサポートされていないと判断してはいけません。認証ステータスの報告には sysom-osops precheck を使用します。

コアワークフロー

1. ユーザーの症状を、SysOM のいずれか 1 つのドメイン（memory、IO、load/CPU、network、Java（GC/memory/CPU））に分類します。
2. そのドメインに合致する最小限の SysOM コマンドを実行します。症状が不明確なメモリの問題では、ローカルの memory classify を優先します。その他のドメインでは、対応するドキュメント記載のリモートアクションを使用します。
3. デフォルトのエンベロープフィールド（ok、error、command、agent）のみを読み取ります。
4. 回答を作成する前に、ドメインのリファレンスを読み込みます。 この手順は必須であり、agent.findings と agent.next_steps が完全に見える場合でも省略してはいけません。読み込むリファレンスはドメインによって異なります。
   • Java（種類を問わず、gc/memory/cpu）→ まず references/java/README.md を読み、症状の振り分けとパラメーターの検証を確認します。その後、種類に応じて次を読み込みます。
     • gc：references/java/gc/gc-guide.md
     • memory：references/java/memory/memory-guide.md（続けて、references/java/memory/ 内の用語集、エンベロープガイド、プロファイリングプレイブック、判断ツリーを読みます）
     • cpu：references/java/cpu/cpu-guide.md
   • その他のドメイン→以下の References テーブルから、該当するリファレンスを読み込みます。 リファレンスには、解釈ルール、エンティティの定義、回答の組み立て方に関するガイダンスが記載されており、これらはエンベロープだけでは把握できません。エンベロープの生テキストから Java 用語、ネイティブメモリの分類、プロファイリングの意味を推測してはいけません。
5. ステップ 4 で読み込んだリファレンスに基づいて解釈し、進捗として hop の内容をユーザーに伝えます。agent.summary と重要な所見を提示します。解釈に影響する証拠の条件（情報の最新性、直接的なシグナルが取得できないこと、代替証拠、修正の前提条件など）は維持してください。
6. agent.status に基づいて分岐します。
   • concluded（または欠落・認識できない場合）→ agent.summary、agent.findings[].detail/category、agent.next_steps[] から最終回答を作成し、ループを終了します。
   • in_progress → バックエンドが次の収集 hop を要求しています。agent.next_steps[] の kind=command エントリを取得し、以下の確認ルールを適用して実行し、新しいエンベロープをステップ 4 に渡します。

ガイド付き診断ループの厳守事項（Java の複数 hop セッション）：

• 進行の主導権：agent.next_steps[] を無視して独自に収集内容を決めてはいけません。また、エンベロープにない診断コマンドを実行してはいけません。
• コマンドは表示どおりに正確に実行します。ゲートウェイがすでに --session-id を注入しています。フラグを書き換えたり、追加・削除したりしてはいけません。コマンドが失敗した場合は、パラメーターを変更して再試行せず、エラーエンベロープをそのまま伝えます。
• hop の上限：同じセッションで 4 hop を実行したら、バックエンドがまだ in_progress と示していてもループを終了します。これまでの結論を提示し、証拠の限界を明記します（バックエンドも同じ上限で強制的に結論を出すため、二重の安全策となります）。
• ユーザーが拒否した場合：ユーザーが提案されたコマンドを拒否したら、ループを終了し、すでに収集した証拠に基づいて要約します。その hop を実行しなかったために未確認のままとなる結論を明示します。

プロファイリングまたは長時間実行される追加コマンドを実行する前（例：java analyze --type memory --duration N、対象プロセスにエージェントを注入するコマンド、または複数分の実行が見込まれるコマンド）：

• コマンドの処理内容、所要時間、対象プロセスへのパフォーマンス上の影響（例：サンプリングによる CPU オーバーヘッド、注入したエージェントによる追加メモリ、セーフポイント停止の可能性）をユーザーに伝えます。
• 続行してよいかユーザーに確認します。ユーザーの確認を得るか、追加実行を自動で行うよう事前に継続的な指示を受けている場合を除き、コマンドを実行してはいけません。
• コマンドの実行開始後、予想待ち時間をユーザーに伝え、処理中の場合は進捗を随時知らせます。

読み取り専用のクエリコマンド（例：java analyze --type cpu）には、ここに記載した要件は適用されません。詳細は各ドメインガイドの Execution Model を参照してください。 agent.next_steps[] にコマンドが返され、根本原因の所見に回答に十分な証拠がすでに含まれていない場合は、次に最初のコマンドを実行してください。 Agent に表示される SysOM の次のステップを、手動のシェル調査に置き換えないでください。Linux の生の確認は、SysOM の次のステップが成功、失敗、またはタイムアウトした後に行う、範囲を限定した代替手段です。

デフォルトでは、ドキュメントに記載されたコマンドをそのまま使用してください。ユーザーが明示的にその情報を求めない限り、生の証拠、デバッグ用、またはバックエンドの証拠を拡張するフラグを追加しないでください。

最終回答では、証拠、根本原因、担当者／範囲、運用上の対応対象を明示してください。ユーザーが明示的にコマンドを求めない限り、検証や修復のためのシェルコマンドを追加しないでください。「変更作業の時間枠内に、依存関係を確認し、漏えいを起こしているコンポーネントを無効化またはアップグレードしてください」のような表現を優先し、生のモジュール、cgroup、sysctl、キャッシュ解放、プロセス終了のコマンドは避けてください。 モジュールの調査や削除、メモリ概要の確認、cgroup ファイルへの書き込み、キャッシュ解放の制御、sysctl の変更、プロセス終了などのコマンドに見えるインラインスニペットを、デフォルトの最終回答の手順に含めないでください。

agent ビューは診断に必要な情報をすべて含んでいる必要があります。構造化された証拠はバックエンド／UI 向けのビューであり、必要なエンティティを確認するためのデフォルトの Agent 情報源として扱わないでください。

ドメインのルーティング

ユーザーの症状	最初のルート
原因が明確でないメモリの問題、OOM、高い RSS、ファイルキャッシュ、shmem/tmpfs、メモリ cgroup、ソケットメモリ、カーネルメモリ	sysom-osops memory classify
Java の問題（症状が不明確）	references/java/README.md の症状トリアージルールに従います。ユーザーに症状を尋ね、一致するタイプにルーティングしてください
Java の GC 一時停止／頻繁な GC／低い GC スループット	sysom-osops java analyze --type gc
Java ヒープ／OOM／ヒープリーク／ネイティブリーク	sysom-osops java analyze --type memory — pid/pod が指定されていない場合は候補リストが返されます。ユーザーが選択するまで停止し、再試行しないでください
Java の CPU ホットスポット／高いスレッド CPU 使用率／フレームグラフ	sysom-osops java analyze --type cpu --pid <PID>
ディスクの遅延、高い iowait、ディスクレイテンシ、ブロックされた IO	sysom-osops io iofsstat。概要から遅い IO が示された場合は、続けて io iodiagnose を実行します
高い負荷、runqueue の滞留、CPU 待ちで停止したタスク	表面化している症状に応じて、sysom-osops load loadtask または load delay
パケット損失、再送、ネットワークタイムアウト、ジッター	損失／ドロップの症状には sysom-osops net packetdrop、レイテンシの変動には net netjitter

コマンドのパラメーターについては、references/deep-actions.md と references/parameter-guide.md を参照してください。OS とリージョンのサポート状況については、references/supported-environments.md を参照してください。これらのリファレンスは Skill の資料です。診断対象ホスト上の .claude/skills パスを開くために、リモートターゲットのファイルツールを使用しないでください。 Java の症状からタイプへのルーティングについては、references/java/README.md を参照してください。

メモリのルーティング

メモリも、すべてのドメインと同じコアワークフローおよびフォローアップルールに従います。まず sysom-osops memory classify を実行し、表示された出力または agent.next_steps[] から次のアクションを選択してください。メモリの詳細アクションを選ぶ場合や、どのエンティティが不足しているかを確認する場合は、他のドメイン向けの references/non-memory-triage.md に相当する references/memory-triage.md を読み込んでください。

注：Java 関連のメモリ症状（Java プロセスでの OOM、ヒープリーク、ネイティブリーク）は、memory classify ではなく、sysom-osops java analyze --type memory を使って Java ドメインにルーティングしてください。上記の「ドメインのルーティング」表を参照してください。

表示された SysOM の出力から、次のメモリアクションを選択してください。症状の表現だけからメモリの仕組みを推測しないでください。

エンベロープ契約

デフォルトのコマンド出力は Agent 契約です。

{
  "ok": true,
  "command": "sysom-osops memory classify",
  "agent": {
    "status": "concluded",
    "session_id": "a1b2c3d4e5f6",
    "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[] に含められるのは、severity、title、detail、category のみです。PID、cgroup、サービス、ファイルパス、OOM の被害対象、上限／現在値、残存物、保持者、クリーンアップ対象などの必須エンティティは、agent.summary または agent.findings[].detail に記載する必要があります。

ガイド付き診断セッションにおけるフィールドの意味：

• agent.status：in_progress は、バックエンドの診断エージェントが追加の収集ステップを要求していることを意味します。concluded は診断が収束したことを意味します。値がない場合、または認識できない値の場合は、concluded として扱います。従来のコレクター階層の状態（success、warning など）が Java 以外のアクションに表示される場合は、これまでどおり解釈します。
• agent.session_id：バックエンドが生成するマルチホップセッション識別子です。生成や変更はしないでください。ゲートウェイがすでに command 文字列に挿入しているため、そのまま実行してください。
• agent.next_steps[].kind：command = バックエンドが要求した収集コマンド（上記の確認ルールに従います）。info = ユーザー側への提案。提示はしますが、自動実行はしないでください。warning = 証拠またはデータ品質に関する注意事項。

フォローアップのルール

• category=root_cause を優先し、次に重大度が最も高い所見、さらにユーザーが報告した症状に最も合致する所見を優先してください。
• 表示されている detail に症状の説明に必要なエンティティと安全な次のアクションが含まれている場合、root_cause は回答可能と判断してください。
• agent.next_steps[] は優先順位付きの計画として扱い、チェックリストとして扱わないでください。
• 名前が特定された不足エンティティを補完できる場合、または修復方針を変更できる場合に限り、別の SysOM コマンドを実行してください。
• 実行時間の長い Java 収集コマンド — java analyze --type memory --duration N（プロファイリング。旧形式は memory javamem --duration N）および collect モードでの java analyze --type gc（5～10 分の JFR／GC 収集）— は、 実行に数分かかります。ユーザーにその旨を伝え、ツールのタイムアウトを適切に設定してください。また、クライアントのタイムアウト後に同じコマンドを再実行してはいけません。詳細は references/java/memory/profiling-playbook.md（memory）および references/java/gc/gc-guide.md（gc）を参照してください。
• 解釈に影響する、現在の証拠と過去の証拠の区別、直接シグナルが利用できないこと、現在性の確認を完了するために使用した代替証拠、修復の安全性に関する前提条件など、表示されている限定情報は保持してください。
• 直接シグナルが利用できないために所見で代替証拠を使用している場合は、最終回答で両方の点を述べてください。結論を代替メトリックだけに絞らないでください。
• 集中的な SysOM コマンドで根本原因が特定できたら、その結果に基づいて回答してください。報告を網羅的にするために追加コマンドを実行したり、同じエンティティに関連し、名前の特定された証拠の不足を示している場合を除き、以前の分類の異常や観察結果を追跡したりしないでください。
• バックエンド専用のコレクターや非公開のヘルパーコマンドを直接呼び出さないでください。
• SysOM が summary または detail ですでに示した PID、cgroup、ファイル、制限、イベントを再確認しないでください。
• SysOM の詳細コマンドが category=root_cause を返し、必要なエンティティが表示されている場合は、その結果に基づいて回答してください。生の Linux チェックは、矛盾やコマンドエラーがある場合、または明らかにエンティティが不足している場合に限ります。
• 最終回答では、特定済みのエンティティをさらに生の Linux コマンドで検証しないでください。結果の内容自体に実行可能で安全な次のアクションが示されている場合を除き、修復は依存関係を考慮した作業対象と変更ウィンドウの計画として説明してください。
• 最終回答で実行可能なシェルコマンドのスニペットは避けてください。変更後の検証にしか役立たないコマンドについては、生の Linux コマンドではなく、再実行する SysOM のチェック項目またはメトリックを示してください。
• これには、モジュールの調査や削除、メモリーのサマリー、cgroup ファイルへの書き込み、キャッシュ破棄の制御、sysctl の変更、プロセスの強制終了に関するインラインのコマンド名も含まれます。依存関係の確認条件と運用上の作業対象を文章で説明してください。
• 現在の結果で報告された症状を説明できず、別の SysOM ドメインがより確かな根本原因を示している場合は、そのドメインに切り替えて調査してください。
• 診断中は、プロセスの終了、ファイルの削除、sysctl 値の変更、キャッシュ破棄の制御への書き込みなど、対象の状態を変更する修復コマンドを実行しないでください。ユーザーから修復の実施を明示的に依頼された場合を除き、推奨事項として提示してください。
• メモリー以外の所見でも同じルールを適用してください。集中的な詳細コマンドを1つ実行し、必要なエンティティが表示されたら回答してください。

エラーハンドリング

error.code	対応
Sysom.TargetRequired	インスタンス ID とリージョンを尋ねるか、ECS メタデータの自動検出に必要な条件を説明します
Sysom.FallbackClassify	ローカルの分類結果を提示し、次に実施できる具体的な手順がある場合にのみ続行します
Sysom.PermissionDenied	references/ram-policies.md を使って、必要な RAM 権限を説明します
Sysom.AuthenticationFailure	このセッション外で認証情報を設定するようユーザーに依頼します
Sysom.InvalidParameter	インスタンス、リージョン、またはコマンドパラメーターを修正するようユーザーに依頼します
Sysom.DiagnosisVersionNotSupported	対象インスタンスの診断コンポーネントを更新する必要があることを説明します
Sysom.DiagnosisJsonParseFailed	ユーザーが引き続き同じ証拠を必要としている場合に限り、1 回だけ再試行します
Sysom.PollError	不足している証拠が引き続き必要な場合、同じ具体的な操作を 1 回だけ再試行します

空の出力はエンベロープではありません

コマンドは、stdout と stderr のどちらにも何も出力せずにゼロ以外の終了コードで終了することがあります。これはエンベロープではないため、解析しないでください。空の出力を JSON として解析すると失敗します。主な原因は未対応のフラグです。エンベロープが生成される前に CLI が未定義のフラグを拒否し、現在はそのメッセージを出力しないためです。

コマンドが何も出力しない場合：

1. 同じコマンドを変更せずに再試行したり、診断結果を報告したりしないでください。
2. 指定したフラグを references/parameter-guide.md と照合し、sysom-osops <group> <command> --help で確認してください。io、load、net の各コマンドが受け付けるのは --region、--instance、--scope のみです。
3. 未対応のフラグを削除して、1 回だけ再実行してください。
4. 引き続き出力が空の場合は、診断可能なエラーなしでコマンドが失敗したことをユーザーに伝え、使用したコマンドとフラグを明記してください。結果を推測せず、Sysom.InvalidParameter と同じように扱ってください。

ヘルプテキストはエンベロープではありません

ドメインのサブコマンドは、壊れているのではなく存在しない場合があります。リモートの詳細診断コマンドは、認証情報が必要な SysOM スキルカタログから実行時に検出されます。認証情報がない場合、カタログにアクセスできず、サブコマンドは登録されません。そのため CLI はドメイングループのヘルプテキストを出力し、終了コードは 0 になります。

出力が Commands under "<domain>" are discovered at runtime で始まる場合は、診断結果ではなく、コマンドが存在しない状態として扱ってください。

1. エンベロープとして解析したり、「問題は見つかりませんでした」と報告したりしないでください。この場合の終了コード 0 は、コマンドが実行されなかったことを意味します。
2. そのドメインが未対応、またはこの Skill で利用できるのが memory classify だけだと結論づけないでください。
3. 詳細診断には認証情報が必要であることをユーザーに伝えてください。認証状態の確認には sysom-osops precheck を、設定には sysom-osops configure を案内してください。認証情報の設定は会話の外で行います。
4. ユーザーが認証情報を設定したことを確認してから、コマンドを再実行してください。

参考資料

参考資料	使用する場面
references/classify-output-guide.md	ローカルのメモリ分類出力を読む場合
references/memory-triage.md	メモリの詳細診断操作を選ぶ場合、またはメモリエンティティの完全性を確認する場合
references/non-memory-triage.md	IO、負荷／CPU、ネットワークの診断先を決める場合
references/deep-actions.md	ドメイン別の SysOM コマンドを調べる場合
references/parameter-guide.md	コマンドパラメーターを検証する場合
references/report-interpretation.md	エンベロープのフィールドと回答形式を解釈する場合
references/ram-policies.md	RAM 権限を説明する場合
references/supported-environments.md	OS、アーキテクチャ、リージョンの対応状況を確認する場合

Java 分析リファレンス

リファレンス	使用する場面
references/java/README.md	Java の主要なエントリーポイント：症状のトリアージ、パラメーターガイド、サブドメインのインデックス
references/java/gc/gc-guide.md	--type gc の結果を実行または解釈する場合
references/java/cpu/cpu-guide.md	--type cpu の結果を実行または解釈する場合
references/java/memory/memory-guide.md	--type memory の解釈と、探索を優先するフローのエントリーポイント
references/java/memory/glossary.md	Java メモリ用語
references/java/memory/javamem-envelope-guide.md	--type memory のエンベロープ構造の解釈
references/java/memory/profiling-playbook.md	--duration による収集前の準備と想定される動作
references/java/memory/decision-tree.md	Java のマルチホップセッションでバックエンドの next_steps に従う場合
references/java/memory/case-library.md	ケースライブラリとアンチパターン