Docs
文档目录

可观测性 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 版本解析以及知识索引质量评估任务编排。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 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/tracesOpenTelemetry 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/observationsObservation 列表(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项目摄取状态

端点详解

请求与响应

以下按端点给出完整规格:输入(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 参数;请求体是原始 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)。

调用示例:

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 新增)。

输入:

参数位置类型必填默认/枚举说明
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 列表及持久化 trajectory:定位一次 Agent / RAG / LLM 调用的全链路细节。

输入:

参数位置类型必填默认/枚举说明
traceIdpathstring是—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。

调用示例:

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 聚合而成,用于按对话轮次观测。

输入:

参数位置类型必填默认/枚举说明
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)。

观测列表与评分分析(2.9.0)

GET /v1/observability/observations

跨 Trace 查询 Observation;名称、级别、traceId 和环境使用精确匹配。

scope:observability.traces.read;Server SDK:Observability.listObservations。

输入:

参数位置类型必填默认/枚举说明
limitqueryinteger否25单页最大返回数量,取值 1–100。
offsetqueryinteger否0分页跳过的记录数(偏移量),取值 0–999900,且必须为 limit 的整数倍。
fromquerystring否""观测时间范围起点。
toquerystring否""观测时间范围终点。
typequerystring否""逗号分隔的观测类型。
namequerystring否""观测名称,精确匹配。
levelquerystring否""观测级别,精确匹配。
traceIdquerystring否""父 Trace ID,精确匹配。
environmentquerystring否""环境,精确匹配。

输出:200,模型 observabilityObservationList。

字段类型说明
totalinteger当前筛选条件下的观测总数。
observationsobject[]本页观测,模型 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。

输入:

参数位置类型必填默认/枚举说明
scoreIdpathstring是—评分 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。

输入:

参数位置类型必填默认/枚举说明
scoreIdpathstring是—评分 ID。
kindquerystring是parsing / chunking解析或分块明细类型。
limitqueryinteger否25最大返回数量。
offsetqueryinteger否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。

输入:

参数位置类型必填默认/枚举说明
scoreIdsbodystring[]是—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。

输入:

参数位置类型必填默认/枚举说明
scoreIdsbodystring[]是—1–100 个评分 ID,重复 ID 自动去重。
reanalysisIdbodystring否—按当前项目设置重新分析的 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。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdbodystring是—知识库 ID。
versionIdbodystring否null显式知识库版本;空为既有(legacy)范围。
capabilitiesbodyobject是—勾选的索引能力(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。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdbodystring是—知识库 ID。
versionIdbodystring否null显式知识库版本;空为既有(legacy)范围。
scoreNamebodystring是—评分显示名称(≤128 字符)。
idempotencyKeybodystring是—幂等任务键;重试复用同一键。
membersbodyobject是—按能力独立的评估成员配置(含抽样)。
localebodystring否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。

输入:

参数位置类型必填默认/枚举说明
namequerystring是—Prompt 名称。
labelquerystring否productionPrompt 标签;与 version 互斥。
versionqueryinteger否—精确版本号;与 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;多层调用按实际调用栈关联。

2. 模型消息形态(Messages)与多轮上下文规则

在 generation-create / generation-update 事件的 body 中,input 与 output 遵循以下格式契约:

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)、成本与时间戳规范

5. 摄取返回、重试与回读错误处理矩阵

接口与阶段状态码或响应特征语义与平台行为客户端处理与重试策略
POST /v1/observability/ingestionHTTP 200,errors: [] 且 successes[] 覆盖本批全部事件 ID批次内(1–100 条)全部事件通过格式校验并进入异步队列。仅代表请求被接收,不等于已完成落库或 ATIF 已就绪。
POST /v1/observability/ingestionHTTP 207 Multi-Status部分事件受理(successes[])、部分事件被拒(errors[])。必须检查 errors[];针对被拒项排查原因,修正前不宣称整批成功。
POST /v1/observability/otel/v1/tracesHTTP 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 就绪态与特定评估器结论仍需分别验证。

错误与边界

与 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)
Observability.listObservationsGET /observability/observations(2.9.0)
Observability.getScoreAnalysis / getScoreQualityDetails / listScoreAnalysisSummaries / triggerScoreAnalyses.../scores/{scoreId}/analysis 等分析面(2.9.0)
Observability.previewIndexEvaluation / createIndexEvaluationPOST /observability/evals/index-preview、POST /observability/evals/index(2.10.0)
Observability.resolvePromptGET /observability/prompts/resolve(2.10.0)

2.12.0 接口与兼容增量

以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。

