huawei-cloud-lts-log-inspector

Huawei Cloud LTS ログトラフィックおよび収集状況インスペクター

概要

このスキルは、Huawei Cloud LTS（Log Tank Service）のログトラフィック分析、収集状態の検査、一括ログエクスポート管理のための包括的なツールキットを提供します。 次の4つの主なシナリオを想定しています。

1. ログトラフィックの異常調査 - ログトラフィックが急増した場合、TOP-N 統計を使用して、どのログストリームで大量のログが発生しているかを特定します。
2. 障害の詳細な特定 - 異常なログ ID を指定すると、その前後のコンテキストログのスタックを自動的に取得し、障害発生時の状況を再構成します。
3. 収集障害の巡回点検 - ホストグループの収集レポート状況を確認し、収集が途絶えた箇所を特定します。
4. 一括ログエクスポート - OBS 転送タスクを作成し、大量の過去ログを OBS バケットにエクスポートしてダウンロードします。

アーキテクチャ

User Trigger -> Skill Workflow -> hcloud CLI LTS Commands -> Structured Output
                                    |-- Traffic Stats (Histogram / TOP-N / Timeline)
                                    |-- Log Context Query
                                    |-- Collection Inspection (HostGroup / Host / AccessConfig)
                                    |-- OBS Transfer (Create / List / Delete)
                                    +-- Diagnostic Report (Aggregated)

重要な制限事項

機能	状態	説明
コンシューマーグループのクエリ（F8）	利用不可	LTS コンシューマーグループは招待制のベータ版です。Java/Go SDK のみ対応しており、REST API または CLI はありません
コンシューマーグループのカーソル更新（F11）	利用不可	上記と同じです
オフラインダウンロードタスク（F9/F10/F12）	代替手段	LTS コンソールのオフラインダウンロードはホワイトリスト登録者のみ利用でき、パブリック API はありません。代替手段として OBS 転送（CreateTransfer）を使用します。

制約事項

• OBS 転送タスクを作成する場合は、実行前にトラフィックとストレージのコストに関するリスク警告を必ず出力してください。
• すべてのログの一括エクスポートは禁止されています。必ずロググループとログストリームの範囲を指定してください。
• このスキルは、ロググループ／ログストリームの TTL、インデックス設定、アラームルールを変更しません。
• このスキルは、ロググループまたはログストリームを作成も削除もしません。
• コンテキストログのクエリでは、テキスト出力が過大になるのを防ぐため、簡潔な断片（前後の既定値は100行、最大500行）を返します。

前提条件

1. hcloud CLI がインストールされ、有効な AK/SK プロファイルで認証されていること。
   • インストールガイド：references/cli-installation-guide.md を参照してください
   • 確認方法：hcloud configure list に有効なプロファイルが表示されること
2. IAM 権限：クエリ操作には LTS の読み取り権限、OBS 転送の作成／削除には LTS の転送書き込み権限が必要です。references/iam-policies.md を参照してください。
3. リージョン：対象リージョン（例：cn-north-4）で LTS が利用可能であること。
4. OBS バケット（転送のみ）：OBS 転送タスクを作成するには、既存の OBS バケットが必要です。

ワークフロー

シナリオ 1：ログトラフィックの異常調査

1. ListTopnTrafficStatistics -> Identify TOP-N log streams by write traffic (descending)
2. ListTimeLineTrafficStatistics -> Check traffic trend over the time window
3. ListLogHistogram -> Drill down into the suspect log stream histogram
4. Output: Structured traffic anomaly report

シナリオ 2：障害の詳細な特定

1. ListLogs -> Search for the target log by keyword/time range to get line_num
2. ListLogContext -> Pull context logs (before/after) using line_num
3. Output: Concise context log fragments (max 500 lines each direction)

シナリオ 3：収集障害の巡回点検

1. ListHostGroup -> List all host groups
2. ListHost --filter.host_status=offline -> Find offline hosts
3. ListHost --filter.host_status=error -> Find error-state hosts
4. ListAccessConfig -> Check collection configs for affected hosts
5. Output: Collection anomaly checklist

