通过将自建网关数据上报到应用性能监控，可收集 Token 输入/输出/缓存调用的用量数据，依托平台可观测能力实现可视化展示，精准呈现真实的业务用量与访问趋势，便于直观掌握资源消耗情况。本文为您介绍如何将自建网关的用量数据上报到应用性能监控。

说明

本文仅针对自建网关场景下的用量数据上报进行标准定义说明，若存在其他指标上报需求，可参考此规范做额外设定。

## 背景信息 ArkClaw 企业版支持用户绑定自建网关，并将自有模型池开放给员工端使用，但目前自建网关的数据并未纳入可观测展示范围。若存在 Token 用量展示需求，需要将自建网关 Token 用量数据上报至应用性能监控，上报成功后，即可在应用性能监控的预置看板或 ArkClaw 企业版的用量分析看板中查看数据明细。 ### 指标说明

说明

Counter 属于单调递增的同步指标。支持通过 SDK 按累计或增量时态导出，但业务侧始终只允许调用 add (本次增量)，不允许调用 add (累计总数)，也不允许传入负数。

|**指标名称** |**类型** |**单位** |**描述** | |---|---|---|---| |custom_gateway_token_used |Counter |1（number） |自建网关 Token 使用消耗。 | ### 标签字段 |**标签（Label）** |是否必填 |**示例** |**描述** | |---|---|---|---| |apmplus_business_carrier |是 |arkclaw_enterprise |固定值：`arkclaw_enterprise`，需要添加在 resource attribute 中。 | |service |是 |claw_instance_xxx |Claw 实例 ID，需要添加在 resource attribute 中。 | |claw_space_id |是 |space_xxx |Claw 实例所属的工作空间。 | |token_type |是 |input

|Token 类型，枚举值包括：

* input：输入 Token 消耗。

* output：输出 Token 消耗。

* cache_read：缓存 Token 消耗。 | |model |是 |doubao\-pro\-32k |模型名称。 | |provider |是 |ark |模型厂商。

| |from |是 |gateway\-prod\-bj |数据来源。推荐填写自建网关名称或唯一稳定的 ID 信息，禁止填写动态地址。 | |user_name |是 |zhangsan |用户名称，属于用户元信息。

说明

用户名称、邮箱、部门等用户元信息可通过 ListUsers 接口获取。

| |user_email

|是 |zhangsan@example.com |用户邮箱，属于用户元信息。 | |user_department

|是 |gateway\-prod\-bj |用户部门，属于用户元信息。 | ## 前提条件上报自建网关的用量数据时，需要用到以下关键信息。 |关键信息 |示例 |说明 | |---|---|---| |ArkClaw SpaceID |csi\-yehw6ow1kwa5g0\*\*\*\* |ArkClaw 的空间 ID 信息，直接前往 ArkClaw 企业版控制台获取。更多详细说明参见：[空间信息](https://docs.volcengine.com/docs/87732/2272766)。

