ArkClaw Enterprise supports comprehensive metric query capabilities through Server-side Monitoring. In addition to the basic visual dashboards, Server-side Monitoring provides a unified metric query API that allows you to customize metric queries based on your needs. In this topic, the preset metric arkclaw_enterprise_total_token_usage_sum is used as an example to describe how to query ArkClaw Enterprise metrics.

Background

The Draw API provided by Server-side Monitoring is available for querying ArkClaw Enterprise metrics.

Item	The value of a label
API name	Draw, for metric graph queries
Action	Draw
Version	2022-11-09
Document	Draw API help documentation
Protocol	HTTPS POST. The request body is JSON.

The reference for the basic information about the preset metric arkclaw_enterprise_total_token_usage_sum.

Category	Description
Preset metric	arkclaw_enterprise_total_token_usage_sum
Metric definition	Total token consumption of ArkClaw instances across input, output, and cache.
Grouping dimensions	Configure grouping dimensions based on your needs. The available fields include: service: instance ID user_email: user email user_name: user name user_department: user department claw_space_id: Claw space ID openclaw_token: Token type openclaw_channel: channel openclaw_provider: service provider openclaw_model: model

Limits

Draw supports both preset metric queries and PromQL queries. However, because the user information in ArkClaw Enterprise metrics comes from external APIs or underlying instrumentation, PromQL queries are not supported. You can use preset metric queries only.

Query examples

Because the API parameters are relatively complex, to reduce debugging costs, the preset metric arkclaw_enterprise_total_token_usage_sum is used as an example to describe several common query examples for preset metric queries.

Example 1: Single value query / instant query

Example 2: Time series query

This example illustrates how to query the total token consumption.

warning

In a single-value query request, set the parameter "instant": true. The result is returned in Table format.

Modify metric to query the specified metric. To query ArkClaw metrics, simply set metric_category to claw.

To set filter conditions, modify filters. To specify grouping dimensions, use group_by_fields.

To specify a query time range, modify start_time and end_time.

Sample request

tip

If custom tags are configured for an ArkClaw instance, you can use the tags in filters to filter data and in group_by_fields to query data by group. For details of ArkClaw instance custom tags, see Managing tags.

Sample response

The query response format is as follows. Focus on Columns and Rows in the response. When you query only one metric at a time, the last column in Columns is always the query result value, and the preceding columns contain the related attribute information. ValueColumns identifies which columns are metric value columns.

Columns: The meaning of each column in the result.

Rows: Each element represents a row in the result. The meaning of each column corresponds one-to-one with Columns.

This example illustrates how to query the total token consumption trend.

warning

In a time series query request, set the graph_type parameter to time_series. The request returns data in time series format, where each time series contains data points aligned by time granularity along with the corresponding label information.

Modify metric to query the specified metric. To query ArkClaw metrics, simply set metric_category to claw.

To set filter conditions, modify filters. To specify grouping dimensions, use group_by_fields.

To specify a query time range, modify start_time and end_time.

Sample request

tip

If custom tags are configured for an ArkClaw instance, you can use the tags in filters to filter data and in group_by_fields to query data by group. For details of ArkClaw instance custom tags, see Managing tags.

Sample response

The query response format is as follows. Focus on TimeSeries in the response. In TimeSeries, each object is a single time series; Points contains the timestamp and corresponding value of each point in the time series; TagKvs contains all the attribute information of the time series.

tip

If custom tags are configured for an ArkClaw instance, you can use the tags in filters to filter data and in group_by_fields to query data by group.

Observability Platform