Docs
文档目录

记忆审计日志与链路定位

功能概述与核心场景

记忆审计与链路定位(Memory Audit & Trace,控制台页签为 审计 与 Trace)是 Agentbase Memory(v2.10.0)面向企业安全合规、变更追溯与生产性能排障的核心观测体系。在多团队协作与高频智能体交互中,运维与架构团队需要清晰回答三类问题:

  1. 配置变更历史追溯:谁在什么时间、出于什么原因(reason)修改了哪一个 Memory 配置命名空间或 Pipeline,对应的 lastEventId 与 ETag 是什么?

  2. 业务数据面操作审计:某次记忆写入(POST /v1/memory/memories)、批量删除(DELETE)、检索召回(search / recall)或经验蒸馏(distillations)是否成功执行、关联了哪个异步任务 ID(jobId)、耗时多少毫秒?

  3. 端到端调用链路追踪(Trace):某次异步写入或混合检索在 API 受理、队列等待、OceanBase 向量查询与 dashscope-prod 模型调用(qwen-plus / text-embedding-v3 / qwen3.7-text-rerank)各阶段分别消耗了多少时间与 Token?

在 Agentbase 企业智能中台(69c6d1aa00062e6bb60)的标杆项目 企业智能客服与知识中台(enterprise-ai-hub-210)中,系统默认开启请求审计(policy.requestAuditEnabled: true),并通过统一的 X-AppBase-Trace-Id 响应头与 APPBASE_TRACE_TAGS.capabilityMemory(即 capability:memory 标签)将 Memory 页面与 智能体运维(Observability / AgentOps) 无缝打通。


核心概念与架构

Agentbase Memory 的审计与可观测架构分为三个相互补充的层次:控制面配置版本历史、数据面业务请求审计(memory_events) 以及 OpenTelemetry / Langfuse 分布式链路追踪(Traces)。

记忆审计日志与链路定位:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

三类观测数据的职责与边界对比

观测维度查询入口 / 接口记录范围与核心字段不记录的内容与设计边界
配置变更历史(Config History)配置 → 配置版本 或 GET /v1/projects/{projectId}/memory/config/{namespace}/history记录每次配置保存与回滚的版本号(version)、事件 ID(lastEventId)、etag、操作者(actor)、变更原因(reason)与前后 Diff。不记录未保存的页面表单输入或样例试跑原文。
业务请求审计(Request Audit)记忆 → 审计 或 GET /v1/memory/audits记录记忆创建、更新、单条/批量删除、搜索、统一召回、反馈/观察、导入导出提交、画像提取与上下文/知识治理操作;包含 requestId、jobId、userId、HTTP 状态码与耗时。不逐次记录普通单条读取(getMemory)、列表浏览(listMemories)、统计查询和异步任务状态轮询(getJob),防止轮询风暴淹没关键业务变更审计。
记忆链路追踪(Memory Trace)记忆 → Trace(跳转至 智能体运维 → 链路,带 tag=capability:memory)记录 API 受理、后台队列等待、分阶段执行(事实抽取、向量化、冲突检测、Rerank)、模型 Token 消耗与网关错误码(gatewayStatus、errorCode)。受平台全局开关 agentops.enabled 与采样率(policy.observability.successSampleRate)控制;未采样时不代表业务请求未执行。

功能入口与权限矩阵

控制台入口与权限矩阵

控制台入口位于:项目 enterprise-ai-hub-210 → 记忆(Memory) → 审计 页签,以及右侧紧邻的 Trace 页签。

功能动作控制台入口REST API 端点 / 跳转路由所需权限 Scope
查询业务请求审计列表记忆 → 审计 页签搜索栏GET /v1/memory/auditsmemories.read
开关项目请求审计记忆 → 配置 → 基础配置PUT /v1/projects/{projectId}/memory/config/policy(requestAuditEnabled)projects.write
查看配置变更历史与 ETag记忆 → 配置 → 展开配置版本GET /v1/projects/{projectId}/memory/config/{namespace}/historyprojects.read
一键跳转查看 Memory Trace记忆 → Trace 页签按钮路由跳转:/console/project-{region}-{project}/observability/traces?tag=capability%3Amemoryobservability.traces.read

