文档中心

ArkClaw 企业版

管理员观测ArkClaw

自建网关用量数据上报

通过将自建网关数据上报到应用性能监控，可收集 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 企业版控制台获取。更多详细说明参见：空间信息。可基于此信息批量查询 ArkClaw 实例详情、用户详情和空间详情等信息。例如：可通过 ListClawInstances 接口获 Claw 实例 ID 信息。
APMPlus AppKey	378c****c45589**c08d****	若测试自建网关数据上报，建议单独创建新的工作区做数据写入验证和数据准确性验证，避免后续测试数据与正式数据混杂，影响看板质量。工作区创建和 AppKey 获取参考：工作区管理。
APMPlus AppKey	378c****c45589**c08d****		若直接将自建网关的数据上报到正式环境，可参考以下步骤获取 Claw 空间对应的 AppKey。通过 GetClawSpace 接口获取 Claw 空间对应的 ApmID 信息。前往应用性能监控工作区管理页面，查找 ApmID 同名的工作区。获取此工作区对应的 AppKey 信息，工作区与 AppKey 一一对应。获取方法参考：工作区管理。
APMPlus endpoint	apmplus-cn-beijing.volces.com:4317	上报地址。获取方法参考：获取 APMPlus endpoint 信息。说明通过域名直接上报数据到应用性能监控时，确保 header 中携带："X-ByteAPM-AppKey": ${app_key}。

操作步骤

数据上报使用 opentelemetry 协议，接入详细说明可参考 metrics API 介绍或应用性能监控的接入文档。以下以 Python 语言的开发流程为例进行说明：

执行以下代码，安装依赖。

pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp

在代码中创建 MeterProvider。

Opentelemetry 官方文档中的 Demo 将 metrics 打印到 console，但对于上报到应用性能监控的场景，除了需要更换 grpc/http exporter 信息外，还需要设置 endpoint 和 headers 等信息。创建示例如下:

注意

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

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

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": "<app_key>", # Claw 空间或测试工作区对应的 AppKey 信息。获取方法参见前提条件中的说明。
}
# 设置 resource attributes
resource_attributes = {
"service_name": "<claw_instance_id>", # 使用 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

进行指标打点。

业务代码中获取到模型供应商返回的有效 usage 信息后，调用 record_token_usage()，进行指标打点。示例如下：

注意

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

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

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)

刷新与关闭。

数据写入属于异步聚合操作，若为了方便测试，可在数据写入后立即执行刷新操作，避免因测试服务退出导致数据丢失。同时，为确保数据无丢失，网关服务重启/关闭前也需要刷新并关闭 metric provider，实现优雅重启/关闭。

# 测试或短任务：等待当前指标导出，便于立即验证。
metric_provider.force_flush(timeout_millis=10000)

# 服务优雅停机：在 ASGI/WSGI/Kubernetes shutdown hook 中调用一次。
metric_provider.shutdown(timeout_millis=10000)

结果验证

自建网关的用量数据成功上报后，可通过看板查看数据明细。

若将数据上报到测试工作区，可前往全栈可观测平台的预置看板中搜索自建网关用量分析看板，可视化查看数据明细。更多详细说明参见：预置看板。

若直接将数据上报到正式环境，可前往 ArkClaw 企业版的用量分析看板中，可视化查看数据明细。更多详细说明参见：查看 ArkClaw 用量分析。

最近更新时间：2026.08.20 15:27:01

这个页面对您有帮助吗？

有用

无用