huawei-cloud-agentarts-obs-diagnosis

Huawei Cloud AgentArts 无数据可观测性诊断

概述

本技能可系统地诊断 Huawei Cloud AgentArts agent-ops 平台中缺失的指标、日志和追踪/会话。 诊断流程分为三个阶段：检查订阅元数据 → 排查数据管道 → 验证查询参数，涵盖三个数据源：APM（追踪/指标）、AOM（指标）和 LTS（日志）。

架构

Application (OTel SDK/Collector)
  │
  ├── Traces:  OTEL SDK → APM (OTLP) → deliverConfig → Kafka → agent-ops
  ├── Metrics: Application → AOM (Prometheus) → agent-ops
  └── Logs:    Application → LTS → agent-ops (requires logGroup/logStream metadata)

数据类型和元数据

数据类型	来源	所需元数据
追踪/会话	APM	apmBusiness、apmToken
指标	AOM	promInstance、aomAccessCode
日志	LTS	logGroup、logStream

前提条件

1. Huawei Cloud 凭证

export HUAWEI_ACCESS_KEY="<your-access-key-id>"
read -rs HUAWEI_SECRET_KEY; export HUAWEI_SECRET_KEY
export HUAWEI_REGION="cn-north-4"

2. hcloud CLI（KooCLI）

安装：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html

3. IAM 权限

最小权限策略请参阅 references/iam-policies.md。

工作流

步骤 1：确定缺失的数据类型

使用 AskUserQuestion 确定缺失的数据类型：

选项	数据类型	数据源
A	指标（metrics）	AOM / APM
B	日志（logs）	LTS
C	追踪/会话（traces/session）	APM
D	全部缺失	所有来源

记录症状：完全缺失还是部分缺失、错误代码、开始时间。

步骤 2：确认环境上下文

参数	默认值	说明
region	cn-north-4	查询区域（必须与数据摄取区域一致）
domain_id	—	IAM 域 ID
project_id	—	LTS 查询的项目 ID
start_time / end_time	—	毫秒时间戳（13 位，不能使用 10 位秒级时间戳）

步骤 3：检查订阅元数据（阶段 1 — 始终优先检查）

缺少订阅元数据是无数据问题的最常见根因。

检查 APM 业务和令牌：

hcloud APM ListBusiness --cli-region=cn-north-4

如果不存在业务 → 尚未订阅 APM。创建业务：

hcloud APM CreateBusiness --cli-region=cn-north-4 \
  --name="obs-diagnosis-check" \
  --display_name="obs-diagnosis-check" \
  --descp="diagnosis" \
  --cmdb_datasource_type=OTEL

验证业务令牌：

hcloud APM ShowToken --cli-region=cn-north-4 \
  --x-business-id={business_id}

检查 AOM Prometheus 实例和访问码：

hcloud AOM ListPromInstance --cli-region=cn-north-4 --Enterprise-Project-Id=0
hcloud AOM ListAccessCode --cli-region=cn-north-4

如果没有 PromInstance → 尚未配置 AOM。创建 Prometheus 实例 （--prom_type 必须是 ECS/CCE/REMOTE_WRITE/CLOUD_SERVICE/ACROSS_ACCOUNT 之一； 必须提供 --region 标头，且其值必须与 --cli-region 一致）：

hcloud AOM CreatePromInstance --cli-region=cn-north-4 \
  --prom_name="obs-diagnosis" \
  --prom_type=REMOTE_WRITE \
  --region=cn-north-4

检查 LTS 日志组和日志流：

hcloud LTS ListLogGroups --cli-region=cn-north-4
hcloud LTS ListLogStreams --cli-region=cn-north-4 --log_group_id={group_id}

如果没有 logGroup/logStream → 尚未为 agent-ops 订阅 LTS。

步骤 4：按数据类型诊断（阶段 2 — 检查管道）

4A. 指标无数据诊断

从下往上检查管道：

