指标 API

GET /api/public/metrics

指标 API 让你能够从 Litefuse 数据中拉取自定义分析。该接口允许你指定维度、指标、过滤条件和时间粒度，从而为 LLM 应用构建强大的自定义报表与仪表盘。

指标 API v2

⚠️

仅 Cloud： v2 指标 API 仅在 Litefuse Cloud 上可用。我们正在为自托管部署提供平滑的迁移方案。

数据可用性说明： 在使用当前 SDK 版本时，数据可能需要约 5 分钟才能在 v2 接口上出现。我们将很快发布更新版本的 SDK，使数据可以立即可用。

GET /api/public/v2/metrics

v2 指标 API 通过基于新事件表 schema 的优化数据架构，将每次查询的数据库工作量降到最低，带来显著的性能提升。

与 v1 的关键差异

v2 中不再提供 traces 视图。 请改用 observations 视图，相比 v1 它更快、能力更强。

v2 中可用的视图

视图	说明
`observations`	查询 observation 级数据，可选地附带 trace 级聚合
`scores-numeric`	查询数值型与布尔型分数
`scores-categorical`	查询分类型（字符串）分数

行数限制

v2 指标 API 默认强制每次查询最多返回 100 行（rowLimit），以保证一致的性能。你可以在查询中指定自定义的 rowLimit 来覆盖这个默认值。

高基数维度

某些维度如 id、traceId、userId 和 sessionId 在 v2 指标 API 中不能用于分组。按这些高基数字段分组开销极大，实际中也很少有用。这些维度仍可用于过滤。

示例：observation 中成本最高的模型

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  -G \
  --data-urlencode 'query={
    "view": "observations",
    "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
    "dimensions": [{"field": "providedModelName"}],
    "filters": [],
    "fromTimestamp": "2025-12-01T00:00:00Z",
    "toTimestamp": "2025-12-16T00:00:00Z",
    "orderBy": [{"field": "totalCost_sum", "direction": "desc"}]
  }' \
  https://litefuse.cloud/api/public/v2/metrics

API 参考： 完整的参数、响应 schema 和交互示例请见 v2 指标 API 参考。

指标 API v1

指标 API 支持跨多个视图（traces、observations、scores）查询，让你可以：

选择特定维度对数据进行分组
应用多个指标，分别使用不同的聚合方式
基于元数据、时间戳和其他属性过滤数据
按可自定义的粒度跨时间分析数据
按需要对结果排序

查询参数

API 接受一个以 URL 编码方式传入的 JSON 查询对象：

参数	类型	说明
`query`	JSON 字符串	编码后的查询对象，定义要拉取哪些指标

查询对象结构

字段	类型	必填	说明
`view`	string	是	要查询的数据视图：`"traces"`、`"observations"`、`"scores-numeric"` 或 `"scores-categorical"`
`dimensions`	array	否	用于分组的维度对象数组，例如 `[{ "field": "name" }]`
`metrics`	array	是	要计算的指标对象数组，例如 `[{ "measure": "latency", "aggregation": "p95" }]`
`filters`	array	否	用于缩小结果范围的过滤对象数组，例如 `[{ "column": "metadata", "operator": "contains", "key": "customKey", "value": "customValue", "type": "stringObject" }]`
`timeDimension`	object	否	基于时间的分析配置，例如 `{ "granularity": "day" }`
`fromTimestamp`	string	是	查询周期起始的 ISO 时间戳
`toTimestamp`	string	是	查询周期结束的 ISO 时间戳
`orderBy`	array	否	结果排序规则，例如 `[{ "field": "name", "direction": "asc" }]`

维度对象结构

{ "field": "name" }

指标对象结构

{ "measure": "count", "aggregation": "count" }

常见的 measure 类型包括：

count - 记录数
latency - 持续时间/延迟指标

聚合类型包括：

sum - 求和
avg - 平均值
count - 记录数
max - 最大值
min - 最小值
p50 - 50 分位
p75 - 75 分位
p90 - 90 分位
p95 - 95 分位
p99 - 99 分位

过滤对象结构

{
  "column": "metadata",
  "operator": "contains",
  "key": "customKey",
  "value": "customValue",
  "type": "stringObject"
}

时间维度对象

{
  "granularity": "day"
}

支持的粒度包括：hour、day、week、month 和 auto。

示例

下面是一个按 name 分组查询 trace 数量的示例：

curl \
-H "Authorization: Basic <BASIC AUTH HEADER>" \
-G \
--data-urlencode 'query={
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}' \
https://litefuse.cloud/api/public/metrics

响应：

{
  "data": [
    { "name": "trace-test-2", "count_count": "10" },
    { "name": "trace-test-3", "count_count": "5" },
    { "name": "trace-test-1", "count_count": "3" }
  ]
}

数据模型

指标 API 提供了多个数据视图，每个视图都有自己可查询的维度与指标集合。本节列出了每个视图的可用选项。

可用视图

视图	说明
`traces`	在 trace 层级查询数据
`observations`	在 observation 层级查询数据
`scores-numeric`	查询数值型与布尔型分数
`scores-categorical`	查询分类型（字符串）分数

