AgentbaseDocs
文档目录

可观测

这是什么 / 何时用

Observability 覆盖两件事:

前置

选择接入方式

已有条件接入方式适用边界
已使用 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?) 保留原始 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 的权限。

使用骨架

关键参数与返回

错误与边界

2.7.0 增量:轨迹评估与监控指标

以下能力落在 Console 评估面与评估 worker / 部署监控侧,公开摄取与查询契约(本页端点)无变化(spec v2.6.0 → v2.7.0 observability 段无新增端点与参数变更):

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 列表与评分分析

2.10.0 增量:知识索引质量评估与 Prompt 解析

SDK 类别差异

示例指引

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

批量上报(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 顺序分批。

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[],不能只看是否抛错

OTel Traces 上报

SDK 直传原始 OTLP body 并返回原始响应(本页给 Node SDK 与 REST 形态);其他语言可让 OpenTelemetry exporter 直连同一 REST 端点。

// createOtelTraces(body, contentType?) —— OTLP HTTP 形态(JSON/protobuf,可选 gzip)
const raw = await observability.createOtelTraces(otelBody);
// 不是 OTLP gRPC endpoint;适合接 OpenTelemetry exporter

查询与 Trace 日志

getStatus 为状态探测;Trace 日志查询是独立数据面(scope traceLogs.read)。

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 });

事实源