agentbase-docs

可观测性 API

LLM 应用可观测性数据面(兼容 Langfuse 语义):trace / observation / score 事件摄取(批量 JSON 与 OpenTelemetry 两种入口)、trace / session / user / score 查询、指标查询、执行日志关联与项目摄取状态。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope 划分到子能力:observability.ingest.write(摄取)、observability.traces.read、observability.sessions.read、observability.users.read、observability.scores.read、observability.metrics.read、observability.status.read、traceLogs.read(执行日志)。

端点清单

方法 + 路径用途
POST /observability/ingestion批量摄取 trace/observation/score 事件
POST /observability/otel/v1/tracesOpenTelemetry traces 摄取
GET /observability/traces / GET .../traces/{traceId}trace 列表/详情
GET /observability/sessions / GET .../sessions/{sessionId}会话列表/详情
GET /observability/users / GET .../users/{userId}用户列表/详情
GET /observability/scores / GET .../score-configs评分列表/配置
POST /observability/evals/mcp/tools发现评估用只读 MCP 工具(2.8.0)
POST /observability/metrics指标查询
GET /observability/logs按 trace/execution 取执行输出日志
GET /observability项目摄取状态

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

摄取

POST /v1/observability/ingestion

批量摄取 trace / observation / score 事件(Langfuse 事件模型):单批 1–100 个事件,全部受理返回 200,任一事件被拒返回 207 逐事件报告。

输入:

参数位置类型必填默认/枚举说明
batchbodyobject[]是—事件数组(1–100 个),元素结构见 batch[] 子字段行(事件模型与 Langfuse 摄取契约对齐;spec 以 object[] 泛化暴露)。
metadatabodyobject否—整批摄取元数据(如 sdk、sdkVersion),可选。
batch[].idbodystring是—事件幂等 ID(如 UUID);每个 create / update 事件用新的唯一值,重试时复用原 id 保证幂等。
batch[].typebodystring是枚举见说明事件类型:trace-create;span-create / span-update;generation-create / generation-update;score-create;另支持 event-create、agent-create、tool-create、chain-create、retriever-create、evaluator-create、embedding-create、guardrail-create(兼容别名 observation-create / observation-update 不建议新代码使用)。
batch[].timestampbodystring是—事件时间,带时区的 ISO 8601 字符串。
batch[].bodybodyobject是—实体字段对象,字段随事件类型而定,见下。
batch[].body.idbodystring是—实体 ID:trace 用非全零 32 位小写十六进制、observation 用 16 位小写十六进制,可复用为 W3C traceparent;更新同一实体时保持不变。
batch[].body.namebodystring否—实体名称(如 support-agent.run、llm.answer)。
batch[].body.timestampbodystring否—实体发生时间(ISO 8601)。
batch[].body.traceIdbodystringobservation 必填—所属根 Trace 的 body.id;子 Observation 另用 parentObservationId 指向父 Observation。
batch[].body.userId / sessionIdbodystring否—归属用户与会话:userId 聚合出 users 视图,sessionId 聚合出 sessions 视图。
batch[].body.environment / release / tagsbodystring / string[]否—部署语境:environment 仅小写字母、数字、-、_(≤40 字符),release 版本串,tags 标签数组。
batch[].body.input / outputbodyany否—输入 / 输出载荷(建议脱敏后上报)。
batch[].body.startTime / endTimebodystringobservation 常用—Observation 起止时间(ISO 8601)。
batch[].body.parentObservationIdbodystring否—父 Observation 的 body.id(构成 span 树)。
batch[].body.level / statusMessagebodystring否枚举 DEBUG, DEFAULT, WARNING, ERRORObservation 级别与状态消息。
batch[].body.model / modelParameters / completionStartTimebodystring / object否—generation 专用:模型 ID、模型参数与补全开始时间。
batch[].body.usage / usageDetails / costDetailsbodyobject否—generation 专用:token 用量(如 {input: 120, output: 48, total: 168, unit: "TOKENS"})与成本明细。
batch[].body.value / dataTypebodynumber / stringscore 必填—score 专用:分数值与数据类型(NUMERIC / CATEGORICAL);目标用 traceId / observationId / sessionId 之一指定。
batch[].metadatabodyobject否—事件级元数据。

