huaweicloud/huaweicloud-skills

huawei-cloud-agentarts-otel-ingestion

OpenTelemetry ingestion skill for Huawei Cloud AgentArts observability platform.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/huaweicloud/huaweicloud-skills --skill huawei-cloud-agentarts-otel-ingestion

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

Huawei Cloud AgentArts OpenTelemetry Ingestion

Overview

This skill enables OpenTelemetry (OTel) telemetry data ingestion into Huawei Cloud AgentArts observability platform (agent-ops). It covers four functional areas:

  1. OTel Telemetry Ingestion — Route trace/metrics/logs from applications to

agent-ops via APM deliverConfig forwarding (Path A, recommended) or OTLP direct connection (Path B, verification only).

  1. AI Agent Observation — Instrument AI/LLM applications with OpenTelemetry GenAI

semantic conventions (gen_ai.* spans, token usage metrics, model call chains).

  1. Auto-Configuration — Detect application language/framework and generate

ready-to-use OTel SDK/Collector configuration.

  1. Ingestion Diagnostics — Verify data arrival via agent-ops observation APIs

(trace/session/metric/log queries).

Architecture

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

Data Flow

See references/dataflow-diagram.md for the Mermaid diagram.

Prerequisites

1. Huawei Cloud Credentials

Set credentials out-of-band. Never paste AK/SK in chat.

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

Verify by running the CLI configure list command (if hcloud CLI is installed).

2. hcloud CLI (KooCLI)

Install: https://support.huaweicloud.com/qs-hcli/hcli02003.html

3. APM Subscription

Confirm agent-ops has subscribed to APM observation. If not subscribed, complete subscription first (management plane: SubscribeOpsObservation / OpenOpsObservation).

4. IAM Permissions

See references/iam-policies.md for least-privilege policy.

5. OTel SDK

Install language-specific OTel packages:

  • Java: opentelemetry-javaagent (download 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

Workflow

Step 1: Confirm Application Environment

Detect the application language/framework:

LanguageDetection MethodOTel Instrument
Javapom.xml / build.gradle / .jar filesopentelemetry-javaagent
Pythonrequirements.txt / pyproject.tomlopentelemetry-sdk
Node.jspackage.json@opentelemetry/sdk-node
Gogo.modgo.opentelemetry.io/otel

If existing OTel config is detected, read and adjust rather than overwrite.

Step 2: Confirm Target Environment

ParameterDefaultDescription
regioncn-southwest-301agent-ops deployment region
APM_ENDPOINThttps://apm2.cn-southwest-301.beta.myhuaweicloud.comAPM OTLP endpoint
AGENT_OPS_ENDPOINThttps://agentarts.cn-southwest-301.myhuaweicloud.comAgentArts API endpoint
apm.internal.endpointInternal endpointFor deliverConfig forwarding
wushan.common.appcodeApp codeFor internal endpoint auth

Step 3: Confirm Ingestion Scope

  • Data types: traces / metrics / logs
  • Application name (appName) and business ID (businessId)

Step 4: Execute Ingestion (Path A or B)

Path A: APM deliverConfig Ingestion (Recommended)

4a. Create tracing business (official API — verified via IAM authorization reference):

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

API equivalent (official path):

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. Get business token (official API):

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

API equivalent:

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

Record the returned token for application-side OTel exporter auth.

4c. Get access point (official 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. Create deliverConfig forwarding (user-provided API — requires manual verification):

Note: This endpoint is from user-provided reference, not found in official public docs. Verify the exact path in Huawei Cloud API Explorer before use.
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}"
  }
}

Modify: PUT /v2/trace/deliver-config (body: {id, deliver_otel_trace}) Delete: DELETE /v2/trace/deliver-config/{id}?region=

4e. Configure application-side OTel SDK/Collector

Java Agent:

bash
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:

python
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:

javascript
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:

go
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):

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 Direct Connection (Verification Only)

