huawei-cloud-lts-log-inspector

华为云 LTS 日志流量与采集检查工具

概览

此 Skill 为华为云 LTS（Log Tank Service）提供一套全面的工具，用于日志流量分析、采集健康状况检查和批量日志导出管理。 它面向以下四种主要场景：

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 消费者组处于邀请制 Beta 阶段；仅提供 Java/Go SDK，没有 REST API 或 CLI
消费者组游标更新（F11）	不可用	同上
离线下载任务（F9/F10/F12）	替代方案	LTS 控制台的离线下载仅对受邀用户开放，且没有公开 API。使用 OBS 转储（CreateTransfer）作为替代方案。

约束

• 创建 OBS 转储任务前，必须输出流量与存储成本风险警告。
• 禁止批量导出所有日志 - 始终指定日志组和日志流范围。
• 此 Skill 不会修改日志组/日志流 TTL、索引配置或告警规则。
• 此 Skill 不会创建或删除日志组或日志流。
• 上下文日志查询返回精简片段（默认前后各 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. 区域：目标区域必须提供 LTS 服务（例如，cn-north-4）。
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	是	Top N，范围为 1-100
--start_time	是	开始时间戳（ms），最大范围为 30 天
--end_time	是	结束时间戳（ms）
--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	是	起始时间戳（毫秒），范围最长为 30 天
--end_time	是	结束时间戳（毫秒）
--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	否	上次查询返回的分页 scroll ID

注意：如需获取 line_num，请先调用 ListLogs 搜索目标日志， 然后在 ListLogContext 中使用返回的 line_num 值。

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 - Agent 正常运行，正在采集日志
• offline - 主机离线，采集已中断
• error / plugin error - Agent 出错，采集可能已中断
• uninstall - 未安装 Agent
• 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}	是	华为云区域	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
操作名称	PascalCase	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 命令快速参考