请求级 Trace ID 传递与关联机制

  1. X-AppBase-Trace-Id 响应头: 所有经过 Agentbase /v1/memory/* 门面的成功响应(HTTP 2xx)都会在 HTTP 响应头中返回 X-AppBase-Trace-Id(32 位非全零小写十六进制关联 ID)。服务端优先采纳调用方传入的合法 W3C traceparent 请求头,其次采纳合法 X-Trace-ID;若均未传入则自动生成新 ID。

  2. APPBASE_TRACE_TAGS.capabilityMemory 标签路由: 在控制台点击 Memory → Trace 页签时,前端通过 APPBASE_TRACE_TAGS.capabilityMemory 常量(值为 "capability:memory")自动跳转到可观测链路列表并应用标签过滤,精准筛选出当前项目由托管 Memory 服务产生的全部同步与异步轨迹。

  3. 内容捕获双重门禁(captureContent): Memory Trace 是否在 Span 中记录原始记忆文本与提示词内容,受平台全局开关 agentops.memoryCaptureContentEnabled(默认 true)与项目级配置 policy.observability.captureContent 的双重约束。只有两者同时开启时才捕获内容,否则敏感载荷展示为 [REDACTED]。


功能详解与操作指南

1. 在控制台用“请求审计”核对写入、检索与删除结果

  1. 登录 Agentbase 控制台,进入项目 企业智能客服与知识中台(enterprise-ai-hub-210),打开 记忆(Memory) → 审计 页签。

  2. 在顶部筛选栏输入过滤条件:

    • 可按 请求 ID(requestId)、目标用户 ID(userId,如 user_zhangwei_001)、资源 ID(如 memoryId) 或 操作名称(operation) 搜索;

    • 若排查某次异步智能写入、导入导出或蒸馏任务,可在任务过滤框中输入精确的 jobId;

    • 支持按结果状态(成功 / 失败)快速筛选。

记忆审计日志视图(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

  1. 单击展开目标审计记录,核对以下关键排障信息:

    • 请求元数据:HTTP 方法、请求路径、HTTP 状态码、操作主体(actor)、目标用户(userId)与关联资源 ID;

    • 脱敏请求载荷:系统会对请求参数中的 API Key、Token、密码、Cookie 等凭据字段执行自动递归脱敏,并对超大正文进行安全截断(切勿因此主动把业务机密写入 metadata 依赖事后脱敏);

    • 异步任务终态与三段耗时:对于异步写入任务,结合 GET /v1/memory/jobs/{jobId} 核对排队耗时(queueDurationMs)、实际执行耗时(executionDurationMs)与端到端总耗时(totalDurationMs),区分“API 已受理入队(HTTP 202)”与“后台模型最终执行完成(completed / partial_failed / failed)”。

2. 审计与配置历史 API 参数详解及调用示例

(1)查询业务请求审计(GET /v1/memory/audits)

查询参数 / 响应字段类型说明与使用约束
limit(查询参数)integer单页返回条数,取值 1~100(默认 25)。
cursor(查询参数)string分页游标,原样传回上一页响应的 nextCursor。
jobId(查询参数)string按特定异步任务 ID 精确过滤关联审计记录。
userId / operationstring按目标业务用户 ID(如 user_zhangwei_001)或操作类型过滤。
audits(响应字段)array匹配的审计事件列表,保存在项目专属的 memory_events 表中,受 retention.auditEventDays 保留期管理。
scanned / truncatedinteger / bool本次查询扫描的底层事件数及是否触发扫描上限截断。
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"

# 1. 查询 user_zhangwei_001 最近的记忆写入与检索审计日志
curl -fsS --get "${APPBASE_ENDPOINT}/memory/audits" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  --data-urlencode "userId=user_zhangwei_001" \
  --data-urlencode "limit=20" | jq .

# 2. 按异步写入任务 jobId 精确核对审计结果
curl -fsS --get "${APPBASE_ENDPOINT}/memory/audits" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  --data-urlencode "jobId=job_01hxyz9876543210" | jq .

(2)核查配置变更历史(lastEventId、etag、actor、reason)

当需要审计某项配置(如 policy、provider 或 evolution)何时被谁修改时,调用配置历史接口:

# 查询 policy 命名空间的配置变更审计历史
curl -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/policy/history" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" | jq .

典型响应结构包含每次变更的完整治理元数据:

{
  "component": "memory",
  "scopeType": "project",
  "namespace": "policy",
  "currentVersion": 3,
  "lastEventId": "cfg_evt_01j9k2m4n6p8q0r2",
  "etag": "\"v3-8f9e1d2c3b4a\"",
  "items": [
    {
      "version": 3,
      "eventId": "cfg_evt_01j9k2m4n6p8q0r2",
      "etag": "\"v3-8f9e1d2c3b4a\"",
      "actor": "admin:69c6d1aa00062e6bb60",
      "reason": "开启搜索重排 rerankEnabled 并设置慢查询追踪阈值 slowThresholdMs=800",
      "createdAt": "2026-10-22T09:30:00.000Z"
    }
  ]
}

3. 从 Memory 跳转 Trace 定位慢请求与模型调用异常

当在 审计 页签发现某次请求耗时偏高或异步任务出现重试时,单击 Memory → Trace 页签进入可观测链路视图(自动过滤 tag=capability:memory):

  1. 核对时间窗口与关联 ID:在链路列表搜索框中输入响应头返回的 X-AppBase-Trace-Id(若在九州云图环境开启了 _APP_OBSERVABILITY_YUNTU_TRACE_LINK_ENABLED=enabled,也可直接搜索 metadata.cloudAtlasTraceId 对应的 SOFA-TraceId)。

  2. 分析阶段瀑布图(Timeline)与模型调用:

    • 对于异步智能写入(infer=true):同一个 jobId 的多次重试沿用同一个根 Trace ID,每次 attempt 生成独立子 Span;展开 memory.model.call 节点可查看调用 qwen-plus 或 text-embedding-v3 的精确耗时、Prompt/Completion Token 消耗;

    • 对于阶段失败诊断:若某阶段出错,memory.ingest.stage_failed 事件会直接记录 errorClass、errorCode(如 LLM_RATE_LIMITED、LLM_TIMEOUT、LLM_INVALID_JSON)、retryable 以及 gatewayStatus,无需登录服务器翻查容器日志即可完成根因定位;

    • 对于在线记忆检索(search):若项目未开启画像改写(profileRewriteEnabled=false)且未开启重排(rerankEnabled=false),检索链路仅包含 Embedding 向量化与 OceanBase 确定性检索 Span,不会出现 Chat Generation 节点,属于正常的高性能确定性检索路径。


常见问题与排障(FAQ)

1. 为什么我调用了 GET /v1/memory/memories 查询列表或轮询 GET /v1/memory/jobs/{jobId},但在“审计”页签里找不到对应的记录?

2. 审计记录缺失或 Trace 列表中查不到某次成功的记忆操作,是否说明该操作没有生效?

3. 如何让智能体运维的“指标分析(Metrics)”只统计 Memory 链路产生的模型 Token 与延迟?


相关文档