可观测性 API
LLM 应用可观测性数据面(兼容 Langfuse 语义):trace / observation / score 事件摄取(批量 JSON 与 OpenTelemetry 两种入口)、trace / session / user / score 查询、指标查询、执行日志关联与项目摄取状态。
资源与基础路径
- 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 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(执行日志)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
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 / 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 逐事件报告。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
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/body 参数。
输出:返回 200(OTLP 标准受理响应)。请求约束: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 文档(resourceSpores → scopeSpans → spans)响应示例:200:响应为 OTLP 标准受理确认(partialSuccess 语义),此处不展开字段。
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 树:定位一次 Agent / RAG / LLM 调用的全链路细节。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
traceId | path | string | 是 | — | Trace ID,最长 128 字符;与摄取时 body.id 一致。 |
输出:返回完整 trace(泛化 schema any):根 trace 字段加 observations[] 树(每项含 id、traceId、parentObservationId、type(span / generation 等)、startTime / endTime、model、usage、level)。
- 摄取后立即查询若 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 + 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 聚合而成,用于按对话轮次观测。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
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)。
错误与边界
- 摄取部分失败用
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) |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/observability域 13 个端点、traceLogList模型、Langfuse 兼容查询对象)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0Observabilityservice。 - 2.8.0 新增端点:
POST /observability/evals/mcp/tools(specopen-api3-latest-server.jsonv2.8.0 实读确认:请求体gatewayId+gatewayKeyId,响应泛化 schema;appbaseobservability.evals.writescope)。 - 语义深度参考:
skills/ob-agentbase/references/observability.md。