可观测
这是什么 / 何时用
Observability 覆盖两件事:
- AI 观测上报:把 Trace / Observation / Generation / Score(Langfuse 风格事件模型)从受控服务端、CLI、Function 或 Site SSR 上报到当前项目,用于 Agent/LLM 调用链排障、token 用量与质量评估。
- 查询面:按 Trace 查事件树、按 Session/User 聚合、指标查询;以及独立的 Trace 日志查询(Function/动态 Site 的 stdout/stderr,按 W3C Trace ID 或 Execution ID)。
前置
- 公开边界只有
/v1/observability/**;认证固定X-Appwrite-Project+X-Appwrite-Key(有效项目 API Key 或 Function/Site 动态 Key)。2.6.0 起写入 scope 统一为observability.ingest.write(平台注入的动态 Key 自带,无需 Console 勾选;observability.write仅为旧 Key 兼容别名)。 - 租户只取认证上下文:请求 body 禁止传
projectId/orgId等内部 ID;浏览器必须经 Function / Site SSR / 自有后端代报,不持任何观测服务密钥。 - Trace 日志查询是独立数据面:scope
traceLogs.read,与 AI 观测的observability.*互不包含。 - 状态探测
observability.getStatus()(scopeobservability.status.read)返回 ingestionEndpoints;探测权限与写入权限分离。
使用骨架
- 批量上报:
observability.createIngestion({ batch, metadata? })——batch为 1–100 个事件(空批/超 100 拒绝);事件结构{ id, timestamp, type, body }: - 外层
id是幂等 ID(每个 create/update 事件用新的唯一值);body.id是实体 ID(更新同一实体保持不变)。 - 类型:
trace-create、span-create/span-update、generation-create/generation-update、score-create等;Observation 的body.traceId指根 Trace,子 Observation 用parentObservationId指父。 - Trace ID 推荐 32 位小写 hex(非全零)、Observation 16 位 hex,兼容 W3C traceparent;时间用 ISO8601 带时区;
level ∈ DEBUG | DEFAULT | WARNING | ERROR。
- 外层
- 处理返回:全部成功 → HTTP 200;任一失败 → **HTTP 207 Multi-Status,必须逐项检查
errors[]**,不能只看请求是否抛错。200/207 都不等于已持久化(异步 worker 落库):回读 404 时做有上限短轮询,仍无则按"已接收但未验证持久化"处理。 - 重试策略:429 与可恢复 5xx 用有上限指数退避并复用原外层 id;schema/权限类 4xx 不盲重试;超 100 条按 create-before-update 顺序分批。
- OTel traces 上报:
observability.createOtelTraces(body, contentType?)——OTLP HTTP 形态(JSON/protobuf,可选 gzip),SDK 直传原始 body 并返回原始响应;适合接 OpenTelemetry exporter。不是 OTLP gRPC endpoint。 - 查询:
getTrace/listTraces/getSession/listSessions/getUser/listUsers/queryMetrics/listScores/listScoreConfigs;状态getStatus。 - Trace 日志查询:
observability.listLogs({ query, from?, to?, limit?, offset? })——query必填且只允许一个traceId:<value>或executionId:<value>;from默认 to−3600(Unix 秒),to默认当前时间,时间窗最大 24 小时;limit1–100(默认 25);offset0–1000。
关键参数与返回
- ingestion 事件字段要点:
environment仅小写字母数字与-_(≤40 字符,禁langfuse前缀);usage { input, output, total, unit: 'TOKENS' };score-create需name/value/dataType+ 目标(traceId / observationId / sessionId)。 - Trace 日志响应:
{ logs: [{ timestamp, level, message, source, function_id, execution_id, deployment_id, trigger, stream, chunk_index, chunk_count, trace_id }], complete };complete表示日志提供方是否完成查询;无匹配返回 200 + 空数组。 - Trace ID 获取:
traceparent(00-<32hex>-<16hex>-01)会透传进 Function 请求;无 Trace ID 时用 Execution ID 更可靠;全零、短 UUID、带连字符 UUID、业务字符串会被拒绝。
错误与边界
- Trace 日志查询错误:400(selector/时间窗/limit/offset 非法——时间窗勿超 24h)、401(未认证或缺
traceLogs.read)、503(能力关闭/Provider 不可用/SLS 配置失败)、504(Provider 查询超时——缩窗或调 read timeout)。 - Trace 日志不返回:HTTP 请求日志、平台 completion/failure 事件、网关/队列/容器/主机日志、内部异常类型与凭据;消息对敏感字段脱敏并截断。
logging=false或无业务输出时查询为空是预期。 - 数据最小化:默认只上报 duration/status/资源 ID/model/token 用量等有界事实;Prompt、回答、RAG chunk、Memory 内容须用户明确确认数据边界后才采集;永不上报 Authorization/Cookie/项目 Key/Gateway Key/密码/raw headers/完整堆栈。
- 上报放
finally,best-effort 也要留下脱敏失败状态与 Trace ID。
2.7.0 增量:轨迹评估与监控指标
以下能力落在 Console 评估面与评估 worker / 部署监控侧,公开摄取与查询契约(本页端点)无变化(spec v2.6.0 → v2.7.0 observability 段无新增端点与参数变更):
- Agent 轨迹评估(appbase release-2.7.0 PR 562 等):数据集评估在 Trace 目标之外支持 Agent 目标(评估直接驱动 Agent 运行取样),并补齐手动 Agent 评估模式与轨迹规则评估器;OpenCode 轨迹摄取的角色与丢事件问题一并修复。
- 监控与 Function 指标(PR 556):Console Function 用量页新增资源监控视图(function resource metrics),部署侧补齐监控仪表盘与告警规则。
2.8.0 增量:评估 MCP 工具发现
评估任务可为评估器挂接 MCP 工具:配置前先用受限网关凭据发现该网关上可用的只读 MCP 工具,再在评估配置中圈定要挂接的工具。新增方法 observability.discoverEvalMcpTools(gatewayId, gatewayKeyId) —— POST /observability/evals/mcp/tools,请求体 { gatewayId, gatewayKeyId }(AI Gateway 的网关 ID 与受限 Gateway Key ID);返回该网关暴露的只读(无副作用)MCP 工具清单。scope 为 observability.evals.write;gatewayKeyId 需为绑定该网关的活跃子密钥(显式圈定工具、不含模型 / Agent 权限)。
SDK 类别差异
- Console SDK:JS Console SDK(2.6.0)无 Observability 服务(Console 页面直读观测视图);Java Console SDK 有
Observability服务。 - 客户端 SDK(client-sdk/web.md):不承担服务端观测上报(浏览器经自有后端/Function 代报)。
- Java Server / Console SDK 均有
Observability服务。
示例指引
- JavaScript(Node 上报 + 207 处理 + Trace 日志查询):examples/javascript.md
- Java:examples/java.md
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
批量上报(JSON ingestion)
batch 为 1–100 个事件;全部成功 HTTP 200,任一失败 HTTP 207 Multi-Status,必须逐项检查 errors[]——200/207 都不等于已持久化(异步 worker 落库),回读 404 时做有上限短轮询。429 与可恢复 5xx 用有上限指数退避并复用原外层 id,schema/权限类 4xx 不盲重试;超 100 条按 create-before-update 顺序分批。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Client, Observability } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // 写入 scope observability.ingest.write
const observability = new Observability(client);
const res = await observability.createIngestion({
batch: [{
id: crypto.randomUUID(), // 外层幂等 ID:每个 create/update 事件用新的唯一值
timestamp: new Date().toISOString(),
type: 'trace-create',
body: { id: traceId32Hex, name: 'agent-run' } // body.id 是实体 ID,更新同一实体保持不变
}]
});
// 全部成功 HTTP 200;任一失败 HTTP 207 Multi-Status,逐项检查 res.errors[],不能只看是否抛错import io.agentbase.services.Observability;
Observability observability = new Observability(client); // client 初始化见 server-sdk/java.md
Object res = observability.createIngestion(
List.of(Map.of(
"id", java.util.UUID.randomUUID().toString(), // 外层幂等 ID:每个 create/update 事件用新值
"timestamp", java.time.Instant.now().toString(),
"type", "trace-create",
"body", Map.of("id", traceId32Hex, "name", "agent-run"))),
null);
// 全部成功 HTTP 200;部分失败 HTTP 207,逐项检查 errors[],不能只看是否抛异常from uuid import uuid4
from datetime import datetime, timezone
from agentbase.services.observability import Observability
observability = Observability(client) # 方法面与 Node SDK 同构,snake_case 入参
res = observability.create_ingestion(batch=[{
'id': str(uuid4()), # 外层幂等 ID:每个 create/update 事件用新值
'timestamp': datetime.now(timezone.utc).isoformat(),
'type': 'trace-create',
'body': {'id': '<32位小写hex>', 'name': 'agent-run'},
}])
# 全部成功 HTTP 200;任一失败 HTTP 207 Multi-Status,逐项检查 errors[]obs := agentbase.NewObservability(cl) // facade 构造器;cl 为已装载 API Key 的 Client
res, _ := obs.CreateIngestion([]interface{}{map[string]interface{}{
"id": "<唯一幂等ID>", // 外层幂等 ID:每个 create/update 事件用新的唯一值
"timestamp": time.Now().UTC().Format(time.RFC3339),
"type": "trace-create",
"body": map[string]interface{}{"id": traceId32Hex, "name": "agent-run"}, // body.id 是实体 ID,更新同一实体保持不变
}}) // 可选 obs.WithCreateIngestionMetadata
// 全部成功 HTTP 200;任一失败 HTTP 207 Multi-Status,逐项检查返回体 errors[],不能只看是否抛错curl -sS -X POST "$APPBASE_ENDPOINT/observability/ingestion" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"batch":[{"id":"<唯一幂等ID>","timestamp":"2026-01-01T00:00:00+00:00","type":"trace-create","body":{"id":"<32位小写hex>","name":"agent-run"}}]}'
# 全部成功 200;任一失败 207 Multi-Status 逐项检查 errors[];batch 为 1–100 个事件
# 重试复用原外层 id(429/可恢复 5xx 有上限退避);超 100 条按 create-before-update 顺序分批OTel Traces 上报
SDK 直传原始 OTLP body 并返回原始响应(本页给 Node SDK 与 REST 形态);其他语言可让 OpenTelemetry exporter 直连同一 REST 端点。
- Node.js(Server)
- REST(curl)
// createOtelTraces(body, contentType?) —— OTLP HTTP 形态(JSON/protobuf,可选 gzip)
const raw = await observability.createOtelTraces(otelBody);
// 不是 OTLP gRPC endpoint;适合接 OpenTelemetry exportercurl -sS -X POST "$APPBASE_ENDPOINT/observability/otel/v1/traces" \
-H 'Content-Type: application/x-protobuf' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
--data-binary @otlp-traces.pb
# OpenTelemetry exporter 直连此端点(OTLP HTTP);JSON/protobuf,可选 gzip查询与 Trace 日志
getStatus 为状态探测;Trace 日志查询是独立数据面(scope traceLogs.read)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const status = await observability.getStatus(); // scope observability.status.read;返回 ingestionEndpoints
// 查询面另有 getTrace / listTraces / getSession / listSessions / getUser / listUsers / queryMetrics / listScores / listScoreConfigs
// Trace 日志:query 必填且只允许一个 traceId:<value> 或 executionId:<value>
const logs = await observability.listLogs({ query: `executionId:${execId}`, limit: 50 });Object status = observability.getStatus(); // scope observability.status.read;返回 ingestionEndpoints
// 查询面另有 getTrace / listTraces / getSession / listSessions / getUser / listUsers / queryMetrics / listScores / listScoreConfigs
io.agentbase.models.TraceLogList logs = observability.listLogs("executionId:" + execId,
null, null, 50L, null); // query 只允许一个 traceId:<value> 或 executionId:<value>;参数序 from/to/limit/offsetstatus = observability.get_status() # scope observability.status.read;返回 ingestionEndpoints
logs = observability.list_logs(query=f'executionId:{exec_id}', limit=50)
# query 只允许一个 traceId:<value> 或 executionId:<value>;时间窗 ≤24h
# 查询面另有 get_trace / list_traces / get_session / list_sessions / get_user / list_users / query_metrics / list_scores / list_score_configsstatus, _ := obs.GetStatus() // scope observability.status.read;返回 ingestionEndpoints
// 查询面另有 GetTrace / ListTraces / GetSession / ListSessions / GetUser / ListUsers / QueryMetrics / ListScores / ListScoreConfigs
logs, _ := obs.ListLogs("executionId:"+execId, obs.WithListLogsLimit(50)) // 只允许一个 traceId:<value> 或 executionId:<value>;另有 WithListLogsFrom/To/Offset# Trace 日志:from/to 为 Unix 秒(from 默认 to−3600),时间窗 ≤24h;limit 1–100(默认 25),offset 0–1000
curl -sS "$APPBASE_ENDPOINT/observability/logs?query=executionId%3A$EXEC_ID&limit=50" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 查询面:GET /observability/traces(/{traceId})、GET /observability/sessions、GET /observability/users、
# GET /observability/scores、GET /observability/score-configs、POST /observability/metrics、GET /observability(摄取状态)事实源
skills/ob-agentbase/references/observability-ingestion.mdskills/ob-agentbase/references/trace-logs.mdskills/ob-agentbase/references/ai-observability.md- appbase v2.7.0(tag v2.7.0);release-2.7.0 分支 PR 562(Agent 轨迹评估)与 PR 556(监控与 Function 指标)
- agentbase-sdks v2.8.0 specs(
POST /observability/evals/mcp/tools);appbase v2.8.0(Observability 模块 Evals/Mcp/Tools 路由,scopeobservability.evals.write) - agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/services/observability.ts:createIngestion/createOtelTraces均在 2.6.0 源码确认)