huawei-cloud-agentarts-otel-ingestion

华为云 AgentArts OpenTelemetry 数据接入

概述

此技能可将 OpenTelemetry（OTel）遥测数据接入华为云 AgentArts 可观测性平台（agent-ops）。涵盖四个功能领域：

1. OTel 遥测数据接入 — 通过 APM deliverConfig 转发（路径 A，推荐）或 OTLP 直连（路径 B，仅用于验证），将应用的追踪、指标和日志路由至 agent-ops。
2. AI Agent 观测 — 使用 OpenTelemetry GenAI 语义约定（gen_ai.* spans、token 使用指标、模型调用链）为 AI/LLM 应用添加埋点。
3. 自动配置 — 检测应用语言/框架，并生成可直接使用的 OTel SDK/Collector 配置。
4. 接入诊断 — 通过 agent-ops 观测 API（追踪/会话/指标/日志查询）验证数据是否到达。

架构

Application (OTel SDK/Collector)
  │
  ├── Path A (Recommended): OTLP → APM → deliverConfig → Kafka → agent-ops
  │
  └── Path B (Verification): OTLP → Collector → agent-ops (if OTLP receiver available)

数据流

Mermaid 图见 references/dataflow-diagram.md。

先决条件

1. 华为云凭证

通过带外方式设置凭证。切勿在聊天中粘贴 AK/SK。

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

如果已安装 hcloud CLI，可运行 CLI configure list 命令进行验证。

2. hcloud CLI（KooCLI）

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

3. APM 订阅

确认 agent-ops 已订阅 APM 观测。如果尚未订阅，请先完成订阅（管理面：SubscribeOpsObservation / OpenOpsObservation）。

4. IAM 权限

最小权限策略见 references/iam-policies.md。

5. OTel SDK

安装特定语言的 OTel 包：

• Java：opentelemetry-javaagent（下载 JAR）
• Python：pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
• Node.js：npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
• Go：go get go.opentelemetry.io/otel go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

工作流

步骤 1：确认应用环境

检测应用语言/框架：

语言	检测方法	OTel 埋点工具
Java	pom.xml / build.gradle / .jar 文件	opentelemetry-javaagent
Python	requirements.txt / pyproject.toml	opentelemetry-sdk
Node.js	package.json	@opentelemetry/sdk-node
Go	go.mod	go.opentelemetry.io/otel

如果检测到现有 OTel 配置，请先阅读并调整，而非覆盖。

步骤 2：确认目标环境

参数	默认值	说明
region	cn-southwest-301	agent-ops 部署区域
APM_ENDPOINT	https://apm2.cn-southwest-301.beta.myhuaweicloud.com	APM OTLP 端点
AGENT_OPS_ENDPOINT	https://agentarts.cn-southwest-301.myhuaweicloud.com	AgentArts API 端点
apm.internal.endpoint	内部端点	用于 deliverConfig 转发
wushan.common.appcode	应用代码	用于内部端点认证

步骤 3：确认接入范围

• 数据类型：追踪 / 指标 / 日志
• 应用名称（appName）和业务 ID（businessId）

步骤 4：执行数据接入（路径 A 或 B）

Path A：APM deliverConfig 摄取（推荐）

4a. 创建追踪业务（官方 API — 已通过 IAM 授权参考验证）：

hcloud APM CreateBusiness --cli-region={region} \
  --name="otel-business-<appName>" \
  --display_name="<appName>" \
  --descp="otel business" \
  --cmdb_datasource_type="AGENTRUN"

对应的 API（官方路径）：

POST {APM_ENDPOINT}/v1/apm2/openapi/tracing/business/create
Content-Type: application/json
X-Auth-Token: {iam_token}

{
  "name": "otel-business-<appName>",
  "display_name": "<appName>",
  "descp": "otel business",
  "cmdb_datasource_type": "AGENTRUN"
}

4b. 获取业务令牌（官方 API）：

hcloud APM ShowToken --cli-region={region} \
  --business_id={business_id}

对应的 API：

GET {APM_ENDPOINT}/v1/apm2/openapi/tracing/business/token/{business_id}
X-Auth-Token: {iam_token}
x-business-id: {business_id}

记录返回的令牌，用于应用侧 OTel exporter 身份验证。

4c. 获取接入点（官方 API）：

POST {APM_ENDPOINT}/v1/apm2/openapi/tracing/access/get-access-point/{business_id}
X-Auth-Token: {iam_token}
x-business-id: {business_id}

4d. 创建 deliverConfig 转发（用户提供的 API — 需要手动验证）：

注意：此端点来自用户提供的参考资料，未在官方公开文档中找到。 使用前，请在 Huawei Cloud API Explorer 中验证确切路径。

POST {APM_INTERNAL_ENDPOINT}/v2/trace/deliver-config?region=cn-southwest-301
x-apply-domain-id: {domain_id}
x-apply-role-name: te_admin
Content-Type: application/json

