AgentbaseDocs
文档目录

记忆审计日志与链路定位

功能概述与核心场景

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

在 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)**。

flowchart TB
    subgraph RequestEntry["1. 客户端与服务端调用入口"]
        WriteReq["数据面变更与检索请求\n创建 / 更新 / 删除 / 搜索 / 召回 / 蒸馏 / 确认"]
        ReadPoll["高频普通读取与状态轮询\ngetMemory / listMemories / getJob 轮询"]
        ConfigReq["控制面配置与生命周期变更\nPUT /memory/config/{ns} & Pipeline 发布"]
    end

    subgraph AuditAndConfig["2. 审计与配置历史层 (OceanBase 项目表)"]
        Sanitizer["递归脱敏与载荷截断器\n自动遮蔽密钥/Token/Cookie/密码"]
        AuditStore[("数据面请求审计表 (memory_events)\nGET /v1/memory/audits\n记录 requestId / jobId / actor / status / durationMs")]
        ConfigHistory[("配置版本与事件历史\nGET /memory/config/{ns}/history\n记录 version / lastEventId / etag / actor / reason")]
    end

    subgraph TraceLayer["3. 端到端链路追踪层 (Observability / AgentOps)"]
        TraceHeader["响应头关联: X-AppBase-Trace-Id\n(优先继承 W3C traceparent / X-Trace-ID)"]
        MemoryTraces["Memory 专属 Trace 过滤视图\n/observability/traces?tag=capability%3Amemory\n(APPBASE_TRACE_TAGS.capabilityMemory)"]
        StageSpans["细粒度阶段 Observation\nqueueDurationMs / executionDurationMs\nmemory.model.call & memory.ingest.stage_failed"]
    end

    WriteReq --> Sanitizer --> AuditStore
    ConfigReq --> ConfigHistory
    WriteReq --> TraceHeader --> MemoryTraces
    ReadPoll --> TraceHeader
    MemoryTraces --> StageSpans

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

观测维度查询入口 / 接口记录范围与核心字段不记录的内容与设计边界
配置变更历史(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. 在控制台用“请求审计”核对写入、检索与删除结果

截图未公开:原图可能包含账号或资源标识。

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

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):


常见问题与排障(FAQ)

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

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

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


相关文档