输出:返回逐事件受理结果:successes[](受理事件)与 errors[](被拒事件);全部通过为 200,任一失败为 207 Multi-Status。

字段类型说明
successesobject[]受理事件:id(事件外层 ID)+ status(201)
errorsobject[]被拒事件:id + status(HTTP 语义码)+ message(拒绝原因)

调用示例:

curl -X POST "https://<your-endpoint>/v1/observability/ingestion" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "id": "evt-0f3a2b71-create",
        "type": "trace-create",
        "timestamp": "2026-09-14T02:30:00.000Z",
        "body": {
          "id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
          "timestamp": "2026-09-14T02:30:00.000Z",
          "name": "support-agent.run",
          "userId": "user_42",
          "sessionId": "session-20260914-001",
          "environment": "production",
          "release": "2026.09.14",
          "tags": ["agent", "support"],
          "input": { "question": "订单 20260914 号何时发货?" }
        }
      },
      {
        "id": "evt-0f3a2b72-gen",
        "type": "generation-create",
        "timestamp": "2026-09-14T02:30:01.200Z",
        "body": {
          "id": "a1b2c3d4e5f60718",
          "traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
          "name": "llm.answer",
          "startTime": "2026-09-14T02:30:01.000Z",
          "model": "gpt-4o-mini",
          "modelParameters": { "temperature": 0.7 },
          "input": { "messages": 3 }
        }
      },
      {
        "id": "evt-0f3a2b73-genupd",
        "type": "generation-update",
        "timestamp": "2026-09-14T02:30:03.900Z",
        "body": {
          "id": "a1b2c3d4e5f60718",
          "traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
          "endTime": "2026-09-14T02:30:03.800Z",
          "output": { "answerChars": 186 },
          "usage": { "input": 412, "output": 96, "total": 508, "unit": "TOKENS" }
        }
      },
      {
        "id": "evt-0f3a2b74-score",
        "type": "score-create",
        "timestamp": "2026-09-14T02:30:04.500Z",
        "body": {
          "id": "score-0001",
          "traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
          "name": "user-feedback",
          "value": 0.9,
          "dataType": "NUMERIC"
        }
      }
    ],
    "metadata": { "sdk": "custom-agent", "sdkVersion": "1.0.0" }
  }'

响应示例:

{
  "successes": [
    {
      "id": "evt-0f3a2b71-create",
      "status": 201
    },
    {
      "id": "evt-0f3a2b72-gen",
      "status": 201
    },
    {
      "id": "evt-0f3a2b73-genupd",
      "status": 201
    }
  ],
  "errors": [
    {
      "id": "evt-0f3a2b74-score",
      "status": 400,
      "message": "Invalid request data"
    }
  ]
}

POST /v1/observability/otel/v1/traces

以 OpenTelemetry 标准格式摄取 traces:接受 OTLP HTTP JSON 或 protobuf(可 gzip),按 gen_ai 语义约定映射为平台 trace / observation 模型。

输入:无 path/query/body 参数。

输出:返回 200(OTLP 标准受理响应)。请求约束:Content-Type: application/json 或 application/x-protobuf;可选 Content-Encoding: gzip;原始与解压后请求体均须非空且不超过 4,718,592 字节(4.5 MiB)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/observability/otel/v1/traces" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  --data-binary @otlp-traces.json
# otlp-traces.json 为标准 OTLP ExportTraceServiceRequest JSON 文档(resourceSpores → scopeSpans → spans)

响应示例:200:响应为 OTLP 标准受理确认(partialSuccess 语义),此处不展开字段。

POST /v1/observability/evals/mcp/tools(2.8.0)

发现评估可用的只读 MCP 工具:评估任务为评估器挂接 MCP 工具前,用受限网关凭据列出该 AI Gateway 上无副作用的 MCP 工具清单(2.8.0 新增)。

输入:

参数位置类型必填默认/枚举说明
gatewayIdbodystring是—AI Gateway 的网关 ID。
gatewayKeyIdbodystring是—受限 Gateway Key(子密钥)ID:需为绑定该网关的活跃凭据,显式圈定工具且不含模型 / Agent 权限。