1. 应用侧：是否已配置 OTEL 指标 SDK / Prometheus exporter？
2. AOM 侧：

   hcloud AOM ListPromInstance --cli-region=cn-north-4 --Enterprise-Project-Id=0
   hcloud AOM ListAccessCode --cli-region=cn-north-4
   hcloud AOM ListMetadataAomPromGet --cli-region=cn-north-4
   

   • Prometheus 实例是否有效？
   • 访问码是否有效？
   • 端点是否可访问？
3. 查询侧：使用 Prometheus 查询验证数据是否存在：

   hcloud AOM ListInstantQueryAomPromGet --cli-region=cn-north-4 \
     --query="up" \
     --prom_instance_id={prom_id}
   

4. agent-ops 过滤器：检查 metric_name 是否匹配（resource_tokens、model_tokens、 session_tokens、trace_tokens），以及过滤标签是否匹配（gen_ai_resource_type、 resource_id、model_id）。

4B. 日志无数据诊断

1. 应用侧：是否已配置 ICAgent / OTEL 日志 exporter？
2. LTS 侧：

   hcloud LTS ListLogGroups --cli-region=cn-north-4
   hcloud LTS ListLogStreams --cli-region=cn-north-4 --log_group_id={group_id}
   hcloud LTS ListLogs --cli-region=cn-north-4 \
     --log_group_id={group_id} \
     --log_stream_id={stream_id} \
     --start_time=1720000000000 \
     --end_time=1720600000000
   

3. 查询参数：检查 agentRunId、agentId、traceId、logType 和 关键词语法（LTS 查询语言）。
4. 错误代码：
   • LTS.2446 → 不支持的查询语法 — 修正关键词语法
   • 403 → 权限被拒绝 — 检查委托令牌（ops_admin_trust）

4C. 追踪/会话无数据诊断

1. 应用侧：

   hcloud APM SearchAgent --cli-region=cn-north-4 --x-business-id={business_id}
   

   OTEL SDK 是否配置了正确的端点和令牌？
2. APM deliverConfig：
   • deliverConfig 中的 deliver_otel_trace=true 是否已设置？
   • Kafka 是否可访问（bootstrap-servers、SASL_SSL、topic 是否存在）？
3. APM 数据验证：

   hcloud APM SearchTransaction --cli-region=cn-north-4 \
     --x-business-id={business_id} \
     --start_time=1720000000000 \
     --end_time=1720600000000
   

4. agent-ops 查询侧（仅限 API — KooCLI 中不支持）：

   curl -X POST ${AGENT_OPS_ENDPOINT}/v1/ops/observation/traces \
     -H "Authorization: Bearer ${IAM_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"start_time": 1720000000000, "end_time": 1720600000000}'
   

步骤 5：常见检查（所有数据类型）

1. 时间戳格式：必须为 13 位毫秒时间戳（10 位秒级时间戳 → 无数据）
2. 区域一致性：采集区域必须与查询区域一致
3. 身份验证：IAM token / AppCode 是否有效？401 → 已过期，403 → 权限不足。${IAM_TOKEN} 需在运行期通过 IAM token / AppCode 获取后替换（见上文步骤 4 中的 agent-ops 查询命令）；未替换时它仍是占位符，照抄请求必定返回 401。
4. 权限检查：

   hcloud IAM ListPoliciesV5 --cli-region=cn-north-4
   

步骤 6：生成诊断报告

报告格式请参见 references/diagnostic-report-template.md。

核心命令