{
  "config_name": "AgentArts-<appName>",
  "deliver_domain": "{domain_id}",
  "deliver_otel_trace": true,
  "descp": "otel trace deliver",
  "business_ids": "{business_id}",
  "application_ids": "{app_id}",
  "otel_trace_topic_name": "{kafka_topic}",
  "kafka_config": {
    "bootstrap.servers": "{bootstrap_servers}",
    "acks": "all",
    "retries": 1,
    "sasl.mechanism": "PLAIN",
    "security.protocol": "SASL_SSL",
    "username": "{kafka_user}",
    "password": "{kafka_password}"
  }
}

修改：PUT /v2/trace/deliver-config（请求体：{id, deliver_otel_trace}） 删除：DELETE /v2/trace/deliver-config/{id}?region=

4e. 配置应用侧 OTel SDK/Collector

Java Agent：

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=<appName> \
  -Dotel.exporter.otlp.endpoint={APM_ENDPOINT} \
  -Dotel.exporter.otlp.headers="Authorization=Bearer {token}" \
  -jar app.jar

Python SDK：

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

exporter = OTLPSpanExporter(
    endpoint=f"{APM_ENDPOINT}/v1/traces",
    headers={"Authorization": f"Bearer {token}"},
)

Node.js SDK：

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const traceExporter = new OTLPTraceExporter({
  url: `${APM_ENDPOINT}/v1/traces`,
  headers: { Authorization: `Bearer ${token}` },
});
const sdk = new NodeSDK({ traceExporter, serviceName: '<appName>' });
sdk.start();

Go SDK：

import (
  "go.opentelemetry.io/otel"
  "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
  "go.opentelemetry.io/otel/sdk/resource"
  sdktrace "go.opentelemetry.io/otel/sdk/trace"
  semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
)

exporter, _ := otlptracehttp.New(ctx,
  otlptracehttp.WithEndpoint(APM_ENDPOINT),
  otlptracehttp.WithHeaders(map[string]string{"Authorization": "Bearer " + token}),
)

OTel Collector（config.yaml）：

exporters:
  otlp/apm:
    endpoint: "{APM_ENDPOINT}:443"
    headers:
      Authorization: "Bearer {token}"
service:
  pipelines:
    traces:
      exporters: [otlp/apm]
    metrics:
      exporters: [otlp/apm]
    logs:
      exporters: [otlp/apm]

Path B：OTLP 直接连接（仅用于验证）

截至当前 agent-ops 版本，后端包含 OTLP proto 定义，但 未实现 OTLP 接收器。Path B 仅用于验证测试。

1. 部署带有 OTLP 接收器和测试 exporter 的 OTel Collector。
2. 从示例应用生成测试 span。
3. 验证数据导出，确认 SDK/Collector 配置正确。
4. 使用管理平面 API 验证数据是否可达。

第 5 步：AI Agent 观测（GenAI 语义约定）

使用 OpenTelemetry GenAI 语义约定对 AI/LLM 应用进行插桩：

Span 名称	描述	关键属性
invoke_agent	Agent 调用	gen_ai.system、gen_ai.request.model
execute_tool	工具执行	gen_ai.tool.name、gen_ai.tool.description
inference	模型推理	gen_ai.usage.input_tokens、gen_ai.usage.output_tokens

Python 示例（LLM 追踪）：

from opentelemetry import trace

tracer = trace.get_tracer("agentarts-ai")

with tracer.start_as_current_span("invoke_agent") as span:
    span.set_attribute("gen_ai.system", "huawei-cloud")
    span.set_attribute("gen_ai.request.model", "pangu-4.0")
    # ... agent logic ...
    span.set_attribute("gen_ai.usage.input_tokens", input_tokens)
    span.set_attribute("gen_ai.usage.output_tokens", output_tokens)

Node.js 示例：

const tracer = trace.getTracer('agentarts-ai');
const span = tracer.startSpan('invoke_agent');
span.setAttribute('gen_ai.system', 'huawei-cloud');
span.setAttribute('gen_ai.request.model', 'pangu-4.0');
// ... agent logic ...
span.setAttribute('gen_ai.usage.input_tokens', inputTokens);
span.setAttribute('gen_ai.usage.output_tokens', outputTokens);
span.end();

完整属性参考请参阅 references/genai-semconv.md。

第 6 步：验证数据到达

查询 agent-ops 观测 API，确认数据已摄取。 这些是管理平面 API — 使用 IAM 令牌（X-Auth-Token）进行身份验证，而不是使用 OTel 业务侧 Bearer 令牌：

ShowOpsTrace（官方 — 已验证）：

curl -X POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/traces \
  -H "X-Auth-Token: {iam_token}" \
  -H "Content-Type: application/json" \
  -d '{"start_time": 1720000000000, "end_time": 1720600000000}'