シナリオ 4：一括ログエクスポート（OBS 転送を使用）

1. [Cost risk warning displayed to user]
2. User confirms
3. CreateTransfer -> Create OBS transfer task (log group + stream -> OBS bucket)
4. ListTransfers -> Monitor transfer status
5. User downloads logs from OBS bucket
6. (Optional) DeleteTransfer -> Clean up transfer after download

主なコマンド

1. ログトラフィック統計

1.1 ログヒストグラムのクエリ

hcloud LTS ListLogHistogram --cli-region={region} \
  --group_id={log_group_id} \
  --stream_id={log_stream_id} \
  --start_time={start_time} \
  --end_time={end_time} \
  --key_word={keyword} \
  --step_interval={step_interval}

パラメーター	必須	説明
--group_id	はい	ロググループ ID
--stream_id	はい	ログストリーム ID
--start_time	はい	開始時刻
--end_time	はい	終了時刻
--key_word	はい	検索キーワード
--step_interval	はい	ステップ間隔（整数）

1.2 TOP-N トラフィック統計のクエリ

hcloud LTS ListTopnTrafficStatistics --cli-region={region} \
  --resource_type=log_stream \
  --topn=10 \
  --start_time={start_timestamp_ms} \
  --end_time={end_timestamp_ms} \
  --search_list.1=write \
  --sort_by=write \
  --is_desc=true \
  --filter.log_group_id={log_group_id}

パラメーター	必須	説明
--resource_type	はい	log_group、log_stream、または tenant
--topn	はい	上位 N 件。範囲は1～100
--start_time	はい	開始タイムスタンプ（ミリ秒）。最大範囲は30日
--end_time	はい	終了タイムスタンプ（ミリ秒）
--search_list.1	はい	データ種別：index／write／storage／basicTransfer／seniorTransfer／coldStorage
--sort_by	はい	並べ替えフィールド。search_list に含まれている必要があります
--is_desc	はい	降順：true／false
--filter.{key}	はい	フィルター条件（マップ）。例：--filter.log_group_id=xxx

1.3 タイムラインのトラフィック統計をクエリする

hcloud LTS ListTimeLineTrafficStatistics --cli-region={region} \
  --resource_type=log_stream \
  --search_type=write \
  --start_time={start_timestamp_ms} \
  --end_time={end_timestamp_ms} \
  --period=1 \
  --timezone=Asia/Shanghai \
  --resource_id={resource_id}

パラメーター	必須	説明
--resource_type	はい	log_group、log_stream、または tenant
--search_type	はい	write／index／storage／basicTransfer／seniorTransfer
--start_time	はい	開始タイムスタンプ（ms）、範囲は最大30日
--end_time	はい	終了タイムスタンプ（ms）
--period	はい	時間間隔（時間）、範囲は1～24
--timezone	はい	タイムゾーン文字列
--resource_id	いいえ	絞り込み対象の特定のリソース ID

2. ログコンテキストのクエリ

2.1 ログの内容をクエリする

hcloud LTS ListLogs --cli-region={region} \
  --log_group_id={log_group_id} \
  --log_stream_id={log_stream_id} \
  --start_time={start_time_ms} \
  --end_time={end_time_ms} \
  --keywords={keyword} \
  --limit=100 \
  --is_desc=true

2.2 ログコンテキストをクエリする（前後）

hcloud LTS ListLogContext --cli-region={region} \
  --log_group_id={log_group_id} \
  --log_stream_id={log_stream_id} \
  --line_num={line_num} \
  --backwards_size=100 \
  --forwards_size=100

パラメーター	必須	説明
--log_group_id	はい	ロググループ ID
--log_stream_id	はい	ログストリーム ID
--line_num	いいえ	ログ行のシーケンス番号（ナノ秒タイムスタンプ）。ListLogs の結果から取得します
--backwards_size	いいえ	前の行数（上のコンテキスト）、範囲は[0、500]、デフォルトは100
--forwards_size	いいえ	後の行数（下のコンテキスト）、範囲は[0、500]、デフォルトは100
--scroll_id	いいえ	前回のクエリで取得したページネーション用スクロール ID