Trace 维度

维度	类型	说明
`id`	string	Trace ID
`name`	string	Trace 名称
`tags`	string[]	Trace 标签
`userId`	string	与该 trace 关联的用户 ID
`sessionId`	string	与该 trace 关联的会话 ID
`release`	string	Release 标记
`version`	string	Version 标记
`environment`	string	环境（如 production、staging）
`observationName`	string	关联 observation 的名称
`scoreName`	string	关联分数的名称

Trace 指标

指标	说明
`count`	trace 数量
`observationsCount`	trace 中包含的 observation 数量
`scoresCount`	trace 中包含的分数数量
`latency`	trace 持续时间（毫秒）
`totalTokens`	trace 中使用的 token 总数
`totalCost`	trace 的总成本

Observation 维度

维度	类型	说明
`id`	string	Observation ID
`traceId`	string	关联的 trace ID
`traceName`	string	父 trace 的名称
`environment`	string	环境（如 production、staging）
`parentObservationId`	string	父 observation 的 ID
`type`	string	Observation 类型
`name`	string	Observation 名称
`level`	string	日志级别
`version`	string	版本
`providedModelName`	string	模型名称
`promptName`	string	Prompt 名称
`promptVersion`	string	Prompt 版本
`userId`	string	来自父 trace 的用户 ID
`sessionId`	string	来自父 trace 的会话 ID
`traceRelease`	string	来自父 trace 的 release
`traceVersion`	string	来自父 trace 的 version
`scoreName`	string	关联分数的名称

Observation 指标

指标	说明
`count`	observation 数量
`latency`	observation 持续时间（毫秒）
`totalTokens`	使用的 token 总数
`totalCost`	总成本
`timeToFirstToken`	首 token 时间（毫秒）
`countScores`	关联分数的数量

Score 维度（通用）

维度	类型	说明
`id`	string	分数 ID
`name`	string	分数名称
`environment`	string	环境
`source`	string	分数来源
`dataType`	string	数据类型
`traceId`	string	关联的 trace ID
`traceName`	string	关联的 trace 名称
`userId`	string	来自 trace 的用户 ID
`sessionId`	string	来自 trace 的会话 ID
`observationId`	string	关联的 observation ID
`observationName`	string	关联的 observation 名称
`observationModelName`	string	关联 observation 中使用的模型
`observationPromptName`	string	关联 observation 中使用的 prompt 名称
`observationPromptVersion`	string	关联 observation 中使用的 prompt 版本
`configId`	string	配置 ID

Score 指标

数值型分数

指标	说明
`count`	分数数量
`value`	数值型分数的值

分类型分数

指标	说明
`count`	分数数量

分类型分数额外包含一个维度：

维度	类型	说明
`stringValue`	string	分类型分数的字符串值

每日指标 API（旧版）

⚠️

这是一个旧版 API。新场景请改用指标 API。它的速率限制更高，灵活性更强。

GET /api/public/metrics/daily

通过每日指标 API，你可以从 Litefuse 拉取按天聚合的用量与成本指标，用于下游场景，如分析、计费和限流。该 API 允许你按应用类型、用户或标签进行过滤，以获取定制化的数据。

更多细节请参见 API 参考。

概览

返回的数据包含以下每日时间序列：

以美元计的成本
trace 与 observation 数量
按模型名称拆分
按输入与输出拆分的用量（如 token）
以美元计的成本
trace 与 observation 数量

可选过滤条件：

traceName：按应用类型过滤，具体取决于你如何在 trace 中使用 name
userId：按用户过滤
tags：按标签过滤
fromTimestamp
toTimestamp

缺少某个关键指标或过滤条件？欢迎到我们的建议板提出。

示例

GET /api/public/metrics/daily?traceName=my-copilot&userId=john&limit=2

{
  "data": [
    {
      "date": "2024-02-18",
      "countTraces": 1500,
      "countObservations": 3000,
      "totalCost": 102.19,
      "usage": [
        {
          "model": "llama2",
          "inputUsage": 1200,
          "outputUsage": 1300,
          "totalUsage": 2500,
          "countTraces": 1000,
          "countObservations": 2000,
          "totalCost": 50.19
        },
        {
          "model": "gpt-4",
          "inputUsage": 500,
          "outputUsage": 550,
          "totalUsage": 1050,
          "countTraces": 500,
          "countObservations": 1000,
          "totalCost": 52.0
        }
      ]
    },
    {
      "date": "2024-02-17",
      "countTraces": 1250,
      "countObservations": 2500,
      "totalCost": 250.0,
      "usage": [
        {
          "model": "llama2",
          "inputUsage": 1000,
          "outputUsage": 1100,
          "totalUsage": 2100,
          "countTraces": 1250,
          "countObservations": 2500,
          "totalCost": 250.0
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 2,
    "totalItems": 60,
    "totalPages": 30
  }
}

自定义仪表盘术语表

这个页面对你有帮助吗？

支持