HTTPScopeSDK
POST /observability/reports/agentsobservability.metrics.readobservability.getReportAgents
POST /observability/reports/overviewobservability.metrics.readobservability.getReportOverview
POST /observability/reports/qualityobservability.metrics.readobservability.getReportQuality
GET /observability/trace-analysesobservability.scores.readobservability.listTraceAnalyses
POST /observability/trace-analysesobservability.scores.readobservability.createTraceAnalysis
GET /observability/trace-analyses/{analysisId}observability.scores.readobservability.getTraceAnalysis
POST /observability/traces/analysisobservability.scores.readobservability.analyzeTraceCollection
GET /observability/traces/{traceId}observability.traces.readobservability.getTrace

POST /observability/reports/agents

读取可观测性智能体报表。需要 observability.metrics.read、observability.traces.read、observability.users.read 和 observability.sessions.read 权限。

参数位置必填类型约束 / 默认值含义
rangebody否stringenum=24h, 7d, 30d; default="7d"预设报表时间范围;同时指定 from 和 to 时忽略。
frombody否stringdefault=""自定义时间范围的开始时间(ISO-8601),须与 to 一起使用,跨度最多 30 天。
tobody否stringdefault=""自定义时间范围的结束时间(ISO-8601),须与 from 一起使用,跨度最多 30 天。

成功响应:HTTP 200 — any.

POST /observability/reports/overview

读取可观测性概览报表

参数位置必填类型约束 / 默认值含义
rangebody否stringenum=24h, 7d, 30d; default="7d"预设报表时间范围;同时指定 from 和 to 时忽略。
frombody否stringdefault=""自定义时间范围的开始时间(ISO-8601),须与 to 一起使用,跨度最多 30 天。
tobody否stringdefault=""自定义时间范围的结束时间(ISO-8601),须与 from 一起使用,跨度最多 30 天。

成功响应:HTTP 200 — any.

POST /observability/reports/quality

读取可观测性质量报表。需要 observability.metrics.read、observability.traces.read 和 observability.scores.read 权限。

参数位置必填类型约束 / 默认值含义
rangebody否stringenum=24h, 7d, 30d; default="7d"预设报表时间范围;同时指定 from 和 to 时忽略。
frombody否stringdefault=""自定义时间范围的开始时间(ISO-8601),须与 to 一起使用,跨度最多 30 天。
tobody否stringdefault=""自定义时间范围的结束时间(ISO-8601),须与 from 一起使用,跨度最多 30 天。

成功响应:HTTP 200 — any.

GET /observability/trace-analyses

通过受限游标分页列出基于模型的集合分析历史。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。

参数位置必填类型约束 / 默认值含义
limitquery否integerformat=int32; default=20历史记录最大条数,取 1–20。
cursorquery否stringdefault=""上一页返回的不透明 nextCursor。
datasetIdquery否stringdefault=""需要查询分析历史的数据集。

成功响应:HTTP 200 — any.

POST /observability/trace-analyses

为同一应用的 2–100 条 Trace 创建基于模型的根因分析。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。

参数位置必填类型约束 / 默认值含义
traceIdsbody否array[string]default=[]Trace ID 列表,需提供 2–100 个,重复项会被忽略;提供 datasetId 时忽略此项。
requestIdbody是string—幂等 UUID;重试时复用,重新分析时使用新的 UUID。
namebody否string—集合名称,最多 120 个字符。
datasetIdbody否stringdefault=""分析所属的数据集;提供时从其有效条目中获取来源 Trace。
datasetRunIdbody否stringdefault=""需要分析其 Trace 的数据集运行记录,须同时提供 datasetId。

成功响应:HTTP 202 — any.

GET /observability/trace-analyses/{analysisId}

查询基于模型的集合分析及已保存结果,不会创建新任务。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。

参数位置必填类型约束 / 默认值含义
analysisIdpath是string—创建或列表接口返回的集合分析 ID。

成功响应:HTTP 200 — any.

POST /observability/traces/analysis

汇总同一应用 2–100 条 Trace 的已有分析,不会创建新任务。需要 observability.scores.read 和 observability.traces.read 权限;数据集分析还需要 observability.datasets.read。

参数位置必填类型约束 / 默认值含义
traceIdsbody否array[string]default=[]待分析的 Trace ID,需提供 2–100 个,重复项会被忽略;提供 datasetId 时忽略此项。
datasetIdbody否stringdefault=""分析所属的数据集;提供时从其有效条目中获取来源 Trace。
datasetRunIdbody否stringdefault=""需要分析其 Trace 的数据集运行记录,须同时提供 datasetId。

成功响应:HTTP 200 — any.

GET /observability/traces/{traceId}

查询可观测性 Trace

参数位置必填类型约束 / 默认值含义
traceIdpath是string—Trace ID,最多 128 个字符。
compactquery否booleandefault=false返回受限的 Trace 视图,并明确标注省略内容的覆盖情况。

成功响应:HTTP 200 — any.

错误与重试边界

400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。