注：line_num を取得するには、まず ListLogs を呼び出して対象のログを検索し、 返された line_num の値を ListLogContext で使用します。

3. 収集状況の確認

3.1 ホストグループを一覧表示する

hcloud LTS ListHostGroup --cli-region={region} \
  --filter.host_group_type=linux

パラメーター	必須	説明
--filter.host_group_type	いいえ	windows または linux
--filter.host_group_name_list.1	いいえ	ホストグループ名で絞り込み
--host_group_id_list.1	いいえ	ホストグループ ID で絞り込み

3.2 ホストを一覧表示する（収集ステータス）

hcloud LTS ListHost --cli-region={region} \
  --filter.host_status=offline

パラメーター	必須	説明
--filter.host_status	いいえ	ホストステータス：uninstall、running、offline、error、plugin error、installing、install-fail、upgrading、upgrade-fail、uninstalling、authentication error
--filter.host_name_list.1	いいえ	ホスト名で絞り込み
--filter.host_ip_list.1	いいえ	ホスト IP で絞り込み
--host_id_list.1	いいえ	ホスト ID で絞り込み

収集ステータスの意味：

• running - エージェントは正常に稼働しており、ログを収集中です
• offline - ホストがオフラインで、収集が停止しています
• error / plugin error - エージェントエラーが発生しており、収集が停止している可能性があります
• uninstall - エージェントがインストールされていません
• authentication error - 認証に失敗しており、収集が停止しています

3.3 アクセス設定を一覧表示する（収集設定）

hcloud LTS ListAccessConfig --cli-region={region} \
  --access_config_name_list.1={config_name}

パラメーター	必須	説明
--access_config_name_list.1	いいえ	アクセス設定名で絞り込み
--host_group_name_list.1	いいえ	ホストグループ名で絞り込み
--log_group_name_list.1	いいえ	ロググループ名で絞り込み
--log_stream_name_list.1	いいえ	ログストリーム名で絞り込み

4. OBS 転送（ログの一括エクスポートの代替手段）

コストリスクに関する警告：OBS 転送タスクを作成すると、OBS のストレージ料金と、 実際のログ転送量に応じた LTS の転送料金が発生します。転送タスクを作成する前に、必ず ユーザーに確認してください。

4.1 OBS 転送を作成する

hcloud LTS CreateTransfer --cli-region={region} \
  --log_group_id={log_group_id} \
  --log_streams.1.log_stream_id={log_stream_id} \
  --log_transfer_info.log_transfer_type=OBS \
  --log_transfer_info.log_transfer_mode=cycle \
  --log_transfer_info.log_transfer_status=ENABLE \
  --log_transfer_info.log_storage_format=RAW \
  --log_transfer_info.log_transfer_detail.obs_bucket_name={obs_bucket} \
  --log_transfer_info.log_transfer_detail.obs_period=5 \
  --log_transfer_info.log_transfer_detail.obs_period_unit=min

パラメーター	必須	説明
--log_group_id	はい	転送元のロググループ ID
--log_streams.1.log_stream_id	はい	転送元のログストリーム ID
--log_transfer_info.log_transfer_type	はい	OBS、DIS、または DMS
--log_transfer_info.log_transfer_mode	はい	cycle（定期）または realTime
--log_transfer_info.log_transfer_status	はい	ENABLE、DISABLE、または EXCEPTION
--log_transfer_info.log_storage_format	はい	RAW または JSON
--log_transfer_info.log_transfer_detail.obs_bucket_name	はい	転送先の OBS バケット名
--log_transfer_info.log_transfer_detail.obs_period	はい	転送間隔：1、2、3、5、6、12、30
--log_transfer_info.log_transfer_detail.obs_period_unit	はい	min または hour

4.2 転送を一覧表示する

hcloud LTS ListTransfers --cli-region={region} \
  --log_transfer_type=OBS

4.3 転送の削除

hcloud LTS DeleteTransfer --cli-region={region} \
  --log_transfer_id={transfer_id}

5. 診断ワークフロー

5.1 トラフィック急増の診断

