Docs
文档目录

可观测

这是什么 / 何时用

Observability 覆盖两件事:

  1. AI 观测上报:把 Trace / Observation / Generation / Score(Langfuse 风格事件模型)从受控服务端、CLI、Function 或 Site SSR 上报到当前项目,用于 Agent/LLM 调用链排障、token 用量与质量评估。

  2. 查询面:按 Trace 查事件树、按 Session/User 聚合、指标查询;以及独立的 Trace 日志查询(Function/动态 Site 的 stdout/stderr,按 W3C Trace ID 或 Execution ID)。

前置

选择接入方式

已有条件接入方式适用边界
已使用 OpenTelemetry SDK / Exporter标准 exporter → OTLP/HTTP Trace 入口JSON 或 protobuf,可选 gzip;不支持 OTLP/gRPC
Agentbase Node.js 服务端应用精确安装 agentbase-node-sdk@2.12.0,调用 createIngestion普通请求按本页配置禁止跳转;OTel 原始请求暂使用 REST
自行控制 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 的权限。

使用骨架

  1. 批量上报: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。

  2. 处理返回:全部成功 → HTTP 200;任一失败 → HTTP 207 Multi-Status,必须逐项检查 errors[],不能只看请求是否抛错。200/207 都不等于已持久化(异步 worker 落库):回读 404 时做有上限短轮询,仍无则按"已接收但未验证持久化"处理。

  3. 重试策略:429 与可恢复 5xx 用有上限指数退避并复用原外层 id;schema/权限类 4xx 不盲重试;超 100 条按 create-before-update 顺序分批。

  4. OTel traces 上报:使用下方 REST 的 OTLP HTTP 入口(JSON/protobuf,可选 gzip);Node SDK 2.12 的原始请求不受本页普通请求跳转配置保护。已有 OpenTelemetry SDK 可使用 exporter;不支持 OTLP gRPC。

  5. 查询:getTrace / listTraces / getSession / listSessions / getUser / listUsers / queryMetrics / listScores / listScoreConfigs;状态 getStatus。

  6. Trace 日志查询:observability.listLogs({ query, from, to, limit, offset })(from、to、limit、offset 均可选)——query 必填且只允许一个 traceId:<value> 或 executionId:<value>;from 默认 to−3600(Unix 秒),to 默认当前时间,时间窗最大 24 小时;limit 1–100(默认 25);offset 0–1000。

关键参数与返回

错误与边界

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 类别差异

示例指引

完整 Agent 轨迹上报示例

以下提供一个基于 Node.js 18+ 原生 fetch 与 node:crypto 的完整 ESM 脚本(无需安装额外依赖)。本示例直接调用公开 REST 接口(POST /v1/observability/ingestion 与可选的回读接口 GET /v1/observability/traces/{traceId}),用于演示原始事件的关联结构及分层验收方式,并非某个 SDK 版本内置的高层封装方法。

场景与事件结构说明

示例采用合成订单查询场景(用户查询订单 ORD-20261022-889 的物流状态):

  1. 第一次模型调用(generation-create):接收 system 与 user 消息,模型输出 assistant 的工具调用请求 tool_calls(调用函数 get_order_status);

  2. 工具执行(tool-create):通过 metadata.toolCallId 关联同一工具调用 ID,返回订单已发货状态;

  3. 第二次模型调用(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 用量均为合成演示数据,不连接或冒充真实大模型服务,也不代表真实模型质量评估通过。

运行条件与环境变量

环境变量必填所需权限 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;
});

演示脚本与生产业务实现的区别

验收范围与重复执行

此脚本仅在同一进程内对网络异常、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 顺序分批。

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 prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}
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 上报

通过 REST 发送原始 OTLP body;OpenTelemetry exporter 也可使用同一 HTTP 入口。

Node SDK 2.12 的 createOtelTraces 走独立原始请求,未受本页普通请求的防跳转配置保护;安全配置核实前,请使用下方 REST 步骤。

查询与 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 });

2.12.0 — 集合分析与报表

SDK 新增 createTraceAnalysis/listTraceAnalyses/getTraceAnalysis、analyzeTraceCollection 与三类 POST 报表查询。集合分析需要 scores.read 和 traces.read;datasetId/datasetRunId 指定运行来源时还需 datasets.read。requestId 使用稳定 UUID,重试保留,主动重跑换新 UUID。每组 2–100 条不同 Trace、最多 500 条关联评分,至少两条有可用根因分析。报表 scope 为 observability.metrics.read,读取 Trace 可传 compact。HTTP 202 仅为接受,按 analysisId 查询,失败的详情读取不能自动再次创建。

import { Client, Observability } from 'agentbase-node-sdk';
const client = new Client().setEndpoint(process.env.AGENTBASE_ENDPOINT)
 .setProject(process.env.AGENTBASE_PROJECT_ID).setKey(process.env.AGENTBASE_API_KEY);
{
  const prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}
const obs = new Observability(client);
const analysis = await obs.createTraceAnalysis({
 datasetId: process.env.AGENTBASE_DATASET_ID,
 datasetRunId: process.env.AGENTBASE_DATASET_RUN_ID,
 requestId: crypto.randomUUID(), name: 'customer-support-run-review' });
console.log(analysis);