huawei-cloud-agentarts-otel-ingestion

Huawei Cloud AgentArts OpenTelemetry 取り込み

概要

このスキルでは、Huawei Cloud AgentArts のオブザーバビリティプラットフォーム（agent-ops）への OpenTelemetry（OTel）テレメトリデータの取り込みを有効にします。次の4つの機能領域を扱います。

1. OTel テレメトリの取り込み — APM の deliverConfig 転送（パス A、推奨）または OTLP の直接接続（パス B、検証のみ）を通じて、アプリケーションのトレース／メトリクス／ログを agent-ops にルーティングします。
2. AI エージェントのオブザーバビリティ — OpenTelemetry GenAI のセマンティック規約（gen_ai.* スパン、トークン使用量メトリクス、モデル呼び出しチェーン）を使用して、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. Huawei Cloud の認証情報

認証情報はチャット外で設定してください。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

ワークフロー

Step 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 設定が検出された場合は、上書きせずに読み込んで調整してください。

Step 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	アプリコード	内部エンドポイントの認証用

Step 3：取り込み対象の確認

• データの種類：トレース／メトリクス／ログ
• アプリケーション名（appName）とビジネス ID（businessId）

Step 4：取り込みの実行（パス A または B）

パス 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 エクスポーター認証に使用します。

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]

パス B：OTLP の直接接続（検証のみ）

現在の agent-ops バージョンでは、バックエンドに OTLP proto 定義は含まれていますが、 OTLP レシーバーの実装はありません。パス B は検証テスト専用です。

1. OTLP レシーバーとテスト用エクスポーターを備えた OTel Collector をデプロイします。
2. サンプルアプリケーションからテスト用スパンを生成します。
3. データのエクスポートを確認し、SDK／Collector の設定が正しいことを検証します。
4. 管理プレーン API を使用して、データに到達できることを確認します。

ステップ 5：AI エージェントの観測（GenAI セマンティック規約）

OpenTelemetry GenAI セマンティック規約を使用して、AI／LLM アプリケーションを計装します。

スパン名	説明	主な属性
invoke_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 です。OTel ビジネス側の Bearer トークンではなく、IAM トークン（X-Auth-Token）で認証してください。

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 レシーバーがありません → パス 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 エクスポーター認証、データプレーン）	トークン取得レスポンスから取得
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 が利用できない	SDK の代わりに YAML 設定で OTel Collector を使用
DeliverConfig API のパスが無効	API Explorer で確認し、手動検証が必要として記録
agent-ops に OTLP レシーバーがない	パス B の代わりにパス A（APM deliverConfig）を使用
AI アプリに OTel 計装がない	検出した言語に基づいて計装設定を自動生成
トークンの有効期限切れ	get-token API でビジネストークンを再取得
管理プレーンにデータがない	時間範囲、リージョン、deliver_otel_trace フラグ、Kafka 接続を確認

注記

• API の検証状況：APM トレーシング API は正式に検証済みです。AgentArts オブザベーション API（ShowOpsTrace、ShowOpsAgentMetricTrend）は正式に文書化されています。 DeliverConfig と一部のオブザベーションクエリ API は手動での検証が必要です。
• 認証情報のセキュリティ：AK/SK をハードコードしないでください。環境変数または CLI プロファイルから読み込んでください。
• GenAI semconv：OpenTelemetry GenAI セマンティック規約は開発中のステータスです （OTel v1.41 時点）。属性名は変更される可能性があります。
• 最小権限：必要な権限については references/iam-policies.md を参照してください。