可基于此信息批量查询 ArkClaw 实例详情、用户详情和空间详情等信息。例如：可通过 [ListClawInstances](https://docs.volcengine.com/docs/87732/2466959?lang=zh) 接口获 Claw 实例 ID 信息。 | |APMPlus AppKey |378c\*\*\*\*\*\*c45589\*\*\*\*\*\*c08d\*\*\*\*\*\* |若测试自建网关数据上报，建议单独创建新的工作区做数据写入验证和数据准确性验证，避免后续测试数据与正式数据混杂，影响看板质量。

工作区创建和 AppKey 获取参考：[工作区管理](https://docs.volcengine.com/docs/6431/2479228?lang=zh)。 | |||若直接将自建网关的数据上报到正式环境，可参考以下步骤获取 Claw 空间对应的 AppKey。

1. 通过 [GetClawSpace](https://docs.volcengine.com/docs/87732/2532487?lang=zh) 接口获取 Claw 空间对应的 ApmID 信息。

2. 前往应用性能监控工作区管理页面，查找 ApmID 同名的工作区。

3. 获取此工作区对应的 AppKey 信息，工作区与 AppKey 一一对应。获取方法参考：[工作区管理](https://docs.volcengine.com/docs/6431/2479228?lang=zh)。 | |APMPlus endpoint |apmplus\-cn\-beijing.volces.com:4317 |上报地址。获取方法参考：[获取 APMPlus endpoint 信息](https://docs.volcengine.com/docs/6431/147492?lang=zh#59K0hBuu)。

说明

通过域名直接上报数据到应用性能监控时，确保 header 中携带："X-ByteAPM-AppKey": ${app_key}。

| ## 操作步骤数据上报使用 opentelemetry 协议，接入详细说明可参考 [metrics API](https://opentelemetry.io/docs/specs/otel/metrics/api/) 介绍或应用性能监控的 [接入文档](https://docs.volcengine.com/docs/6431/81123?lang=zh#mPM2DyRw)。以下以 Python 语言的开发流程为例进行说明： 1. 执行以下代码，安装依赖。 ```Plain Text pip install opentelemetry-api pip install opentelemetry-sdk pip install opentelemetry-exporter-otlp ``` 2. 在代码中创建 [MeterProvider](https://opentelemetry.io/docs/specs/otel/metrics/api/#meterprovider)。 [Opentelemetry 官方文档](https://opentelemetry.io/docs/languages/python/instrumentation/) 中的 Demo 将 metrics 打印到 console，但对于上报到应用性能监控的场景，除了需要更换 grpc/http exporter 信息外，还需要设置 endpoint 和 headers 等信息。创建示例如下:

注意

init_metrics() 必须在进程启动阶段调用一次。多 worker 部署时，每个进程各自初始化一套 Provider 属于正常行为，但不能在同一进程里重复调用 metrics.set_meter_provider()。

service.instance.id 必须设置一个唯一标识当前实例的信息，建议使用 uuid 或 pod name，否则会导致数据查询异常。

```Python import uuid from opentelemetry import metrics from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import ( ConsoleMetricExporter, PeriodicExportingMetricReader, ) from opentelemetry.sdk.resources import Resource from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter def init_metrics(): # 设置上报地址为 apmplus endpoint endpoint = "apmplus-cn-beijing.volces.com:4317" # endpoint 信息。获取方法参见前提条件中的说明。 headers = { "x-byteapm-appkey": "", # Claw 空间或测试工作区对应的 AppKey 信息。获取方法参见前提条件中的说明。 } # 设置 resource attributes resource_attributes = { "service_name": "", # 使用 claw_instance_id 填充，此数据会在写入时填充到 service 标签字段。 "apmplus_business_carrier": "arkclaw_enterprise", # 标识 arkclaw 企业版数据。 "service.instance.id": str(uuid.uuid4()), # 进程启动时将生成一个随机 UUID，标识本次进程实例。 } resource = Resource.create(resource_attributes) exporter = OTLPMetricExporter(endpoint=endpoint, headers=headers) metric_reader = PeriodicExportingMetricReader(exporter) provider = MeterProvider(metric_readers=[metric_reader], resource=resource) # Sets the global default meter provider metrics.set_meter_provider(provider) # Creates a meter from the global meter provider meter = metrics.get_meter( "arkclaw.custom_gateway", version="1.0.0" ) token_used_metrics = meter.create_counter( name="custom_gateway_token_used", unit="1", description="Token usage reported by an ArkClaw custom gateway", ) return provider, token_used_metrics ``` 3. 进行指标打点。业务代码中获取到模型供应商返回的有效 usage 信息后，调用 `record_token_usage()`，进行指标打点。示例如下：

注意

打点为旁路逻辑，不应影响主链路。

Counter 的 attributes 可用于预置看板聚合和筛选。

```Python def record_token_usage( token_used_metrics, *, token_type: str, token_count: int, claw_space_id: str, claw_instance_id: str, model: str, provider: str, gateway_id: str, user_name: str | None = None, user_email: str | None = None, user_department: str | None = None, ) -> None: # 设置指标标签。 attributes = { "claw_space_id": claw_space_id, "token_type": token_type, "service": claw_instance_id, "model": _required_string("model", model), "provider": _required_string("provider", provider).lower(), "from": _required_string("gateway_id", gateway_id), } # 用户维度，如需其他维度，可按需添加。 optional_attributes = { "user_name": user_name, "user_email": user_email.lower() if user_email else None, "user_department": user_department, } attributes.update( { key: str(value).strip() for key, value in optional_attributes.items() if value is not None and str(value).strip() } ) # 传入本次调用的增量，并非历史累计值。 token_used_metrics.add(token_count, attributes=attributes) ``` 4. 刷新与关闭。数据写入属于异步聚合操作，若为了方便测试，可在数据写入后立即执行刷新操作，避免因测试服务退出导致数据丢失。同时，为确保数据无丢失，网关服务重启/关闭前也需要刷新并关闭 metric provider，实现优雅重启/关闭。 ```Python # 测试或短任务：等待当前指标导出，便于立即验证。 metric_provider.force_flush(timeout_millis=10000) # 服务优雅停机：在 ASGI/WSGI/Kubernetes shutdown hook 中调用一次。 metric_provider.shutdown(timeout_millis=10000) ``` ## 结果验证自建网关的用量数据成功上报后，可通过看板查看数据明细。 * 若将数据上报到测试工作区，可前往全栈可观测平台的预置看板中搜索 **自建网关用量分析** 看板，可视化查看数据明细。更多详细说明参见：[预置看板](https://docs.volcengine.com/docs/86845/2137605)。 * 若直接将数据上报到正式环境，可前往 ArkClaw 企业版的 **用量分析** 看板中，可视化查看数据明细。更多详细说明参见：[查看 ArkClaw 用量分析](https://docs.volcengine.com/docs/87732/2272036)。