As of current agent-ops version, the backend contains OTLP proto definitions but no OTLP receiver implementation. Path B is for verification testing only.
  1. Deploy OTel Collector with OTLP receiver and test exporter.
  2. Generate test spans from a sample application.
  3. Verify data export to confirm SDK/Collector config correctness.
  4. Use management plane APIs to verify data reachability.

Step 5: AI Agent Observation (GenAI Semantic Conventions)

Instrument AI/LLM applications with OpenTelemetry GenAI semantic conventions:

Span NameDescriptionKey Attributes
invoke_agentAgent invocationgen_ai.system, gen_ai.request.model
execute_toolTool executiongen_ai.tool.name, gen_ai.tool.description
inferenceModel inferencegen_ai.usage.input_tokens, gen_ai.usage.output_tokens

Python example (LLM tracing):

python
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 example:

javascript
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();

See references/genai-semconv.md for full attribute reference.

Step 6: Verify Data Arrival

Query agent-ops observation APIs to confirm data ingestion. These are management plane APIs — authenticate with IAM token (X-Auth-Token), not the OTel business-side Bearer token:

ShowOpsTrace (official — verified):

bash
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 (official — verified):

bash
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 (existence confirmed, path requires manual verification):

bash
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}'
Note: Exact paths for ListOpsTrace, ListOpsSession, ShowOpsAgentMetricGauge, ListOpsAgentLog require manual verification in Huawei Cloud API Explorer. See references/verification-method.md.

Step 7: Ingestion Diagnostics

Common diagnostic checks:

SymptomCheck
Auth failure (401/403)Token expired → re-fetch business token; check appcode permissions
No subscriptionSubscribe via SubscribeOpsObservation / OpenOpsObservation
Kafka unreachableCheck bootstrap-servers, SASL/SSL, topic existence
SDK/Collector mismatchConfirm OTLP protocol version compatibility
No data in management planeCheck time range, region, deliver_otel_trace=true
OTLP direct unavailableagent-ops has no OTLP receiver → fall back to Path A

Core Commands

CommandPurposeMode
hcloud APM CreateBusiness --cli-region={region}Create tracing businessCLI
hcloud APM ShowToken --cli-region={region}Get business tokenCLI
POST /v1/apm2/openapi/tracing/business/createCreate tracing business (API)API
GET /v1/apm2/openapi/tracing/business/token/{id}Get business token (API)API
POST /v1/apm2/openapi/tracing/access/get-access-point/{id}Get access point (API)API
POST /v2/trace/deliver-configCreate deliverConfig (user-provided)API
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/tracesQuery tracesAPI
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/metrics/trendQuery metric trendAPI

Parameter Confirmation

ParameterRequiredDescriptionExample
regionYesagent-ops deployment regioncn-southwest-301
APM_ENDPOINTYesAPM OTLP endpointhttps://apm2.cn-southwest-301.beta.myhuaweicloud.com
AGENT_OPS_ENDPOINTYesAgentArts API endpointhttps://agentarts.cn-southwest-301.myhuaweicloud.com
appNameYesApplication namemy-ai-agent
business_idYes (Path A)Tracing business IDFrom create response
tokenYesBusiness token (OTel exporter auth, data plane)From get-token response
iam_tokenYesIAM token (management plane API auth)From IAM STS
domain_idYes (Path A)IAM domain IDFrom IAM console
kafka_topicYes (Path A)Kafka topic nameFrom deliverConfig
OTEL_EXPORTER_OTLP_ENDPOINTNoPre-configured OTel endpointEnv var
OTEL_SERVICE_NAMENoPre-configured service nameEnv var

KooCLI Command Format Standard

bash
hcloud <Service> <Operation> --cli-region=<region> [--key=value ...]
FeatureDescriptionExample
Service nameKooCLI Service name (uppercase)APM
Operation namePascalCaseCreateBusiness
Region parameter--cli-region=<value>--cli-region={region}
Simple parameter--key=value--business_id=xxx
Note: AgentArts observation APIs (ShowOpsTrace, ShowOpsAgentMetricTrend, etc.) are not yet confirmed in KooCLI. Use API (curl) mode for these operations.