# Step 1: TOP-N by write traffic (descending)
hcloud LTS ListTopnTrafficStatistics --cli-region={region} \
  --resource_type=log_stream --topn=10 \
  --start_time={start_ms} --end_time={end_ms} \
  --search_list.1=write --sort_by=write --is_desc=true

# Step 2: Timeline trend for the top log stream
hcloud LTS ListTimeLineTrafficStatistics --cli-region={region} \
  --resource_type=log_stream --search_type=write \
  --start_time={start_ms} --end_time={end_ms} \
  --period=1 --timezone=Asia/Shanghai \
  --resource_id={top_stream_id}

5.2 収集停止の診断

# Step 1: Find offline hosts
hcloud LTS ListHost --cli-region={region} --filter.host_status=offline

# Step 2: Find error-state hosts
hcloud LTS ListHost --cli-region={region} --filter.host_status=error

# Step 3: Check access configs
hcloud LTS ListAccessConfig --cli-region={region}

5.3 ログの大量発生を診断

# TOP-N by write traffic descending to find flooding log stream
hcloud LTS ListTopnTrafficStatistics --cli-region={region} \
  --resource_type=log_stream --topn=5 \
  --start_time={start_ms} --end_time={end_ms} \
  --search_list.1=write --sort_by=write --is_desc=true

6. 総合巡回レポート

総合巡回レポートでは、すべての検査結果を集約します。

# 1. TOP-N traffic
hcloud LTS ListTopnTrafficStatistics --cli-region={region} \
  --resource_type=log_stream --topn=10 \
  --start_time={start_ms} --end_time={end_ms} \
  --search_list.1=write --sort_by=write --is_desc=true

# 2. Timeline traffic
hcloud LTS ListTimeLineTrafficStatistics --cli-region={region} \
  --resource_type=tenant --search_type=write \
  --start_time={start_ms} --end_time={end_ms} \
  --period=1 --timezone=Asia/Shanghai

# 3. Host groups
hcloud LTS ListHostGroup --cli-region={region}

# 4. Abnormal hosts
hcloud LTS ListHost --cli-region={region} --filter.host_status=offline
hcloud LTS ListHost --cli-region={region} --filter.host_status=error

# 5. Access configs
hcloud LTS ListAccessConfig --cli-region={region}

次の内容を含む構造化レポートを出力します。

• トラフィック統計の概要（TOP-N とタイムライン）
• 収集異常のチェックリスト（オフライン／エラーホストと影響を受ける設定）

パラメーターの確認

パラメーター	必須	説明	例
{region}	はい	Huawei Cloud のリージョン	cn-north-4
{log_group_id}	はい	LTS ロググループ ID	xxxx-xxxx-xxxx
{log_stream_id}	はい	LTS ログストリーム ID	xxxx-xxxx-xxxx
{start_time} / {end_time}	はい	時間範囲（形式はコマンドによって異なります）	1704067200000（ミリ秒単位のタイムスタンプ）
{topn}	いいえ	TOP-N の件数。範囲は 1～100	10
{line_num}	はい（コンテキスト）	ログ行のシーケンス番号	ListLogs の結果から取得
{obs_bucket}	はい（転送）	転送先の OBS バケット名	my-log-backup
{keyword}	いいえ	ログクエリの検索キーワード	error

KooCLI コマンド形式の標準

hcloud LTS <Operation> --cli-region=<region> [--key=value ...]

機能	説明	例
サービス名	LTS（大文字）	hcloud LTS ListHostGroup
操作名	パスカルケース	ListTopnTrafficStatistics
リージョンパラメーター	--cli-region=<value>	--cli-region=cn-north-4
シンプルなパラメーター	--key=value	--topn=10
インデックス付きパラメーター	--key.1=value1	--search_list.1=write

参考資料

• references/cli-installation-guide.md - hcloud CLI のインストールと設定
• references/iam-policies.md - LTS 用の最小権限 IAM ポリシー
• references/verification-method.md - 検証とテストの方法
• references/dataflow-diagram.md - Mermaid データフロー図
• references/acceptance-criteria.md - 受け入れ基準
• references/lts-api-reference.md - LTS API コマンドのクイックリファレンス