输出:返回 200 + 工具清单 tools[](泛化 schema any:每个工具含 toolId / revisionId / targetRevisionId / name / inputSchemaHash 等字段,具体以实际响应为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/observability/evals/mcp/tools" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "gatewayId": "<GATEWAY_ID>",
    "gatewayKeyId": "<GATEWAY_KEY_ID>"
  }'

响应示例:200:响应为工具清单 JSON(泛化 schema any,具体字段以实际响应为准)。

查询

GET /v1/observability/traces

分页查询项目内 trace 列表:支持时间窗、名称精确匹配、ID/名称模糊搜索、标签与用户过滤。

输入:

参数位置类型必填默认/枚举说明
limitqueryinteger否默认 25单页最大条数,默认 25。
offsetqueryinteger否默认 0翻页偏移,默认 0。
fromquerystring否默认 ""时间范围起点(ISO 8601 时间字符串)。
toquerystring否默认 ""时间范围终点。
namequerystring否默认 ""按 trace 名称精确过滤。
searchquerystring否默认 ""对 trace ID 或名称做模糊匹配。
tagquerystring否默认 ""按标签过滤。
userIdquerystring否默认 ""按归属用户 ID 精确过滤。

输出:返回 trace 列表(泛化 schema any)。元素为 Langfuse 兼容 trace 对象:id、timestamp、name、userId、sessionId、environment、release、tags 等(与摄取 trace-create 的 body 字段一致)。

调用示例:

curl "https://<your-endpoint>/v1/observability/traces?limit=2&from=2026-09-14T00:00:00Z&to=2026-09-15T00:00:00Z&userId=user_42" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为 trace 列表 JSON(泛化 schema;元素字段与 Langfuse trace 模型一致):

{
  "data": [
    {
      "id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
      "timestamp": "2026-09-14T02:30:00.000Z",
      "name": "support-agent.run",
      "userId": "user_42",
      "sessionId": "session-20260914-001",
      "environment": "production",
      "release": "2026.09.14",
      "tags": ["agent", "support"]
    }
  ]
}

GET /v1/observability/traces/{traceId}

读取单个 trace 及其完整 observation 树:定位一次 Agent / RAG / LLM 调用的全链路细节。

输入:

参数位置类型必填默认/枚举说明
traceIdpathstring是—Trace ID,最长 128 字符;与摄取时 body.id 一致。

输出:返回完整 trace(泛化 schema any):根 trace 字段加 observations[] 树(每项含 id、traceId、parentObservationId、type(span / generation 等)、startTime / endTime、model、usage、level)。

调用示例:

curl "https://<your-endpoint>/v1/observability/traces/5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为 trace + observation 树 JSON(泛化 schema;字段与 Langfuse trace / observation 模型一致):

{
  "id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
  "name": "support-agent.run",
  "timestamp": "2026-09-14T02:30:00.000Z",
  "observations": [
    {
      "id": "a1b2c3d4e5f60718",
      "traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
      "type": "GENERATION",
      "name": "llm.answer",
      "startTime": "2026-09-14T02:30:01.000Z",
      "endTime": "2026-09-14T02:30:03.800Z",
      "model": "gpt-4o-mini",
      "level": "DEFAULT",
      "usage": { "input": 412, "output": 96, "total": 508, "unit": "TOKENS" }
    }
  ]
}

GET /v1/observability/sessions

分页查询会话列表:会话由 trace 的 sessionId 聚合而成,用于按对话轮次观测。

输入:

参数位置类型必填默认/枚举说明
limitqueryinteger否默认 25单页最大条数,默认 25。
offsetqueryinteger否默认 0翻页偏移。
fromquerystring否默认 ""会话时间范围起点。
toquerystring否默认 ""会话时间范围终点。