Reference Documents

  • references/iam-policies.md — Least-privilege IAM policies
  • references/cli-installation-guide.md — hcloud CLI installation guide
  • references/verification-method.md — Verification methods and API status
  • references/dataflow-diagram.md — Mermaid data flow diagram
  • references/acceptance-criteria.md — Acceptance criteria checklist
  • references/genai-semconv.md — OpenTelemetry GenAI semantic conventions

Edge Cases

ScenarioHandling
hcloud not installedUse API (curl) mode for all operations
Python/SDK not availableUse OTel Collector with YAML config instead of SDK
DeliverConfig API path invalidVerify in API Explorer; mark as requires manual verification
agent-ops has no OTLP receiverUse Path A (APM deliverConfig) instead of Path B
AI app has no OTel instrumentationAuto-generate instrumentation config based on detected language
Token expiredRe-fetch business token via get-token API
No data in management planeCheck time range, region, deliveroteltrace flag, Kafka connectivity

Notes

  • API verification status: APM tracing APIs are officially verified. AgentArts

observation APIs (ShowOpsTrace, ShowOpsAgentMetricTrend) are officially documented. DeliverConfig and some observation query APIs require manual verification.

  • Credential security: Never hardcode AK/SK. Read from env vars or CLI profile.
  • GenAI semconv: OpenTelemetry GenAI semantic conventions are in Development

status (as of OTel v1.41). Attribute names may change.

  • Least privilege: See references/iam-policies.md for required permissions.
dallo stesso repository

Altri Skills

Tutti gli Skills
huaweicloud
Community

huawei-cloud-devbridge-tunnel

Create and manage DevBridge development tunnels on Huawei Cloud to securely expose local development services to remote devices. Based on DevBridge CLI v0.2.x and API Key authentication. Use this skill when the user wants to: (1) install and configure the DevBridge CLI, (2) create/list/update/delete tunnels, (3) manage tunnel ports and protocols, (4) host local services through tunnels, (5) connect to remote tunnels from another device, (6) manage authentication and API Keys. Trigger: user menti

Installazioni / 1h
3
GitHub Stars
59
Aggiornato
20 nov
huaweicloud
Community

huawei-cloud-find-skills

Invoke this skill to search, list, query, discover, browse, find and install any Huawei Cloud (华为云) agent skill. Triggers include: "华为云", "华为云有什么skill", "华为云相关skill", "华为云agent skill 市场", "华为云skill类目", "explore Huawei Cloud skills", "show Huawei Cloud skill categories", "does a Huawei Cloud skill exist for...", "which Huawei Cloud skills exist", "搜索华为云技能", "查询华为云skill列表", "有没有管理ECS/OBS/RDS的skill", "帮我找 XX 华为云skill", "介绍 XX Skill 内容", "华为云 XX Skill 具体做什么", "安装华为云Skill".

Installazioni / 1h
3
GitHub Stars
59
Aggiornato
20 nov
huaweicloud
Community

huawei-cloud-terraform-installer

Installs Terraform CLI cross-platform with Huawei Cloud mirror support. Use this skill whenever the user mentions installing Terraform, setting up Terraform environment, or when IaC tasks detect missing Terraform. Trigger: install terraform, setup terraform, terraform environment, huaweicloud provider.

Installazioni / 1h
6
GitHub Stars
59
Aggiornato
7 nov
huaweicloud
Community

huawei-cloud-billing-scout

Huawei Cloud BSS billing (not AWS/Azure/other clouds; refuses pricing quotes, real-name review, and any non-billing scope): balance, spend, attribution, reconciliation, coupons, stored-value cards, enterprise/partner billing. One-page briefing via hcloud. Use when the request is about Huawei Cloud billing. Triggers include: 华为云余额, 华为云欠费, 华为云本月花费, 华为云扣费原因, 华为云账单对账, 华为云资源包, 华为云优惠券, 华为云企业主账号, 华为云伙伴账务, 华为云服务编码, Huawei Cloud balance / bill / spend / reconciliation / coupon / stored-value card / BSS b

Installazioni / 1h
5
GitHub Stars
59
Aggiornato
7 nov