可观测性 API
LLM 应用可观测性数据面(兼容 Langfuse 语义):trace / observation / score 事件摄取(批量 JSON 与 OpenTelemetry 两种入口)、trace / session / user / score 查询、指标查询、执行日志关联与项目摄取状态。
服务与资源边界
可观测性 API(/v1/observability/*)提供兼容 OpenTelemetry(OTLP)与 Langfuse 数据模型的全链路 GenAI 可观测与质量评估服务:覆盖 Trace / Observation(Span / Generation / Tool / Retriever / Guardrail)/ Score 批量与流式摄取、多维链路与会话检索、Token 与时延聚合指标查询、评分根因分析(Analysis)、评估 Prompt 版本解析以及知识索引质量评估任务编排。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/observability。数据层级:
session→trace({traceId})→ observation(span/generation 事件);score挂在 trace/observation 上;user({userId})按 trace 归属聚合。摄取入口两个:
POST /observability/ingestion(平台批量 JSON)与POST /observability/otel/v1/traces(OpenTelemetry HTTP JSON / protobuf)。
认证与权限
认证与请求头约定见 通用约定。本域 scope 划分到子能力:observability.ingest.write(摄取)、observability.traces.read、observability.sessions.read、observability.users.read、observability.scores.read、observability.metrics.read、observability.status.read、traceLogs.read(执行日志)。
端点总览
Observability 模块共提供 23 个端点,分为五大能力域:双通道事件摄取(/ingestion 与 /otel/v1/traces)、链路与实体检索(/traces*、/observations、/sessions*、/users*、/logs)、评分与根因洞察(/scores*、/score-configs)、知识索引与 MCP 评估(/evals/*、/prompts/resolve)以及多维指标聚合与状态查询(/metrics、/observability)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
POST /observability/ingestion | 批量摄取 trace/observation/score 事件 |
POST /observability/otel/v1/traces | OpenTelemetry traces 摄取 |
GET /observability/traces / GET .../traces/{traceId} | trace 列表/详情 |
GET /observability/sessions / GET .../sessions/{sessionId} | 会话列表/详情 |
GET /observability/users / GET .../users/{userId} | 用户列表/详情 |
GET /observability/scores(2.9.0 +scoreId 参数)/ GET .../score-configs | 评分列表/配置 |
GET /observability/observations | Observation 列表(2.9.0 新增:名称/类型/时间/级别/traceId/environment 过滤) |
GET .../scores/{scoreId}/analysis · GET .../scores/{scoreId}/quality-details | 评分根因分析详情 / 解析评估逐页逐块明细(2.9.0 新增);2.10.0 起 kind 枚举扩展 index(知识索引质量逐记录明细) |
POST .../scores/analysis/summaries · POST .../scores/analysis/trigger | 分析洞察摘要 / 批量触发(单批 ≤100,2.9.0 新增) |
POST /observability/evals/index-preview · POST /observability/evals/index | 知识索引质量评估:预览各类预计评估记录数 / 创建评估任务(2.10.0 新增,scope observability.evals.read / observability.evals.write) |
GET /observability/prompts/resolve | 按名称 + label(默认 production)或精确版本解析评估 Prompt,label 与 version 互斥(2.10.0 新增,scope observability.prompts.read) |
POST /observability/evals/mcp/tools | 发现评估用只读 MCP 工具(2.8.0) |
POST /observability/metrics | 指标查询 |
GET /observability/logs | 按 trace/execution 取执行输出日志 |
GET /observability | 项目摄取状态 |
端点详解
W3C Trace Context 规范与标识格式:
/observability/otel/v1/traces遵循 W3C 标准,要求traceId为非全零的 32 位小写十六进制字符串、spanId为非全零的 16 位小写十六进制字符串;/observability/ingestion亦推荐使用相同格式以便跨服务透传traceparent(Events 入口本身支持常规非空实体 ID,不强制限制为十六进制)。Observation 的结束时间应不早于开始时间。部分成功多状态响应(
207 Multi-Status):批量摄取接口按单条事件独立校验并异步入库,若批次中存在格式不合法事件,返回207并在响应体中分别列出成功与失败事件的id及原因。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
摄取
POST /v1/observability/ingestion
批量摄取 trace / observation / score 事件(Langfuse 事件模型):单批 1–100 个事件,全部受理返回 200,任一事件被拒返回 207 逐事件报告。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
batch | body | object[] | 是 | — | 事件数组(1–100 个),元素结构见 batch[] 子字段行(事件模型与 Langfuse 摄取契约对齐;spec 以 object[] 泛化暴露)。 |
metadata | body | object | 否 | — | 整批摄取元数据(如 sdk、sdkVersion),可选。 |
batch[].id | body | string | 是 | — | 事件幂等 ID(如 UUID);每个 create / update 事件用新的唯一值,重试时复用原 id 保证幂等。 |
batch[].type | body | string | 是 | 枚举见说明 | 事件类型: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[].timestamp | body | string | 是 | — | 事件时间,带时区的 ISO 8601 字符串。 |
batch[].body | body | object | 是 | — | 实体字段对象,字段随事件类型而定,见下。 |
batch[].body.id | body | string | 是 | — | 实体 ID:推荐 trace 用非全零 32 位小写十六进制、observation 用非全零 16 位小写十六进制,以便复用为 W3C traceparent;更新同一实体时保持不变。 |
batch[].body.name | body | string | 否 | — | 实体名称(如 support-agent.run、llm.answer)。 |
batch[].body.timestamp | body | string | 否 | — | 实体发生时间(ISO 8601)。 |
batch[].body.traceId | body | string | observation 必填 | — | 所属根 Trace 的 body.id;子 Observation 另用 parentObservationId 指向父 Observation。 |
batch[].body.userId / sessionId | body | string | 否 | — | 归属用户与会话:userId 聚合出 users 视图,sessionId 聚合出 sessions 视图。 |
batch[].body.environment / release / tags | body | string / string[] | 否 | — | 部署语境:environment 仅小写字母、数字、-、_(≤40 字符),release 版本串,tags 标签数组。 |
batch[].body.input / output | body | any | 否 | — | 输入 / 输出载荷(建议脱敏后上报)。 |
batch[].body.startTime / endTime | body | string | observation 常用 | — | Observation 起止时间(ISO 8601)。 |
batch[].body.parentObservationId | body | string | 否 | — | 父 Observation 的 body.id(构成 span 树)。 |
batch[].body.level / statusMessage | body | string | 否 | 枚举 DEBUG, DEFAULT, WARNING, ERROR | Observation 级别与状态消息。 |
batch[].body.model / modelParameters / completionStartTime | body | string / object | 否 | — | generation 专用:模型 ID、模型参数与补全开始时间。 |
batch[].body.usage / usageDetails / costDetails | body | object | 否 | — | generation 专用:token 用量(如 {input: 120, output: 48, total: 168, unit: "TOKENS"})与成本明细。 |
batch[].body.value / dataType | body | number / string | score 必填 | — | score 专用:分数值与数据类型(NUMERIC / CATEGORICAL);目标用 traceId / observationId / sessionId 之一指定。 |
batch[].metadata | body | object | 否 | — | 事件级元数据。 |
输出:返回逐事件受理结果:successes[](受理事件)与 errors[](被拒事件);全部通过为 200,任一失败为 207 Multi-Status。
| 字段 | 类型 | 说明 |
|---|---|---|
successes | object[] | 受理事件:id(事件外层 ID)+ status(201) |
errors | object[] | 被拒事件:id + status(HTTP 语义码)+ message(拒绝原因) |
id指事件幂等 ID;body.id指实体 ID:更新同一 trace / observation / score 时保持body.id不变。推荐 trace 用非全零 32 位小写十六进制、observation 用 16 位小写十六进制,便于同一组 ID 复用为 W3C
traceparent。200/207表示已被摄取入口受理,异步 worker 完成持久化前 readback 可能 404,可用短轮询等待。网络错误、
429与可恢复5xx可用有上限的指数退避并复用外层id;schema / 权限类4xx不要盲目重试。
调用示例:
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 参数;请求体是原始 ExportTraceServiceRequest JSON 或 protobuf,JSON 使用 resourceSpans → scopeSpans → spans 结构,不额外包裹 Agentbase 字段。
输出:返回 200,响应为转换后事件的 successes / errors 批次结果。请求约束:Content-Type: application/json 或 application/x-protobuf;可选 Content-Encoding: gzip;原始与解压后请求体均须非空且不超过 4,718,592 字节(4.5 MiB)。
配置 OTel exporter 时直接把本端点作为 traces 专用 endpoint(
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT),避免 exporter 再自动追加/v1/traces。本端点不是 OTLP gRPC endpoint;认证仍用项目双头(
X-Appwrite-Project+X-Appwrite-Key)。直接 HTTP 调用时 OTLP JSON / protobuf 原样作为 body,不要再包一层 JSON。
调用示例:
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 文档(resourceSpans → scopeSpans → spans)最小 OTLP JSON(保存为 otlp-traces.json;以下 ID 为示例,真实调用应生成自己的非全零 Trace/Span ID):
{
"resourceSpans": [{
"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "example-agent"}}]},
"scopeSpans": [{
"scope": {"name": "example-instrumentation"},
"spans": [{
"traceId": "0123456789abcdef0123456789abcdef",
"spanId": "0123456789abcdef",
"name": "agent.run",
"kind": 1,
"startTimeUnixNano": "1788836400000000000",
"endTimeUnixNano": "1788836401000000000",
"status": {"code": 1}
}]
}]
}]
}响应示例:
{
"successes": [{"id": "converted-event-id", "status": 201}],
"errors": []
}OTLP 在本版本由 HTTP action 转发内部转换结果,HTTP 200 也必须检查 errors[],不能按标准 partialSuccess 响应解析。Events 入口则在单项失败时返回 207。受理不代表异步入库完成,使用有 observability.traces.read 的读取凭据回查同一 Trace ID;不要把标准 exporter 的无报错当作完整持久化证据。
POST /v1/observability/evals/mcp/tools(2.8.0)
发现评估可用的只读 MCP 工具:评估任务为评估器挂接 MCP 工具前,用受限网关凭据列出该 AI Gateway 上无副作用的 MCP 工具清单(2.8.0 新增)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
gatewayId | body | string | 是 | — | AI Gateway 的网关 ID。 |
gatewayKeyId | body | string | 是 | — | 受限 Gateway Key(子密钥)ID:需为绑定该网关的活跃凭据,显式圈定工具且不含模型 / Agent 权限。 |
输出:返回 200 + 工具清单 tools[](泛化 schema any:每个工具含 toolId / revisionId / targetRevisionId / name / inputSchemaHash 等字段,具体以实际响应为准)。
只返回只读(无副作用、审批模式为放行且副作用级别为读)的服务端工具;配置评估时从该清单中圈定工具。
scope 为
observability.evals.write;gatewayKeyId对应的凭据不回传任何明文。
调用示例:
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/名称模糊搜索、标签与用户过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 25 | 单页最大条数,默认 25。 |
offset | query | integer | 否 | 默认 0 | 翻页偏移,默认 0。 |
from | query | string | 否 | 默认 "" | 时间范围起点(ISO 8601 时间字符串)。 |
to | query | string | 否 | 默认 "" | 时间范围终点。 |
name | query | string | 否 | 默认 "" | 按 trace 名称精确过滤。 |
search | query | string | 否 | 默认 "" | 对 trace ID 或名称做模糊匹配。 |
tag | query | string | 否 | 默认 "" | 按标签过滤。 |
userId | query | string | 否 | 默认 "" | 按归属用户 ID 精确过滤。 |
输出:返回 trace 列表(泛化 schema any)。元素为 Langfuse 兼容 trace 对象:id、timestamp、name、userId、sessionId、environment、release、tags 等(与摄取 trace-create 的 body 字段一致)。
深翻页时建议用
from/to收窄时间窗,而不是持续加大offset。
调用示例:
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 列表及持久化 trajectory:定位一次 Agent / RAG / LLM 调用的全链路细节。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
traceId | path | string | 是 | — | Trace ID,最长 128 字符;与摄取时 body.id 一致。 |
输出:返回顶层 { trace, observations, trajectory }(泛化 schema any)。trace 是根实体,observations[] 是平铺观测列表,每项包含 id、traceId、parentObservationId、type、name、startTime、endTime、model、level、usage 等字段,由 Console 按父子关系构建树;trajectory 是当前持久化 ATIF,不存在、分批上报尚未完结或异步轨迹尚未就绪时为 null。
摄取后立即查询若 404,先短轮询等待异步 worker 持久化完成。
调用示例:
curl "https://<your-endpoint>/v1/observability/traces/5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例(轨迹尚未就绪时):
{
"trace": {
"id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"name": "support-agent.run",
"timestamp": "2026-09-14T02:30:00.000Z"
},
"observations": [
{
"id": "0123456789abcdef",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"parentObservationId": null,
"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 },
"input": {
"messages": [
{
"role": "user",
"content": "订单何时发货?"
}
]
},
"output": {
"role": "assistant",
"content": "请提供订单号。"
}
}
],
"trajectory": null
}GET /v1/observability/sessions
分页查询会话列表:会话由 trace 的 sessionId 聚合而成,用于按对话轮次观测。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 25 | 单页最大条数,默认 25。 |
offset | query | integer | 否 | 默认 0 | 翻页偏移。 |
from | query | string | 否 | 默认 "" | 会话时间范围起点。 |
to | query | string | 否 | 默认 "" | 会话时间范围终点。 |
输出:返回 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 列表。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
sessionId | path | string | 是 | — | 会话 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 模糊搜索。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 25 | 单页最大条数,默认 25。 |
offset | query | integer | 否 | 默认 0 | 翻页偏移。 |
search | query | string | 否 | 默认 "" | 按用户 ID 模糊搜索。 |
from | query | string | 否 | 默认 "" | 按 trace 时间窗过滤的起点。 |
to | query | string | 否 | 默认 "" | 按 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 用量等聚合)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | — | 用户 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
分页查询评分记录:支持评估任务、分数带、评估器、来源、数据类型过滤与归一化数值比较。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 25 | 单页最大条数,默认 25。 |
offset | query | integer | 否 | 默认 0 | 翻页偏移。 |
from | query | string | 否 | 默认 "" | 评分时间范围起点。 |
to | query | string | 否 | 默认 "" | 评分时间范围终点。 |
evaluationTasks | query | string[] | 否 | 默认 [] | 按评估任务名过滤(数组,取并集)。 |
scoreBands | query | string[] | 否 | 默认 [] | 按归一化分数带过滤(如 low / medium / high)。 |
evaluators | query | string[] | 否 | 默认 [] | 按评估器名称过滤。 |
sources | query | string[] | 否 | 默认 [] | 按评分来源过滤。 |
dataTypes | query | string[] | 否 | 默认 [] | 按分数数据类型过滤(NUMERIC / CATEGORICAL 等)。 |
valueFilters | query | object[] | 否 | 默认 [] | 归一化数值比较数组,多个条件 AND 组合。 |
valueFilterExpression | query | object | 否 | 默认 {} | 有界布尔表达式对象,对归一化数值分数求值;与 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
列出项目内生效的评分配置(评分名称、类型与取值域定义)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 100 | 单页最大条数,默认 100。 |
offset | query | integer | 否 | 默认 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 语义),返回聚合序列。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | body | object | 是 | — | 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 与执行输出关联起来。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
query | query | string | 是 | — | 白名单 key:value 选择器,键仅支持 traceId / executionId / siteExecutionId(如 traceId:5f0c3a9e...);其他键或值格式非法返回参数错误。 |
from | query | integer | 否 | 默认 0 | 查询起点(Unix 秒),默认一小时前。 |
to | query | integer | 否 | 默认 0 | 查询终点(Unix 秒),默认现在。 |
limit | query | integer | 否 | 默认 25 | 最大返回条数,默认 25,上限 100。 |
offset | query | integer | 否 | 默认 0 | 翻页偏移,上限 1000。 |
输出:返回 traceLogList:
| 字段 | 类型 | 说明 |
|---|---|---|
logs | object[] | 日志项数组,字段见下 |
logs[].timestamp | string | 日志时间 |
logs[].level | string | 日志级别 |
logs[].message | string | 日志内容;仅对有限模式处理并截断,不保证识别所有敏感信息 |
logs[].source | string | 执行来源:function / site |
logs[].function_id | string | Function ID(来源为 function 时) |
logs[].site_id | string | Site ID(来源为 site 时) |
logs[].execution_id | string | 执行 ID |
logs[].deployment_id | string | 部署 ID |
logs[].trigger | string | 执行触发方式 |
logs[].stream | string | 输出流(stdout / stderr) |
logs[].chunk_index | integer | 输出分块序号 |
logs[].chunk_count | integer | 输出分块总数 |
logs[].trace_id | string | 关联的 W3C trace ID |
complete | boolean | 日志提供方是否已完成本次查询 |
scope 为
traceLogs.read,与 Langfuse 数据面的observability.*scope 相互独立。不接受 SLS 查询语句或日志提供方配置参数;时间范围与
limit/offset超界会被截断。
调用示例:
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 等容量信息,字段以实际响应为准)。
探测 scope 为
observability.status.read(旧 Key 兼容projects.read);状态探测失败不等于写入 Key 无效。
调用示例:
curl "https://<your-endpoint>/v1/observability" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:响应为项目状态 JSON(泛化 schema,字段以实际响应为准;含 ingestionEndpoints)。
观测列表与评分分析(2.9.0)
GET /v1/observability/observations
跨 Trace 查询 Observation;名称、级别、traceId 和环境使用精确匹配。
scope:observability.traces.read;Server SDK:Observability.listObservations。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 25 | 单页最大返回数量,取值 1–100。 |
offset | query | integer | 否 | 0 | 分页跳过的记录数(偏移量),取值 0–999900,且必须为 limit 的整数倍。 |
from | query | string | 否 | "" | 观测时间范围起点。 |
to | query | string | 否 | "" | 观测时间范围终点。 |
type | query | string | 否 | "" | 逗号分隔的观测类型。 |
name | query | string | 否 | "" | 观测名称,精确匹配。 |
level | query | string | 否 | "" | 观测级别,精确匹配。 |
traceId | query | string | 否 | "" | 父 Trace ID,精确匹配。 |
environment | query | string | 否 | "" | 环境,精确匹配。 |
输出:200,模型 observabilityObservationList。
| 字段 | 类型 | 说明 |
|---|---|---|
total | integer | 当前筛选条件下的观测总数。 |
observations | object[] | 本页观测,模型 observabilityObservation。 |
调用示例:
curl --get "https://<your-endpoint>/v1/observability/observations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/observability/scores/{scoreId}/analysis
读取指定评分的根因分析结果。
scope:observability.scores.read;Server SDK:Observability.getScoreAnalysis。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scoreId | path | string | 是 | — | 评分 ID。 |
输出:200,JSON 对象(schema any)。
调用示例:
curl --get "https://<your-endpoint>/v1/observability/scores/<SCORE_ID>/analysis" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/observability/scores/{scoreId}/quality-details
读取指定评分的解析或分块质量明细。
scope:observability.scores.read;Server SDK:Observability.getScoreQualityDetails。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scoreId | path | string | 是 | — | 评分 ID。 |
kind | query | string | 是 | parsing / chunking | 解析或分块明细类型。 |
limit | query | integer | 否 | 25 | 最大返回数量。 |
offset | query | integer | 否 | 0 | 跳过的记录数。 |
输出:200,JSON 对象(schema any)。
调用示例:
curl --get "https://<your-endpoint>/v1/observability/scores/<SCORE_ID>/quality-details" \
--data-urlencode "kind=parsing" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/observability/scores/analysis/summaries
批量读取评分分析摘要。
scope:observability.scores.read;Server SDK:Observability.listScoreAnalysisSummaries。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scoreIds | body | string[] | 是 | — | 1–100 个评分 ID,重复 ID 自动去重。 |
输出:200,JSON 对象(schema any)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/observability/scores/analysis/summaries" \
-H "Content-Type: application/json" \
-d '{"scoreIds":["<SCORE_ID>"]}' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/observability/scores/analysis/trigger
批量安排评分分析任务。
scope:observability.scores.read;Server SDK:Observability.triggerScoreAnalyses。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
scoreIds | body | string[] | 是 | — | 1–100 个评分 ID,重复 ID 自动去重。 |
reanalysisId | body | string | 否 | — | 按当前项目设置重新分析的 UUID;请求重试复用同一 UUID,进行中的任务复用。 |
输出:200,JSON 对象(schema any)。
调用示例:
curl -X POST "https://<your-endpoint>/v1/observability/scores/analysis/trigger" \
-H "Content-Type: application/json" \
-d '{"scoreIds":["<SCORE_ID>"]}' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"知识索引质量评估与 Prompt 解析(2.10.0)
POST /v1/observability/evals/index-preview
预览知识索引质量评估的评估范围:按勾选的索引能力返回各类预计评估记录数(GraphRAG 实体 / 关系 / 社区报告、RAPTOR 摘要节点、Wiki 页面),提交前评估费用与规模。
scope:observability.evals.read;Server SDK:Observability.previewIndexEvaluation。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | 是 | — | 知识库 ID。 |
versionId | body | string | 否 | null | 显式知识库版本;空为既有(legacy)范围。 |
capabilities | body | object | 是 | — | 勾选的索引能力(GraphRAG / RAPTOR / LLM Wiki)。 |
输出:200,JSON 对象(schema any)——按能力分组的预计评估记录数。
POST /v1/observability/evals/index
创建知识索引质量评估任务(GraphRAG / RAPTOR / LLM Wiki 独立评估,独立模型复核,见产品手册「评估与评分」)。
scope:observability.evals.write;Server SDK:Observability.createIndexEvaluation。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | 是 | — | 知识库 ID。 |
versionId | body | string | 否 | null | 显式知识库版本;空为既有(legacy)范围。 |
scoreName | body | string | 是 | — | 评分显示名称(≤128 字符)。 |
idempotencyKey | body | string | 是 | — | 幂等任务键;重试复用同一键。 |
members | body | object | 是 | — | 按能力独立的评估成员配置(含抽样)。 |
locale | body | string | 否 | en-us | 评估语言:en-us / zh-cn / ja-jp。 |
输出:200,JSON 对象(schema any)——评估任务。
GET /v1/observability/prompts/resolve
按名称 + label(默认 production)或精确版本号解析评估 Prompt;label 与 version 互斥。供评估执行链路确定性地取用 Prompt。
scope:observability.prompts.read;Server SDK:Observability.resolvePrompt。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | query | string | 是 | — | Prompt 名称。 |
label | query | string | 否 | production | Prompt 标签;与 version 互斥。 |
version | query | integer | 否 | — | 精确版本号;与 label 互斥。 |
输出:200,JSON 对象(schema any)——命中的 Prompt 版本。
调用示例:
curl --get "https://<your-endpoint>/v1/observability/prompts/resolve" \
--data-urlencode "name=rag-faithfulness" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"消息与工具关联格式
本节补充 POST /v1/observability/ingestion 与 GET /v1/observability/traces/{traceId} 在构造与验收智能体轨迹(ATIF v1.8)时的消息形态、父子层级、工具调用关联 ID、用量记录及错误处理契约,与上文端点字段表配合使用。
1. 事件幂等标识、实体标识与父子关系
| 字段位置 | 语义角色 | 格式与校验边界 | 重试与更新规则 |
|---|---|---|---|
batch[].id | 事件幂等 ID | 非空唯一字符串(推荐使用 UUID)。 | 重试同一事件时必须复用原 batch[].id;发送新的更新事件(如 generation-update)时必须生成新的 batch[].id。切勿每次重试重新生成。 |
batch[].body.id | 实体 ID | 推荐 Trace 使用非全零 32 位小写 hex、Observation 使用非全零 16 位小写 hex 以兼容 W3C traceparent。 | 创建与后续更新同一 Trace / Observation 实体时保持 body.id 不变。该十六进制格式为跨服务透传推荐规范;Events 入口本身不强制校验十六进制格式(仅 /observability/logs 的 traceId 选择器强制要求 W3C 十六进制格式)。 |
batch[].body.traceId | 根 Trace 引用 | Observation 与绑定 Trace 的 Score 必填,对应根 trace-create 的 body.id。 | 同一链路下的所有 Observation 必须指向同一个根 traceId。 |
batch[].body.parentObservationId | 父节点引用 | 可选;子级 Observation 填入直接父 Observation 的 body.id。 | 顶层 Observation 省略该字段或传 null;多层调用按实际调用栈关联。 |
观测树与对话轨迹的边界:普通
SPAN(如 HTTP 客户端请求、上下文准备)、RETRIEVER、EMBEDDING等节点用于构建完整观测树与时间轴瀑布图,不必生成对话轨迹步骤;平台仅从有效的对话与工具交互证据中派生并持久化ATIF v1.8轨迹。
2. 模型消息形态(Messages)与多轮上下文规则
在 generation-create / generation-update 事件的 body 中,input 与 output 遵循以下格式契约:
输入消息结构(
body.input):推荐使用{ "messages": [...] }(或直接传入消息对象数组),每条消息包含role与content。必须完整保留真实的system、user、assistant、tool角色及对话轮次顺序;需要记录可用工具定义时,可在body.input中并列传入tools函数定义数组。输出消息结构(
body.output):仅写入当次模型调用真实生成的assistant回复内容及tool_calls(如{ "role": "assistant", "content": "...", "tool_calls": [...] }),禁止将输入 Prompt 或历史消息拼入output充当模型输出。多模态内容表达:消息的
content与工具结果支持字符串,或由text、image、audio分片组成的结构化数组(保留type、media_type、path、duration_sec等字段)。多次模型调用的重叠处理:单次 Trace 包含多次模型调用时,每次
GENERATION应如实上报当时传给模型的完整上下文。根 Trace 的body.input建议传入本轮用户输入(如{ "content": "<用户问题>" }或对应的user消息);平台在构建规范轨迹时,以根 Trace 的input确定本轮起点并剔除合并会话中的历史旧轮次,再自动按前缀重叠提取新增消息。调用方不得仅因文本内容相同而自行删减真实轮次。OpenCode 与通用外部 Agent 边界:OpenCode 链路受唯一无环权威上下文(Context Snapshot)、身份核验与完整性否决规则约束;普通外部 Agent 统一按通用 ChatML 消息结构接入,不靠伪造
source标签或内部签名启用特殊路径。
3. 工具调用三处关联 ID 契约
当模型发起工具调用并在后续轮次消费工具结果时,以下三处关联标识必须保持严格一致:
| 阶段位置 | 观测事件与字段路径 | 关键结构与兼容键名 | 平台规范化映射(ATIF v1.8) |
|---|---|---|---|
| 1. 模型输出工具调用 | 前序 GENERATION 的 body.output.tool_calls[] | 每个元素必须同时包含非空调用 ID(id 或 tool_call_id)与函数名(function.name 或 name / function_name),参数置于 function.arguments(或 arguments)。 | 归一化为 ATIF Agent 步骤的 tool_calls[]:{ "tool_call_id": "<id>", "function_name": "<name>", "arguments": {...} }。缺少 ID 或函数名会触发投影错误。 |
| 2. 工具执行节点 | TOOL 观测节点的 body.metadata 与 body.output | 在 metadata.toolCallId(兼容 tool_call_id、callId、call_id 或 OTLP 属性 gen_ai.tool.call_id / gen_ai.tool.call.id)填入同一 ID;工具返回写入 body.output。 | 按调用 ID 匹配前序步骤,挂载至 observation.results[]:{ "source_call_id": "<id>", "content": ... }。 |
| 3. 后续模型输入 | 后续 GENERATION 的 body.input.messages[] | 追加 "role": "tool" 的消息,包含同一 "tool_call_id": "<id>" 及工具返回内容 "content"。 | 保持完整的多轮上下文历史重叠对齐,保留模型实际消费的工具结果。ATIF 结果关联以工具 Observation 的调用 ID 与输出为直接证据;不能仅用后续输入中的 tool 消息替代独立工具执行记录。 |
关联结构对齐示例:
{
"firstGenerationOutput": {
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "call_9f8e7d6c5b4a",
"type": "function",
"function": {
"name": "get_order_status",
"arguments": { "orderId": "ORD-20261022-889" }
}
}
]
},
"toolObservationBody": {
"id": "fedcba9876543210",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"parentObservationId": "0123456789abcdef",
"name": "get_order_status",
"metadata": {
"toolCallId": "call_9f8e7d6c5b4a"
},
"output": { "orderId": "ORD-20261022-889", "status": "SHIPPED" }
},
"secondGenerationInputMessage": {
"role": "tool",
"tool_call_id": "call_9f8e7d6c5b4a",
"content": "{\"orderId\":\"ORD-20261022-889\",\"status\":\"SHIPPED\"}"
}
}4. 用量(Usage)、成本与时间戳规范
独立记录模型用量:每次模型调用在各自的
GENERATION节点上报usage(如{ "input": 120, "output": 48, "total": 168, "unit": "TOKENS" })以及可选的usageDetails(含互斥拆分的cached/reasoning)与costDetails。禁止父子节点重复累加:切勿将子级
GENERATION的 Token 用量汇总后重复写入父级AGENT节点,规范 Generation 用量统计会排除父级 Agent 汇总与评估器自身用量;自行实现的汇总也应避免重复求和。缺失、重复或不能归属到轮次的 Generation 则会限制相关规则评估。未知用量保持缺省:当模型未返回 Token 用量、缓存读写明细或成本时,应保持对应字段缺省(未知),不要填
0冒充真实零消耗。时间戳与先后顺序:外层
timestamp、Tracetimestamp以及 Observation 的startTime、completionStartTime、endTime均使用带时区的 ISO 8601 字符串(如2026-09-14T02:30:01.000Z),且结束时间必须晚于或等于开始时间。
5. 摄取返回、重试与回读错误处理矩阵
| 接口与阶段 | 状态码或响应特征 | 语义与平台行为 | 客户端处理与重试策略 |
|---|---|---|---|
POST /v1/observability/ingestion | HTTP 200,errors: [] 且 successes[] 覆盖本批全部事件 ID | 批次内(1–100 条)全部事件通过格式校验并进入异步队列。 | 仅代表请求被接收,不等于已完成落库或 ATIF 已就绪。 |
POST /v1/observability/ingestion | HTTP 207 Multi-Status | 部分事件受理(successes[])、部分事件被拒(errors[])。 | 必须检查 errors[];针对被拒项排查原因,修正前不宣称整批成功。 |
POST /v1/observability/otel/v1/traces | HTTP 200(返回 { successes, errors }) | 接收 OTLP/HTTP JSON(resourceSpans → scopeSpans → spans)或 protobuf(可 gzip,不支持 gRPC),返回平台内部转换结果。 | 即使 HTTP 200 也必须检查 errors[],不能盲目按标准 OTLP partialSuccess 解析。 |
| 摄取接口(Events / OTLP) | 网络超时、429、500 / 502 / 503 / 504 | 瞬时限流或可恢复服务端异常。 | 使用有上限的指数退避重试;Events 重试时必须复用原事件外层 batch[].id。 |
| 摄取接口(Events / OTLP) | 400 / 401 / 403 / 413 | 请求格式、身份或权限不满足契约,或超过当前部署的请求体限制。按所调用入口各自校验配额与格式(Events 限制单批 1–100 条事件;OTLP 限制原始及解压后请求体不超过 4.5 MiB)。 | 不盲目重试;修正请求体或更换有效项目 API Key。 |
GET /v1/observability/traces/{traceId} | HTTP 404 或观测节点未齐备 | 异步 Worker 尚在处理中,或写入侧未成功投递至当前项目。 | 使用具备 observability.traces.read 的独立读 Key 执行有界短轮询;超时仍未确认则报告“已接收但未验证持久化”。 |
GET /v1/observability/traces/{traceId} | HTTP 200(顶层 { trace, observations, trajectory }) | 返回已落库的根 trace、observations[] 列表及当前持久化的 trajectory(不存在、分批上报尚未完结或异步轨迹尚未就绪时为 null;非空对象仍需核对版本和步骤)。 | 逐一核对顶层 trace、observations、trajectory;回读仅确认当前查到的内容,ATIF 就绪态与特定评估器结论仍需分别验证。 |
错误与边界
摄取部分失败用
207表达:不整体回滚,逐事件检查响应中的错误项后重投。日志查询键不在白名单(
traceId/executionId/siteExecutionId之外):参数错误;时间范围与limit/offset上限超界被截断。事件模型为 Langfuse 兼容:trace/observation/score 字段名与 Langfuse SDK 对齐,OTel 入口走标准语义约定(gen_ai 系)映射。
查询端点分页用
limit/offset(非游标),深翻页以时间窗收窄。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Observability.createIngestion / createOtelTraces | POST /observability/ingestion、POST /observability/otel/v1/traces |
Observability.listTraces / getTrace / listSessions / getSession / listUsers / getUser | trace / session / user 查询 |
Observability.listScores / listScoreConfigs / queryMetrics | GET .../scores、.../score-configs、POST .../metrics |
Observability.listLogs | GET /observability/logs |
Observability.getStatus | GET /observability |
Observability.discoverEvalMcpTools | POST /observability/evals/mcp/tools(2.8.0) |
Observability.listObservations | GET /observability/observations(2.9.0) |
Observability.getScoreAnalysis / getScoreQualityDetails / listScoreAnalysisSummaries / triggerScoreAnalyses | .../scores/{scoreId}/analysis 等分析面(2.9.0) |
Observability.previewIndexEvaluation / createIndexEvaluation | POST /observability/evals/index-preview、POST /observability/evals/index(2.10.0) |
Observability.resolvePrompt | GET /observability/prompts/resolve(2.10.0) |
2.12.0 接口与兼容增量
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
POST /observability/reports/agents | observability.metrics.read | observability.getReportAgents |
POST /observability/reports/overview | observability.metrics.read | observability.getReportOverview |
POST /observability/reports/quality | observability.metrics.read | observability.getReportQuality |
GET /observability/trace-analyses | observability.scores.read | observability.listTraceAnalyses |
POST /observability/trace-analyses | observability.scores.read | observability.createTraceAnalysis |
GET /observability/trace-analyses/{analysisId} | observability.scores.read | observability.getTraceAnalysis |
POST /observability/traces/analysis | observability.scores.read | observability.analyzeTraceCollection |
GET /observability/traces/{traceId} | observability.traces.read | observability.getTrace |
POST /observability/reports/agents
读取可观测性智能体报表。需要 observability.metrics.read、observability.traces.read、observability.users.read 和 observability.sessions.read 权限。
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
range | body | 否 | string | enum=24h, 7d, 30d; default="7d" | 预设报表时间范围;同时指定 from 和 to 时忽略。 |
from | body | 否 | string | default="" | 自定义时间范围的开始时间(ISO-8601),须与 to 一起使用,跨度最多 30 天。 |
to | body | 否 | string | default="" | 自定义时间范围的结束时间(ISO-8601),须与 from 一起使用,跨度最多 30 天。 |
成功响应:HTTP 200 — any.
POST /observability/reports/overview
读取可观测性概览报表
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
range | body | 否 | string | enum=24h, 7d, 30d; default="7d" | 预设报表时间范围;同时指定 from 和 to 时忽略。 |
from | body | 否 | string | default="" | 自定义时间范围的开始时间(ISO-8601),须与 to 一起使用,跨度最多 30 天。 |
to | body | 否 | string | default="" | 自定义时间范围的结束时间(ISO-8601),须与 from 一起使用,跨度最多 30 天。 |
成功响应:HTTP 200 — any.
POST /observability/reports/quality
读取可观测性质量报表。需要 observability.metrics.read、observability.traces.read 和 observability.scores.read 权限。
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
range | body | 否 | string | enum=24h, 7d, 30d; default="7d" | 预设报表时间范围;同时指定 from 和 to 时忽略。 |
from | body | 否 | string | default="" | 自定义时间范围的开始时间(ISO-8601),须与 to 一起使用,跨度最多 30 天。 |
to | body | 否 | string | default="" | 自定义时间范围的结束时间(ISO-8601),须与 from 一起使用,跨度最多 30 天。 |
成功响应:HTTP 200 — any.
GET /observability/trace-analyses
通过受限游标分页列出基于模型的集合分析历史。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
limit | query | 否 | integer | format=int32; default=20 | 历史记录最大条数,取 1–20。 |
cursor | query | 否 | string | default="" | 上一页返回的不透明 nextCursor。 |
datasetId | query | 否 | string | default="" | 需要查询分析历史的数据集。 |
成功响应:HTTP 200 — any.
POST /observability/trace-analyses
为同一应用的 2–100 条 Trace 创建基于模型的根因分析。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
traceIds | body | 否 | array[string] | default=[] | Trace ID 列表,需提供 2–100 个,重复项会被忽略;提供 datasetId 时忽略此项。 |
requestId | body | 是 | string | — | 幂等 UUID;重试时复用,重新分析时使用新的 UUID。 |
name | body | 否 | string | — | 集合名称,最多 120 个字符。 |
datasetId | body | 否 | string | default="" | 分析所属的数据集;提供时从其有效条目中获取来源 Trace。 |
datasetRunId | body | 否 | string | default="" | 需要分析其 Trace 的数据集运行记录,须同时提供 datasetId。 |
成功响应:HTTP 202 — any.
GET /observability/trace-analyses/{analysisId}
查询基于模型的集合分析及已保存结果,不会创建新任务。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
analysisId | path | 是 | string | — | 创建或列表接口返回的集合分析 ID。 |
成功响应:HTTP 200 — any.
POST /observability/traces/analysis
汇总同一应用 2–100 条 Trace 的已有分析,不会创建新任务。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
traceIds | body | 否 | array[string] | default=[] | 待分析的 Trace ID,需提供 2–100 个,重复项会被忽略;提供 datasetId 时忽略此项。 |
datasetId | body | 否 | string | default="" | 分析所属的数据集;提供时从其有效条目中获取来源 Trace。 |
datasetRunId | body | 否 | string | default="" | 需要分析其 Trace 的数据集运行记录,须同时提供 datasetId。 |
成功响应:HTTP 200 — any.
GET /observability/traces/{traceId}
查询可观测性 Trace
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
traceId | path | 是 | string | — | Trace ID,最多 128 个字符。 |
compact | query | 否 | boolean | default=false | 返回受限的 Trace 视图,并明确标注省略内容的覆盖情况。 |
成功响应:HTTP 200 — any.
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。