输出:返回 session 列表(泛化 schema any:每项含会话 ID、时间范围与关联 trace 数,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/observability/sessions?limit=25&from=2026-09-14T00:00:00Z&to=2026-09-15T00:00:00Z" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为 session 列表 JSON(泛化 schema,字段以实际响应为准)。

GET /v1/observability/sessions/{sessionId}

读取单个会话及其包含的 trace 列表。

输入:

参数位置类型必填默认/枚举说明
sessionIdpathstring是—会话 ID,最长 128 字符;即摄取时 trace body.sessionId。

输出:返回 session 详情 + 关联 traces(泛化 schema any,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/observability/sessions/session-20260914-001" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为 session 详情 JSON(泛化 schema,字段以实际响应为准)。

GET /v1/observability/users

分页查询按 trace 归属聚合出的用户列表:支持按用户 ID 模糊搜索。

输入:

参数位置类型必填默认/枚举说明
limitqueryinteger否默认 25单页最大条数,默认 25。
offsetqueryinteger否默认 0翻页偏移。
searchquerystring否默认 ""按用户 ID 模糊搜索。
fromquerystring否默认 ""按 trace 时间窗过滤的起点。
toquerystring否默认 ""按 trace 时间窗过滤的终点。

输出:返回 user 聚合列表(泛化 schema any:每项含用户 ID 与 trace 聚合信息,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/observability/users?limit=25&search=user_4" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为 user 列表 JSON(泛化 schema,字段以实际响应为准)。

GET /v1/observability/users/{userId}

读取单个用户的 trace 派生指标(调用次数、token 用量等聚合)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是—用户 ID,即 trace body.userId。

输出:返回该用户的 trace 派生指标(泛化 schema any,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/observability/users/user_42" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为用户聚合指标 JSON(泛化 schema,字段以实际响应为准)。

GET /v1/observability/scores

分页查询评分记录:支持评估任务、分数带、评估器、来源、数据类型过滤与归一化数值比较。

输入:

参数位置类型必填默认/枚举说明
limitqueryinteger否默认 25单页最大条数,默认 25。
offsetqueryinteger否默认 0翻页偏移。
fromquerystring否默认 ""评分时间范围起点。
toquerystring否默认 ""评分时间范围终点。
evaluationTasksquerystring[]否默认 []按评估任务名过滤(数组,取并集)。
scoreBandsquerystring[]否默认 []按归一化分数带过滤(如 low / medium / high)。
evaluatorsquerystring[]否默认 []按评估器名称过滤。
sourcesquerystring[]否默认 []按评分来源过滤。
dataTypesquerystring[]否默认 []按分数数据类型过滤(NUMERIC / CATEGORICAL 等)。
valueFiltersqueryobject[]否默认 []归一化数值比较数组,多个条件 AND 组合。
valueFilterExpressionqueryobject否默认 {}有界布尔表达式对象,对归一化数值分数求值;与 valueFilters 二选一语境使用。

输出:返回 score 列表(泛化 schema any;元素字段与摄取 score-create 的 body 一致:id、name、value、dataType、traceId / observationId / sessionId)。

调用示例:

curl "https://<your-endpoint>/v1/observability/scores?limit=25&dataTypes=NUMERIC" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为 score 列表 JSON(泛化 schema;字段与 Langfuse score 模型一致):

{
  "data": [
    {
      "id": "score-0001",
      "name": "user-feedback",
      "value": 0.9,
      "dataType": "NUMERIC",
      "traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f"
    }
  ]
}

GET /v1/observability/score-configs

列出项目内生效的评分配置(评分名称、类型与取值域定义)。

输入:

参数位置类型必填默认/枚举说明
limitqueryinteger否默认 100单页最大条数,默认 100。
offsetqueryinteger否默认 0翻页偏移。

输出:返回评分配置列表(泛化 schema any,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/observability/score-configs?limit=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为评分配置列表 JSON(泛化 schema,字段以实际响应为准)。

POST /v1/observability/metrics

基于 trace / observation / score 数据做聚合指标查询(Langfuse metrics query 语义),返回聚合序列。

输入:

参数位置类型必填默认/枚举说明
querybodyobject是—Langfuse metrics query 对象:时间窗(from/to)、度量(metrics[]:measure + aggregation)、维度(dimensions[])与 filters[]。具体字段以 Langfuse metrics query 契约为准。

输出:返回聚合指标序列(泛化 schema any,字段以实际响应为准)。注意:本端点面向观测领域聚合,不是通用基础设施指标数据库。

调用示例:

curl -X POST "https://<your-endpoint>/v1/observability/metrics" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "from": "2026-09-07T00:00:00Z",
      "to": "2026-09-14T00:00:00Z",
      "metrics": [
        { "measure": "cost", "aggregation": "sum" }
      ],
      "dimensions": [
        { "field": "metricsName" }
      ]
    }
  }'

响应示例:响应为聚合指标 JSON(泛化 schema,字段以实际响应为准)。

GET /v1/observability/logs

按 W3C trace 或执行 ID 查询 Function / 动态 Site 执行产生的业务输出日志:把观测 trace 与执行输出关联起来。

输入:

参数位置类型必填默认/枚举说明
queryquerystring是—白名单 key:value 选择器,键仅支持 traceId / executionId / siteExecutionId(如 traceId:5f0c3a9e...);其他键或值格式非法返回参数错误。
fromqueryinteger否默认 0查询起点(Unix 秒),默认一小时前。
toqueryinteger否默认 0查询终点(Unix 秒),默认现在。
limitqueryinteger否默认 25最大返回条数,默认 25,上限 100。
offsetqueryinteger否默认 0翻页偏移,上限 1000。

输出:返回 traceLogList:

字段类型说明
logsobject[]日志项数组,字段见下
logs[].timestampstring日志时间
logs[].levelstring日志级别
logs[].messagestring已脱敏的日志内容
logs[].sourcestring执行来源:function / site
logs[].function_idstringFunction ID(来源为 function 时)
logs[].site_idstringSite ID(来源为 site 时)
logs[].execution_idstring执行 ID
logs[].deployment_idstring部署 ID
logs[].triggerstring执行触发方式
logs[].streamstring输出流(stdout / stderr)
logs[].chunk_indexinteger输出分块序号
logs[].chunk_countinteger输出分块总数
logs[].trace_idstring关联的 W3C trace ID
completeboolean日志提供方是否已完成本次查询

调用示例:

curl "https://<your-endpoint>/v1/observability/logs?query=traceId:5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f&limit=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "logs": [
    {
      "timestamp": "2026-09-14T02:30:01.120Z",
      "level": "INFO",
      "message": "llm.answer start",
      "source": "function",
      "function_id": "fn-support-agent",
      "execution_id": "exec-01J5Z8W9",
      "deployment_id": "dep-63a1",
      "trigger": "https",
      "stream": "stdout",
      "chunk_index": 0,
      "chunk_count": 2,
      "trace_id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f"
    },
    {
      "timestamp": "2026-09-14T02:30:03.910Z",
      "level": "INFO",
      "message": "llm.answer done tokens=508",
      "source": "function",
      "function_id": "fn-support-agent",
      "execution_id": "exec-01J5Z8W9",
      "deployment_id": "dep-63a1",
      "trigger": "https",
      "stream": "stdout",
      "chunk_index": 1,
      "chunk_count": 2,
      "trace_id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f"
    }
  ],
  "complete": true
}

GET /v1/observability

读取当前项目的可观测性状态:初始化状态、摄取入口与容量态,写入前可用它探测可用性。

输入:无 path/query/body 参数。

输出:返回项目摄取状态(泛化 schema any:含启用状态与 ingestionEndpoints 等容量信息,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/observability" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为项目状态 JSON(泛化 schema,字段以实际响应为准;含 ingestionEndpoints)。

错误与边界

与 Server SDK 的对应

service.method端点
Observability.createIngestion / createOtelTracesPOST /observability/ingestion、POST /observability/otel/v1/traces
Observability.listTraces / getTrace / listSessions / getSession / listUsers / getUsertrace / session / user 查询
Observability.listScores / listScoreConfigs / queryMetricsGET .../scores、.../score-configs、POST .../metrics
Observability.listLogsGET /observability/logs
Observability.getStatusGET /observability
Observability.discoverEvalMcpToolsPOST /observability/evals/mcp/tools(2.8.0)

事实源