可观测
这是什么 / 何时用
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;探测权限与写入权限分离。
选择接入方式
| 已有条件 | 接入方式 | 适用边界 |
|---|---|---|
| 已使用 OpenTelemetry SDK / Exporter | 标准 exporter → OTLP/HTTP Trace 入口 | JSON 或 protobuf,可选 gzip;不支持 OTLP/gRPC |
| Agentbase Node.js 服务端应用 | 精确安装 agentbase-node-sdk@2.10.0,调用 createIngestion 或 createOtelTraces | 复用 Client 与项目认证;createOtelTraces(body, contentType)(contentType 可选) 保留原始 body 形态 |
| 自行控制 HTTP 请求 | REST → Events 或 OTLP Trace 入口 | REST 参数与错误模型见 API 参考 |
OpenTelemetry exporter 使用 traces 专用完整地址;以下 APPBASE_ENDPOINT 已包含 /v1,其他变量由受控进程环境注入:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${APPBASE_ENDPOINT%/}/observability/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="X-Appwrite-Project=${APPBASE_PROJECT_ID},X-Appwrite-Key=${APPBASE_API_KEY}"endpoint 不要重复追加 /v1/traces。本版本 OTLP 入口返回 Agentbase 事件批次 JSON,目标 exporter 对该响应的处理需按实际版本验证,不能只凭 OTLP 名称推定完全兼容。生产 exporter 使用有界队列、批量、短超时和有限重试;观测后端不可用时记录脱敏失败/丢弃计数,避免阻塞业务。使用 Agentbase SDK 直传 gzip body 时,还需由客户端显式设置相应 Content-Encoding;普通 exporter 按其自身配置发送。
上报验收分两步:先检查批次响应的 errors[],再用独立读取凭据或 Console 按相同 Trace ID 确认异步持久化。状态探测需要 observability.status.read,Trace 回查需要 observability.traces.read;这些读取能力与写入权限分开,不为方便排查扩大生产 exporter 的权限。
使用骨架
批量上报:
observability.createIngestion({ batch, metadata })(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)(contentType可选)——OTLP HTTP 形态(JSON/protobuf,可选 gzip),SDK 直传原始 body 并返回原始响应;已有 OpenTelemetry SDK 时由 exporter 直连 HTTP 入口。不是 OTLP gRPC endpoint。查询:
getTrace/listTraces/getSession/listSessions/getUser/listUsers/queryMetrics/listScores/listScoreConfigs;状态getStatus。Trace 日志查询:
observability.listLogs({ query, from, to, limit, offset })(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 权限)。
2.9.0 增量:Observation 列表与评分分析
Observation 列表:新增
observability.listObservations({ limit, offset, from, to, type, name, level, traceId, environment })(limit、offset、from、to、type、name、level、traceId、environment均可选) ——GET /v1/observability/observations。name精确匹配、type多选、level过滤;limit1–100,offset必须为limit整数倍(稳定分页);返回{ observations, total }。scopeobservability.traces.read。评分根因分析:
getScoreAnalysis(scoreId)(分析详情:观测事实 / 根因 / 建议)、getScoreQualityDetails(scoreId, { kind })(kind可选)(解析 / 分块 / 索引产物明细,kind∈parsing/chunking/index)、listScoreAnalysisSummaries(分析洞察批量摘要)、triggerScoreAnalyses({ scoreIds })(人工触发,单批 ≤100 个评分)。自动链路只处理关联 Trace、可归一化且规范化值 < 0.5 的数值评分;「使用模型进行根因分析」由 RCA 设置接口控制(Console 面)。执行重试:
POST /v1/observability/evals/jobs/{jobId}/executions/{executionId}/retry(复用仍有效的已保存进度;仅 Server API 与 Console,Node SDK 本迭代未提供方法)。GET /observability/scores新增scoreId查询参数(按评分 ID 过滤);Metrics 查询支持memoryOnly过滤。
2.10.0 增量:知识索引质量评估与 Prompt 解析
知识索引质量评估:对 GraphRAG / RAPTOR / LLM Wiki 三类索引产物做独立模型评估 + 规则检查(能力级 0–1 质量分,独立模型复核,抽样可配置)。新增方法:
observability.previewIndexEvaluation({ knowledgeBaseId, versionId, capabilities })(versionId可选) ——POST /v1/observability/evals/index-preview,提交前返回各类预计评估记录数。scopeobservability.evals.read。observability.createIndexEvaluation({ knowledgeBaseId, versionId, scoreName, idempotencyKey, members, locale })(versionId、locale均可选) ——POST /v1/observability/evals/index,创建评估任务(locale枚举en-us/zh-cn/ja-jp,默认en-us)。scopeobservability.evals.write。
评分明细扩展:
getScoreQualityDetails(scoreId, { kind })的kind枚举在parsing/chunking之外新增index(索引产物逐记录明细:维度分、理由与证据)。评估 Prompt 解析:
observability.resolvePrompt({ name, label, version })(label、version均可选) ——GET /v1/observability/prompts/resolve,按名称 + label(默认production)或精确版本解析评估 Prompt(label 与 version 互斥)。scopeobservability.prompts.read。
SDK 类别差异
Console SDK:2.9.0 的 Console SDK 已包含 Observability 服务;管理面使用 Console Session/JWT。公开上报示例使用 Server SDK 与项目 API Key,读取面按对应 scope 分开授权。
客户端 SDK(client-sdk/web.md):不承担服务端观测上报(浏览器经自有后端/Function 代报)。
Java Server / Console SDK 均有
Observability服务。
示例指引
JavaScript(Node 上报 + 207 处理 + Trace 日志查询):examples/javascript.md
Java:examples/java.md
完整 Agent 轨迹上报示例
以下提供一个基于 Node.js 18+ 原生 fetch 与 node:crypto 的完整 ESM 脚本(无需安装额外依赖)。本示例直接调用公开 REST 接口(POST /v1/observability/ingestion 与可选的回读接口 GET /v1/observability/traces/{traceId}),用于演示原始事件的关联结构及分层验收方式,并非某个 SDK 版本内置的高层封装方法。
场景与事件结构说明
示例采用合成订单查询场景(用户查询订单 ORD-20261022-889 的物流状态):
第一次模型调用(
generation-create):接收system与user消息,模型输出assistant的工具调用请求tool_calls(调用函数get_order_status);工具执行(
tool-create):通过metadata.toolCallId关联同一工具调用 ID,返回订单已发货状态;第二次模型调用(
generation-create):在input.messages中完整携带前序system、user、assistant(含tool_calls)及tool(含一致的tool_call_id)上下文,在output中仅输出本次最终assistant回答。
整次上报共包含 1 个 trace-create、2 个 generation-create、1 个 tool-create(共 4 个事件)。所有 ID 由脚本动态生成;模型身份(synthetic-order-model-demo)与 Token 用量均为合成演示数据,不连接或冒充真实大模型服务,也不代表真实模型质量评估通过。
运行条件与环境变量
运行环境:Node.js 18 或更高版本(保存为
report-agent-trajectory.mjs并通过node report-agent-trajectory.mjs运行)。环境变量说明(所有凭据均从环境变量读取,不硬编码内部域名或项目 ID,脚本不打印任何密钥,也不要在 Shell 中启用
set -x或curl -v):
| 环境变量 | 必填 | 所需权限 Scope | 说明 |
|---|---|---|---|
APPBASE_ENDPOINT | 是 | — | 目标实例公开 API 地址,路径必须为 /v1(如 https://<your-endpoint>/v1)。 |
APPBASE_PROJECT_ID | 是 | — | 目标项目 ID。 |
APPBASE_API_KEY | 是 | observability.ingest.write | 用于上报事件的写入 API Key。 |
APPBASE_OBSERVABILITY_READ_KEY | 否 | observability.traces.read | 独立配置的验收读取 Key,用于对 GET /observability/traces/{traceId} 执行有界短轮询;未配置时仅验证受理。 |
完整 ESM 脚本(report-agent-trajectory.mjs)
import { randomBytes, randomUUID } from 'node:crypto';
class ExampleError extends Error {}
/**
* 校验并规范化公开 Endpoint,要求路径必须为 /v1,且不含内嵌凭据、query 或 hash
*/
function normalizeEndpoint(rawEndpoint) {
if (!rawEndpoint || typeof rawEndpoint !== 'string') {
throw new ExampleError('缺少必填环境变量 APPBASE_ENDPOINT(路径须为 /v1)');
}
const url = new URL(rawEndpoint);
if (!['http:', 'https:'].includes(url.protocol)) {
throw new ExampleError('APPBASE_ENDPOINT 必须使用 http 或 https 协议');
}
if (url.username || url.password || url.search || url.hash) {
throw new ExampleError('APPBASE_ENDPOINT 不得包含内嵌凭据、查询参数或片段标识符');
}
const cleanPath = url.pathname.replace(/\/+$/, '');
if (cleanPath !== '/v1') {
throw new ExampleError('APPBASE_ENDPOINT 路径必须为 /v1(如 https://<your-endpoint>/v1)');
}
return `${url.origin}${cleanPath}`;
}
/**
* 生成指定字节数的非全零小写十六进制字符串(16 bytes = 32 hex,8 bytes = 16 hex)
*/
function generateNonZeroHex(byteLength) {
while (true) {
const hex = randomBytes(byteLength).toString('hex');
if (!/^0+$/.test(hex)) {
return hex;
}
}
}
/**
* 构造合成订单查询场景的 4 个事件:
* 1 个 trace-create + 2 个 generation-create + 1 个 tool-create
* 发送前固定该 batch,重试时复用同一外层 event.id
*/
function buildSyntheticOrderTraceBatch() {
const traceId = generateNonZeroHex(16); // 32 位小写非全零 hex
const firstGenId = generateNonZeroHex(8); // 16 位小写非全零 hex
const toolObsId = generateNonZeroHex(8); // 16 位小写非全零 hex
const secondGenId = generateNonZeroHex(8); // 16 位小写非全零 hex
const toolCallId = `call_${generateNonZeroHex(6)}`;
const baseMs = Date.now() - 1000;
const isoAt = (offsetMs) => new Date(baseMs + offsetMs).toISOString();
// 合成演示模型标识(非真实模型调用)
const syntheticModel = 'synthetic-order-model-demo';
const tools = [{
type: 'function',
function: {
name: 'get_order_status',
description: '查询合成订单状态',
parameters: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },
},
}];
const systemMsg = {
role: 'system',
content: '你是企业订单助手,请通过工具查询订单真实状态后回答用户。',
};
const userMsg = {
role: 'user',
content: '请帮我查一下订单 ORD-20261022-889 发货了吗?',
};
const firstAssistantToolCallMsg = {
role: 'assistant',
content: '',
tool_calls: [
{
id: toolCallId,
type: 'function',
function: {
name: 'get_order_status',
arguments: { orderId: 'ORD-20261022-889' },
},
},
],
};
const toolResultPayload = {
orderId: 'ORD-20261022-889',
status: 'SHIPPED',
carrier: 'SF-Express',
updatedAt: isoAt(350),
};
const toolRoleMsg = {
role: 'tool',
tool_call_id: toolCallId,
content: JSON.stringify(toolResultPayload),
};
const finalAssistantAnswer =
'您的订单 ORD-20261022-889 已由顺丰速运(SF-Express)发出,当前状态为已发货(SHIPPED)。';
const batch = [
{
id: randomUUID(),
timestamp: isoAt(0),
type: 'trace-create',
body: {
id: traceId,
timestamp: isoAt(0),
name: 'synthetic-order-agent.run',
userId: 'demo_user_order_01',
sessionId: `sess_order_demo_${traceId.slice(0, 8)}`,
environment: 'development',
tags: ['agentbase-external', 'synthetic-demo'],
input: { content: userMsg.content },
output: { role: 'assistant', content: finalAssistantAnswer },
metadata: {
syntheticDemo: true,
note: 'Synthetic order inquiry trajectory demo; no real LLM invoked',
},
},
},
{
id: randomUUID(),
timestamp: isoAt(250),
type: 'generation-create',
body: {
id: firstGenId,
traceId,
name: 'llm.plan_tool_call',
startTime: isoAt(20),
endTime: isoAt(240),
model: syntheticModel,
modelParameters: { temperature: 0 },
input: {
tools,
messages: [systemMsg, userMsg],
},
output: firstAssistantToolCallMsg,
// 合成演示用量:每次模型调用独立记录 usage
usage: {
input: 58,
output: 24,
total: 82,
unit: 'TOKENS',
},
metadata: {
syntheticDemo: true,
stepRole: 'tool_decision',
},
},
},
{
id: randomUUID(),
timestamp: isoAt(420),
type: 'tool-create',
body: {
id: toolObsId,
traceId,
parentObservationId: firstGenId,
name: 'get_order_status',
startTime: isoAt(260),
endTime: isoAt(400),
level: 'DEFAULT',
input: { orderId: 'ORD-20261022-889' },
output: toolResultPayload,
metadata: {
// 与模型 output.tool_calls[].id 及后续 tool 消息的 tool_call_id 保持严格一致
toolCallId,
syntheticDemo: true,
},
},
},
{
id: randomUUID(),
timestamp: isoAt(720),
type: 'generation-create',
body: {
id: secondGenId,
traceId,
name: 'llm.final_answer',
startTime: isoAt(440),
endTime: isoAt(700),
model: syntheticModel,
modelParameters: { temperature: 0 },
// 如实上报第二次模型调用的完整上下文,由平台处理前缀重叠
input: {
tools,
messages: [
systemMsg,
userMsg,
firstAssistantToolCallMsg,
toolRoleMsg,
],
},
// output 仅记录本次真实生成的 assistant 回答,不混入输入 Prompt
output: {
role: 'assistant',
content: finalAssistantAnswer,
},
usage: {
input: 112,
output: 36,
total: 148,
unit: 'TOKENS',
},
metadata: {
syntheticDemo: true,
stepRole: 'final_response',
},
},
},
];
return { traceId, batch };
}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const retryable = (status) => [429, 500, 502, 503, 504].includes(status);
async function submitBatchWithRetry({ endpoint, projectId, writeKey, batch }) {
if (!Array.isArray(batch) || batch.length < 1 || batch.length > 100) {
throw new ExampleError('Events batch 必须包含 1–100 个事件');
}
// 同一进程中的重试始终复用这个请求体;不重建事件 ID。
const body = JSON.stringify({ batch });
const expected = new Set(batch.map((event) => event.id));
if (expected.size !== batch.length) throw new ExampleError('事件 ID 必须唯一');
for (let attempt = 1; attempt <= 3; attempt++) {
let response, text;
try {
response = await fetch(`${endpoint}/observability/ingestion`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Appwrite-Project': projectId,
'X-Appwrite-Key': writeKey,
},
body,
signal: AbortSignal.timeout(10000),
redirect: 'error',
});
text = await response.text();
} catch {
if (attempt === 3) throw new ExampleError('上报网络或读取响应失败:受理结果未确认');
await sleep(300 * 2 ** (attempt - 1));
continue;
}
if (retryable(response.status) && attempt < 3) {
await sleep(300 * 2 ** (attempt - 1));
continue;
}
if (![200, 207].includes(response.status)) {
throw new ExampleError(`上报未确认:HTTP ${response.status}`);
}
let payload;
try { payload = JSON.parse(text); }
catch { throw new ExampleError('上报响应非 JSON:受理结果未确认'); }
if (!payload || !Array.isArray(payload.successes) || !Array.isArray(payload.errors)) {
throw new ExampleError('上报响应缺少 successes/errors:受理结果未确认');
}
if (response.status === 207 || payload.errors.length > 0) {
// 不打印服务端原始错误正文;它可能包含提交内容。
const statuses = payload.errors.map((item) => Number.isInteger(item?.status) ? item.status : 'unknown');
throw new ExampleError(`批次未全部受理,HTTP ${response.status},失败状态 ${statuses.join(',')};保留原批次处理失败项`);
}
const acknowledged = new Set();
for (const item of payload.successes) {
if (!expected.has(item?.id) || acknowledged.has(item.id) ||
!Number.isInteger(item.status) || item.status < 200 || item.status >= 300) {
throw new ExampleError('上报成功项身份或状态不符合契约:受理结果未确认');
}
acknowledged.add(item.id);
}
if (acknowledged.size !== expected.size) throw new ExampleError('上报成功项未覆盖原批次:受理结果未确认');
return;
}
}
async function verifyTracePersistence({ endpoint, projectId, readKey, traceId, observations }) {
for (let poll = 1; poll <= 5; poll++) {
let response, payload;
try {
response = await fetch(`${endpoint}/observability/traces/${encodeURIComponent(traceId)}`, {
headers: { 'X-Appwrite-Project': projectId, 'X-Appwrite-Key': readKey },
signal: AbortSignal.timeout(8000),
redirect: 'error',
});
if (response.status === 200) payload = await response.json();
} catch { /* 此次读取未确认;仅在本次有限轮询内继续 */ }
if (response && response.status !== 200 && response.status !== 404 && !retryable(response.status)) {
throw new ExampleError(`回读失败:HTTP ${response.status},请核对读取权限与请求`);
}
if (payload?.trace?.id === traceId && Array.isArray(payload.observations)) {
const actual = new Map(payload.observations.map((item) => [item.id, item]));
const ready = observations.every((expected) => {
const item = actual.get(expected.id);
return item?.traceId === traceId && item.type === expected.type &&
(item.parentObservationId ?? null) === (expected.parentObservationId ?? null) &&
item.input != null && item.output != null;
});
if (ready) {
const trajectory = payload.trajectory;
return {
persisted: true,
// 只检查版本及非空步骤,不将其命名为“完整评估通过”。
hasAtifSteps: trajectory?.schema_version === 'ATIF-v1.8' &&
Array.isArray(trajectory.steps) && trajectory.steps.length > 0,
};
}
}
if (poll < 5) await sleep(1500);
}
return { persisted: false, hasAtifSteps: false };
}
async function main() {
const endpoint = normalizeEndpoint(process.env.APPBASE_ENDPOINT);
const projectId = process.env.APPBASE_PROJECT_ID?.trim();
const writeKey = process.env.APPBASE_API_KEY?.trim();
const readKey = process.env.APPBASE_OBSERVABILITY_READ_KEY?.trim();
if (!projectId || !writeKey) throw new ExampleError('缺少 APPBASE_PROJECT_ID 或 APPBASE_API_KEY');
const { traceId, batch } = buildSyntheticOrderTraceBatch();
console.log(`合成示例 Trace ID:${traceId}`);
await submitBatchWithRetry({ endpoint, projectId, writeKey, batch });
console.log('本批事件已全部受理;异步持久化与轨迹评估仍需分别验收');
if (!readKey) {
console.log('未配置独立读 Key:仅验证受理,未验证持久化');
return;
}
const observations = batch.filter((event) => event.type !== 'trace-create').map((event) => ({
...event.body, type: event.type === 'generation-create' ? 'GENERATION' : 'TOOL',
}));
const result = await verifyTracePersistence({ endpoint, projectId, readKey, traceId, observations });
if (!result.persisted) {
console.log('受理已确认,但在有限回读内未确认本次 Trace 与全部预期 Observation 落库');
process.exitCode = 2;
return;
}
console.log(`本次 Trace 和预期 Observation 已查到;存在非空 ATIF-v1.8 步骤:${result.hasAtifSteps}`);
console.log('仍需在 Console 核对消息、工具结果和所选评估器证据;本脚本不证明评估成功');
}
main().catch((error) => {
// 不输出未知异常正文,避免泄露请求或服务端返回内容。
console.error(error instanceof ExampleError ? error.message : '示例未完成验收:未知异常,受理与落库结果均需核对');
process.exitCode = 1;
});演示脚本与生产业务实现的区别
真实执行证据采集:本脚本使用合成的订单状态、模型名称和 Token 数值来演示事件关联结构;生产业务中应采集真实大模型网关响应、真实工具返回值与准确的
usage,并严格遵守数据最小化原则(对敏感字段脱敏,永不上报密钥、Cookie、原始请求头或未脱敏异常堆栈)。全路径有限上报保障:生产应用中,无论请求正常返回、抛出业务异常,还是遇到客户端取消或连接断开,都应在
finally分支中配合有界超时与有限重试完成事件上报(或记录脱敏的失败状态与traceId),既不要因无限重试阻塞主业务响应,也不要将未等待完成的后台任务直接当作持久化成功。
验收范围与重复执行
此脚本仅在同一进程内对网络异常、429 与所列可恢复 5xx 执行最多三次请求,并复用同一批次。207、非法响应或事件确认不完整时停止;生产调用方应保留原批次与失败项,修正后重试,避免丢失幂等 ID。重新启动本合成脚本会生成一条新的演示 Trace,不是跨进程重试方案。
回读核对本次三个 Observation 的实体 ID、类型、所属 Trace、父节点及非空输入输出,不以节点总数代替身份校验。这仍不是内容完全一致、ATIF 已完整或模型质量通过的证明。示例未执行真实模型调用;运行它会向明确指定的项目写入合成数据,请使用测试项目。
先阅读产品手册中的轨迹概念与四层验收,再查阅消息与工具关联格式。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
批量上报(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(摄取状态)