ShowOpsAgentMetricTrend（官方 — 已验证）：

curl -X POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/metrics/trend \
  -H "X-Auth-Token: {iam_token}" \
  -H "Content-Type: application/json" \
  -d '{"start_time": 1720000000000, "end_time": 1720600000000}'

ListOpsSession（已确认存在，路径需要手动验证）：

curl -X POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/sessions \
  -H "X-Auth-Token: {iam_token}" \
  -H "Content-Type: application/json" \
  -d '{"start_time": 1720000000000, "end_time": 1720600000000}'

注意：ListOpsTrace、ListOpsSession、ShowOpsAgentMetricGauge、 ListOpsAgentLog 的确切路径需要在 Huawei Cloud API Explorer 中手动验证。 请参阅 references/verification-method.md。

第 7 步：摄取诊断

常见诊断检查：

症状	检查
身份验证失败（401/403）	令牌已过期 → 重新获取业务令牌；检查 appcode 权限
未订阅	通过 SubscribeOpsObservation / OpenOpsObservation 订阅
Kafka 无法访问	检查 bootstrap-servers、SASL/SSL、主题是否存在
SDK/Collector 不匹配	确认 OTLP 协议版本兼容性
管理平面中没有数据	检查时间范围、区域、deliver_otel_trace=true
OTLP 直连不可用	agent-ops 没有 OTLP 接收器 → 回退到 Path A

核心命令

命令	用途	模式
hcloud APM CreateBusiness --cli-region={region}	创建追踪业务	CLI
hcloud APM ShowToken --cli-region={region}	获取业务令牌	CLI
POST /v1/apm2/openapi/tracing/business/create	创建追踪业务（API）	API
GET /v1/apm2/openapi/tracing/business/token/{id}	获取业务令牌（API）	API
POST /v1/apm2/openapi/tracing/access/get-access-point/{id}	获取接入点（API）	API
POST /v2/trace/deliver-config	创建 deliverConfig（用户提供）	API
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/traces	查询追踪数据	API
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/metrics/trend	查询指标趋势	API

参数确认

参数	必填	描述	示例
region	是	agent-ops 部署区域	cn-southwest-301
APM_ENDPOINT	是	APM OTLP 端点	https://apm2.cn-southwest-301.beta.myhuaweicloud.com
AGENT_OPS_ENDPOINT	是	AgentArts API 端点	https://agentarts.cn-southwest-301.myhuaweicloud.com
appName	是	应用名称	my-ai-agent
business_id	是（路径 A）	追踪业务 ID	来自创建响应
token	是	业务令牌（OTel exporter 身份验证，数据平面）	来自获取令牌的响应
iam_token	是	IAM 令牌（管理平面 API 身份验证）	来自 IAM STS
domain_id	是（路径 A）	IAM 域 ID	来自 IAM 控制台
kafka_topic	是（路径 A）	Kafka 主题名称	来自 deliverConfig
OTEL_EXPORTER_OTLP_ENDPOINT	否	预配置的 OTel 端点	环境变量
OTEL_SERVICE_NAME	否	预配置的服务名称	环境变量

KooCLI 命令格式标准

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

特性	描述	示例
服务名称	KooCLI 服务名称（大写）	APM
操作名称	PascalCase	CreateBusiness
区域参数	--cli-region=<value>	--cli-region={region}
简单参数	--key=value	--business_id=xxx

注意：尚未确认 AgentArts 观测 API（ShowOpsTrace、ShowOpsAgentMetricTrend 等）是否支持 KooCLI。 对于这些操作，请使用 API（curl）模式。

参考文档

• 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/genai-semconv.md — OpenTelemetry GenAI 语义约定

边缘情况

场景	处理方式
未安装 hcloud	所有操作均使用 API（curl）模式
无法使用 Python/SDK	使用带 YAML 配置的 OTel Collector 代替 SDK
DeliverConfig API 路径无效	在 API Explorer 中验证；标记为需要手动验证
agent-ops 没有 OTLP 接收器	使用路径 A（APM deliverConfig），而非路径 B
AI 应用没有 OTel 埋点	根据检测到的语言自动生成埋点配置
令牌已过期	通过 get-token API 重新获取业务令牌
管理平面中没有数据	检查时间范围、区域、deliver_otel_trace 标记和 Kafka 连通性

注意事项

• API 验证状态：APM 追踪 API 已正式验证。AgentArts 观测 API（ShowOpsTrace、ShowOpsAgentMetricTrend）已有正式文档。 DeliverConfig 和部分观测查询 API 需要手动验证。
• 凭据安全：切勿将 AK/SK 硬编码。请从环境变量或 CLI 配置文件中读取。
• GenAI 语义约定：OpenTelemetry GenAI 语义约定目前处于开发状态 （截至 OTel v1.41）。属性名称可能会变更。
• 最小权限：所需权限请参见 references/iam-policies.md。