命令	用途	模式
hcloud APM ListBusiness --cli-region=cn-north-4	列出 APM 业务	CLI
hcloud APM ShowBusinessDetail --cli-region=cn-north-4	显示业务详情	CLI
hcloud APM ShowToken --cli-region=cn-north-4	获取业务令牌	CLI
hcloud APM ShowAccessPoint --cli-region=cn-north-4	获取接入点	CLI
hcloud APM SearchAgent --cli-region=cn-north-4	搜索 Agent	CLI
hcloud APM SearchTransaction --cli-region=cn-north-4	搜索事务（跟踪）	CLI
hcloud APM ShowSpanSearch --cli-region=cn-north-4	搜索 Span	CLI
hcloud APM ListOpenRegion --cli-region=cn-north-4	列出开放区域	CLI
hcloud AOM ListPromInstance --cli-region=cn-north-4 --Enterprise-Project-Id=0	列出 Prometheus 实例	CLI
hcloud AOM ListAccessCode --cli-region=cn-north-4	列出接入码	CLI
hcloud AOM ListInstantQueryAomPromGet --cli-region=cn-north-4	即时 Prometheus 查询	CLI
hcloud AOM ListRangeQueryAomPromGet --cli-region=cn-north-4	区间 Prometheus 查询	CLI
hcloud AOM ListMetadataAomPromGet --cli-region=cn-north-4	列出 Prometheus 元数据	CLI
hcloud LTS ListLogGroups --cli-region=cn-north-4	列出日志组	CLI
hcloud LTS ListLogStreams --cli-region=cn-north-4	列出日志流	CLI
hcloud LTS ListLogs --cli-region=cn-north-4	列出日志	CLI
hcloud IAM ListPoliciesV5 --cli-region=cn-north-4	列出 IAM 策略	CLI
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/traces	在 agent-ops 中查询跟踪	API
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/metrics/trend	查询指标趋势	API

参数确认

参数	必需	描述	示例
region	是	查询区域	cn-north-4
business_id	是（跟踪）	APM 业务 ID	来自 ListBusiness
prom_instance_id	是（指标）	AOM Prometheus 实例 ID	来自 ListPromInstance
log_group_id	是（日志）	LTS 日志组 ID	来自 ListLogGroups
log_stream_id	是（日志）	LTS 日志流 ID	来自 ListLogStreams
start_time	是	开始时间（毫秒时间戳）	1720000000000
end_time	是	结束时间（毫秒时间戳）	1720600000000
metric_name	否（指标）	要查询的指标名称	resource_tokens
keywords	否（日志）	LTS 关键词搜索	error AND timeout
trace_id	否（跟踪）	跟踪 ID 筛选条件	—

KooCLI 命令格式规范

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

特性	描述	示例
服务名称	KooCLI 服务名称（大写）	APM、AOM、LTS、IAM
操作名称	PascalCase	ListBusiness、ShowToken
区域参数	--cli-region=<value>	--cli-region=cn-north-4
简单参数	--key=value	--business_id=xxx

参考文档

• references/iam-policies.md — 最小权限 IAM 策略
• references/cli-installation-guide.md — hcloud CLI 安装指南
• references/verification-method.md — 验证方法和 API 状态
• references/dataflow-diagram.md — Mermaid 数据流和诊断流程
• references/acceptance-criteria.md — 诊断验收标准
• references/diagnostic-report-template.md — 诊断报告模板

边缘情况

场景	处理方法
缺少所有数据类型	先检查订阅状态，再检查网络连接
部分数据缺失（部分应用）	检查 Agent 部署情况和 service.name 映射
LTS.2446 错误	修正关键词语法（转义、引号、运算符）
403 错误（非 claw）	检查 IAM 租户权限和订阅状态
403 错误（claw）	检查委托（ops_admin_trust）和 STS 配置
RESOURCE_NOT_EXIST	缺少资源记录 — 确认 CreateClawTenantRelation
缺少元数据	先订阅（SubscribeOpsObservation）
时间戳为 10 位	转换为 13 位毫秒时间戳
区域不匹配	摄取和查询使用相同区域

说明

• 优先级顺序：订阅元数据 → 数据管道 → 查询参数 → 权限
• 最常见的根本原因：缺少订阅元数据（apmBusiness、promInstance、logGroup）
• 时间戳陷阱：使用了 10 位秒级时间戳，而不是 13 位毫秒级时间戳
• 凭证安全：切勿硬编码 AK/SK。请从环境变量或 CLI 配置文件中读取。
• 最小权限原则：所需权限请参见 references/iam-policies.md。