Metric数据上报

安装依赖库

安装OpenTelemetry Python SDK及相关依赖库。要求Python 3.9或以上版本。

pip install opentelemetry-distro==0.62b1
pip install opentelemetry-api==1.41.1
pip install opentelemetry-exporter-otlp==1.41.1
pip install traceloop-sdk==0.60.0

获取上报参数

1. 在AgentArts平台左侧导航栏中选择“运营运维 > 观测”，并进入“智能体列表”页面。
2. 单击“智能体接入”，填写智能体名称，并选择类型。类型按实际选择。
   图1 智能体接入
   

3. 填写完成后，单击“创建”等待平台自动创建接入信息，记录接入地址、鉴权信息、智能体ID等信息。请妥善保管该信息。

   表1 接入信息说明

   参数	说明
   agent_id	智能体ID。
   metric_endpoint	Metric数据接入地址。
   metric_token	Metric上报鉴权Token。
   project_id	上报Metric数据时使用。在AgentArts页面获取。
   promID	上报Metric数据时使用。在AgentArts页面获取。

   图2 记录接入地址、鉴权信息、智能体ID等信息
   

上报Metric数据

配置参数信息：

在上报Metric数据前，需配置环境变量。服务名称（OTEL_SERVICE_NAME）必须遵循AgentArts.{{智能体ID}}.{{版本号}} 的格式（版本号默认填写default）。

OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer {metric_token},projectID={project_id},promID={prom_id},Content-Type=application/x-protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT={metric_endpoint}
OTEL_EXPORTER_OTLP_METRICS_INSECURE=true

上报Metric数据示例代码：

本示例用于首次接入平台时，验证上报网络、鉴权和配置是否正确。此阶段使用手动构造的静态数据。

示例中gen_ai.domain.id、gen_ai.user.id的取值请按实际进行替换，请登录“我的凭证 > API凭证”页面获取。

图3 获取domain id、user id

import os
import time
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry import metrics

# 1. 替换为您的真实接入凭证
AGENT_ID = "您的智能体ID"
METRIC_ENDPOINT = "您的Metric接入地址"
METRIC_TOKEN = "您的Metric鉴权Token"
PROJECT_ID = "您的ProjectID"
PROM_ID = "您的PromID"

# 2. 配置 OTel Metric 环境变量 (注意 Headers 格式与 Trace 不同)
os.environ["OTEL_SERVICE_NAME"] = f"AgentArts.{AGENT_ID}.default"
os.environ["OTEL_EXPORTER_OTLP_METRICS_HEADERS"] = f"Authorization={METRIC_TOKEN},projectID={PROJECT_ID},promID={PROM_ID},Content-Type=application/x-protobuf"
os.environ["OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"] = METRIC_ENDPOINT
os.environ["OTEL_EXPORTER_OTLP_METRICS_INSECURE"] = "true"

# 3. 初始化 Metric Provider，设置上报周期为 60000 毫秒（60秒）
metric_reader = PeriodicExportingMetricReader(
    OTLPMetricExporter(),
    export_interval_millis=60000
)
meter_provider = MeterProvider(metric_readers=[metric_reader])
metrics.set_meter_provider(meter_provider)

def report_metrics():
    meter = metrics.get_meter(__name__)

    # 定义一个计数器 (Counter)，用于统计模型请求总数
    request_counter = meter.create_counter(
        name="gen_ai.total.requests",
        unit="1",
        description="Number of requests to GenAI",
    )

    # 定义指标的关联维度 (Attributes)
    # 【注意】gen_ai.resource.id 必须与平台生成的智能体 ID 严格一致，注意替换gen_ai.domain.id、gen_ai.user.id的值
    attributes = {
        "gen_ai.resource.id": AGENT_ID,
        "gen_ai.resource.type": "agent",
        "gen_ai.model.id": "deepseek-v4-pro",
        "gen_ai.session.id": "session-001",
        "gen_ai.domain.id": "your_domain_id",
        "gen_ai.project.id": PROJECT_ID,
        "gen_ai.user.id": "your_user_id",
        "gen_ai.call.status": True,
        "gen_ai.space.id": "default"
    }

    # 业务发生时，计数器累加 1
    request_counter.add(1, attributes=attributes)

if __name__ == "__main__":
    print(f"==================================================")
    print(f" 智能体持续指标上报测试已启动！")
    print(f" 我们将持续运行 3 分钟，每 10 秒模拟一次调用。")
    print(f" 请保持此窗口运行，2分钟后刷新 AgentArts 观测控制台。")
    print(f"==================================================")

    # 模拟持续运行 3 分钟 (180 秒)，每 10 秒调用一次
    total_duration = 180
    interval = 10
    elapsed = 0

    while elapsed < total_duration:
        print(f"[{time.strftime('%H:%M:%S')}] 正在模拟第 {int(elapsed/interval) + 1} 次智能体业务调用...")
        report_metrics()

        time.sleep(interval)
        elapsed += interval

    # 测试结束，优雅关闭并强刷最后一批数据
    meter_provider.shutdown()
    print("==================================================")
    print(" 持续测试结束，指标数据已成功全部推送")
    print("==================================================")

为了保证您上报的Metric指标能够被 AgentArts 看板正确识别。您在代码中创建Meter时，指标名及关联的维度属性（Attributes）必须与平台标准严格对齐。关于所有可设置的Attribute字段及含义，请参考OpenTelemetry字段映射。

查看上报数据

上述示例代码中，定义了gen_ai.total.requests用于统计模型的请求总数。运行脚本后将触发模拟调用，调用完成后。在“运营运维 > 观测 > 智能体列表”页面，单击对应的智能体名称。可看到与模拟调用量相同的模型调用次数。

图4 查看上报数据

常见问题

运行上报脚本时，出现Failed to export metrics... error code: StatusCode.UNAUTHENTICATED鉴权失败报错

检查脚本的请求参数是否填写正确，检查metric_token、project_id、prom_id、Content-Type=application/x-protobuf的值是否有拼写错误。尤其检查Authorization的值中是否填写了重复的Bearer 前缀。

脚本执行成功没有报错，但在AgentArts中却看不到任何数据和折线图

• 原因一：

  原因分析：在您的指标属性中，“gen_ai.domain.id”如果填了“your_domain_id”这样的静态假数据，看板在采用您当前华为云真实账号进行查询时，会因为安全机制直接将非本租户的“数据”过滤掉。解决方案：gen_ai.domain.id、gen_ai.user.id需要按照您的真实信息填写。

• 原因二：
• 原因分析：

  原因分析：AOM底层计算QPS或请求量趋势图时，使用的是速率函数。这些函数在数学上必须在时间轴上至少有2个以上不同时间点的数据才能计算出斜率。如果您只跑了一次脚本并立即shutdown()，时序库里只有一个孤立的点，无法形成折线，在图表上就会显示空数据。解决方案：将代码改造成循环上报模式（例如在本地每10秒自动add 1次，持续运行3分钟以上），让数据形成连续的时序流。

• 原因三：

  原因分析：您在代码中上报的指标与在AgentArts中看的页面不是同一个。例如代码中上报的是gen_ai.total.requests，该指标对应的是“大模型调用次数”，如果找错了看板位置，则看不到数据。

  解决方案：根据上报的具体指标查看平台看板。