Docs
文档目录

记忆端到端调用链路追踪(Memory Traces)

功能概述与核心场景

记忆端到端调用链路追踪(Memory Traces) 是 Agentbase Memory 与智能体运维可观测中心(AgentOps / Observability)深度打通的全链路性能剖析与故障诊断能力。在企业级智能体生产环境——例如 Agentbase 企业智能中台(组织 ID:69c6d1aa00062e6bb60)下的示例项目 企业智能客服与知识中台(项目 ID:enterprise-ai-hub-210,基于 OceanBase Shared V2 存储模式)中,一次看似简单的记忆读写背后往往跨越多个异构计算阶段:

当研发或 SRE 运维人员需要定位以下核心生产问题时:

  1. 检索延迟拆解:“为什么某次 hybrid 混合检索总耗时 420ms?时间究竟花在 OceanBase 向量索引扫描,还是上游 dashscope-prod 的 qwen3.7-text-rerank 重排网络往返?”

  2. 异步抽取与去重归因:“为什么 VIP 架构师 user_zhangwei_001 的多轮会话提交 infer=true 后未新增记忆?是模型判定 NONE(重复跳过),还是触发了 LLM_RATE_LIMITED 正在后台重试?”

  3. Token 成本核算与慢调用治理:“后台知识蒸馏(distillations)与 Dreaming 聚合分别消耗了多少 Prompt / Completion Tokens?哪些慢请求超过了 slowThresholdMs?”

在控制台 记忆(Memory) 页面单击 记忆链路追踪按钮,即可跳转至项目可观测性链路追踪视图;初始筛选为 tag=memory,实现从业务 X-AppBase-Trace-Id、jobId、userId 到毫秒级 Span 瀑布图(Waterfall)与大模型 Generation 载荷的端到端穿透定位。


核心概念与架构

Memory 调用链路追踪通过统一的分布式追踪上下文(W3C traceparent / X-Trace-ID -> X-AppBase-Trace-Id),将 同步 API 接入平面、异步队列与 Pipeline Worker 平面、OceanBase 存储检索平面 以及 Models / LLM Gateway 模型调用平面 串联为完整的 OpenTelemetry / Langfuse Trace Tree:

记忆端到端调用链路追踪(Memory Traces):流程示意,不是运行截图

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

查看流程图大图

1. 端到端 Trace ID 传播与关联协议

Agentbase Memory 在所有 /v1/memory/* 接口上遵循确定性的 Trace ID 继承与回传规则:

传播环节Header / 字段名称格式规范与优先级规则生产排障用途
入站请求头(优先级 1)traceparent标准 W3C Trace Context 格式(00-<32hex trace-id>-<16hex parent-id>-<2hex flags>)当上游微服务或智能体编排层已开启 OpenTelemetry 时,Memory 自动提取其中的 32 位十六进制 trace-id 作为本次记忆操作的关联 Trace ID,实现全栈单链合一。
入站请求头(优先级 2)X-Trace-ID32 位非全零小写十六进制字符串(^[0-9a-f]{32}$)当未传 traceparent 时,优先采纳调用方显式传入的合法 X-Trace-ID。
出站响应头(权威回执)X-AppBase-Trace-Id32 位非全零小写十六进制字符串(如 7a8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e)若调用方未传上述请求头,平台自动生成全新 Trace ID,并在所有成功响应头中统一通过 X-AppBase-Trace-Id 返回;在异步重试(attempt 1..N)期间,同一个 jobId 始终沿用同一个根 Trace ID。
接口标签筛选示例capability:memory链路列表接口筛选值可按标签过滤;实际标签以链路详情为准。控制台入口的初始筛选值为 tag=memory。

2. 同步检索 vs 异步写入/蒸馏的 Span 树结构拆解

在 Trace 详情抽屉的瀑布图(Waterfall)中,不同业务路径会呈现层级 Span 树结构。下表的提供商、模型及维度仅为示例,实际以项目配置为准:

业务链路类型核心阶段 Span / Generation 节点名称观测类型 (type)关联模型 / 存储组件关键观测属性与诊断指标
同步混合检索与召回
(search / recall)
memory.query_rewrite(开启画像改写时)GENERATIONdashscope-prod / qwen-plus记录原始 query、结合 user_zhangwei_001 画像改写后的查询词及 Token 消耗。
memory.embedding.querySPANdashscope-prod / text-embedding-v3记录 1024 维稠密向量与 Sparse 稀疏向量编码耗时(支持命中 queryEmbeddingCache 缓存)。
memory.storage.hybrid_querySPANOceanBase Shared V2记录项目独占表组 _<projectSequence> 上的向量 HNSW 扫描、全文检索、2 跳图遍历(graph)及 RRF 融合耗时。
memory.rerank(当 policy.rerankEnabled=true)SPANdashscope-prod / qwen3.7-text-rerank记录候选集重排耗时与得分分布;若重排超时降级,记录 degraded.rerank=true。
异步写入 / 蒸馏 / Dreaming
(infer=true / distillations / contexts/runs)
memory.job.queue_waitSPAN(或元数据)异步任务队列记录 queueDurationMs(从 HTTP 202 入队到 Worker 实际开始执行的排队等待毫秒数)。
memory.media.parse(多模态写入时)GENERATIONdashscope-prod / qwen-vl-max记录解析 agent_multimedia_bucket 中 PNG/JPEG/WebP/PDF 文件的耗时与提取字节数。
memory.pipeline.fact_extraction
memory.pipeline.skill_extraction
memory.pipeline.experience_extraction
GENERATIONdashscope-prod / qwen-plus (tool_call)普通诊断链路仅记录调用元数据;满足内容采集条件的独立评估链路可能包含原始输入输出。
memory.pipeline.conflict_detection
memory.pipeline.skill_merge
GENERATIONdashscope-prod / qwen-plus记录与存量相似记忆/技能比对后输出的 ADD / UPDATE / DELETE / NONE / MERGE 决策动作。
memory.ingest.stage_failed(异常诊断节点)EVENT / SPAN故障阶段定位器当任一阶段报错时记录 errorClass、errorCode(如 LLM_RATE_LIMITED、LLM_TIMEOUT、LLM_INVALID_JSON)、retryable 与 gatewayStatus。

功能入口与权限矩阵

在目标项目的 记忆 页面打开 记忆链路追踪按钮,进入项目链路页面;初始筛选为 tag=memory。

功能动作控制台 UI 入口与路由REST API 端点Server SDK / 头部契约所需 RBAC / API Key Scope跨模块关联依赖
从记忆工作台跳转链路页记忆链路追踪按钮GET /v1/observability/traces(筛选条件依实际需要设置)控制台路由导航控制台成员 + observability.traces.read联动 智能体运维 → 链路追踪
查看单条 Trace 的 Span 瀑布图链路列表点击目标 Trace 行展开详情抽屉GET /v1/observability/traces/{traceId}HTTP GETobservability.traces.read展示 memory.model.call 与 OceanBase 检索子 Span
配置 Memory 可观测采样与慢阈值记忆 → 配置 → 基础配置 (policy)GET/PUT /v1/projects/{projectId}/memory/config/policy控制面 HTTP API具备管理权限的 Console 用户会话;按接口核对操作权限管理 observability.enabled、successSampleRate、slowThresholdMs、captureContent
查看 Memory 相关指标智能体运维 → 指标 → Observations → 仅看 Memory (memoryOnly)POST /v1/observability/metricsJSON 请求体中的 query;控制台筛选由查询适配层转换observability.metrics.read仅针对 Observations 视图;详见指标监控与分析报表
交叉核对业务请求回执与任务终态记忆 → 操作审计或审计页签(?tab=audit)GET /v1/memory/audits、GET /v1/memory/jobs/{jobId}memory.listAudits / memory.getJob审计:项目管理员会话或当前项目 API Key(memories.read);任务查询:memories.read与 记忆审计日志 互为排障闭环

功能详解与操作指南

步骤一:从记忆控制台跳转并筛选链路

  1. 登录 Agentbase 控制台,选择目标项目,在左侧导航栏单击 记忆。

  2. 单击页面顶部的 记忆链路追踪按钮。

  3. 浏览器跳转到链路页并带有 tag=memory。筛选条件可在链路页调整;该值不同于下方接口示例的 capability:memory。

  4. 在列表顶部筛选区可进一步叠加精细化定位条件:

    • Trace ID 搜索:粘贴业务响应头返回的 X-AppBase-Trace-Id(如 7a8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e);

    • User ID 过滤:输入 user_zhangwei_001 或 user_lina_002,仅查看特定客户的记忆写入、画像更新与召回链路;

    • Session ID 过滤:输入业务会话标识(如 sess_ticket_TK_20261022_001),串联查看同一工单会话内历次记忆推断与上下文召回的完整轨迹序列。

步骤二:下钻剖析 Span 瀑布图(排查延迟瓶颈与 skipReason)

单击列表中的任意一条 Memory Trace 记录,右侧详情面板将展示完整的 Span 树与阶段耗时瀑布图。在实际运维中,可按以下四步法则快速定位问题:

  1. 区分 queueDurationMs 与 executionDurationMs:

    • 若异步写入或蒸馏任务端到端耗时较长,先观察根 Trace 创建时刻到第一个 Worker 执行 Span 之间的空白等待段(queueDurationMs)。若 queueDurationMs 显著偏高而 executionDurationMs 正常,说明项目正在进行大批量导入(batch / imports)触发了后台队列削峰排队,而非模型或数据库变慢。

  2. 定位在线混合检索(search / recall)的耗时大头:

    • 对比 memory.embedding.query(调用 dashscope-prod 的 text-embedding-v3)、memory.storage.hybrid_query(OceanBase 向量 + 全文 + 图检索)与 memory.rerank(调用 qwen3.7-text-rerank)三个子 Span 的耗时占比;

    • 若 memory.rerank 耗时接近或超过预算,可检查是否将候选召回上限设置过大,或结合渐进式检索的 deadlineMs: 450 实现硬超时保护。

  3. 理解何时不会出现 LLM GENERATION 节点(skipReason):

    • 当查看一次 infer=false 直接写入、一条设置了 handlingPolicy="no_model" 的合规记录,或一次未开启画像改写(profileRewriteEnabled=false)的在线检索时,Span 树中没有 GENERATION 大模型生成节点属于完全符合预期的正常行为,Span 元数据会明确记录跳过原因(如 skipReason: "request_infer_false" 或 "policy_no_model")。

  4. 定位异步任务失败与重试(memory.ingest.stage_failed):

    • 当某次 infer=true 写入或知识蒸馏因上游模型限流(HTTP 429)触发重试时,同一个 jobId 的多次尝试(attempt=1, 2...)会聚合在同一条根 Trace 下;展开带警告/错误标记的 memory.model.call 或 memory.ingest.stage_failed 节点,可直接读取 errorCode(如 LLM_RATE_LIMITED、LLM_INVALID_JSON)、retryable: true/false 及 gatewayStatus。

步骤三:配置隐私内容捕获双门禁(captureContent)与智能采样策略

在企业生产环境中,并非所有项目都希望将客户原始对话和记忆正文写入可观测链路日志;同时,超高并发项目也无需对 100% 的常规快速成功请求全量采集 Trace。Agentbase Memory 在 policy.observability(位于 /v1/projects/{projectId}/memory/config/policy)中提供了精细的采样与隐私控制开关:

配置字段路径类型默认值 / 范围治理语义与生效机制
policy.observability.enabledbooleantrue项目级 Memory Trace 导出开关(需平台全局 agentops.enabled=true 同时开启)。
policy.observability.successSampleRatenumber0.0 ~ 1.0(默认 1.0)普通成功请求的采样率。例如设为 0.2 表示对耗时正常的成功请求按 20% 概率采样。注意:失败请求(Error)与超过慢阈值的慢请求(Slow)不受采样率丢弃,始终优先采集。
policy.observability.slowThresholdMsinteger正整数(如 800 ms)超过阈值的请求不因成功采样率被丢弃,但导出仍可能失败或丢弃,不能保证最终有 Trace 可查。
policy.observability.captureContentbooleanfalse / true内容采集受平台 agentops.memoryCaptureContentEnabled 与项目 policy.observability.captureContent 共同控制。普通诊断 Generation 不包含模型输入输出;启用内容采集时,独立评估链路可能记录原始输入输出,必须在上报前脱敏,不能依赖自动替换或递归清洗。

普通读取和列表通常不生成请求审计记录;缺少审计记录不能证明未发生请求。

步骤四:通过请求头注入自定义 Trace ID 并使用 API 查询验证

下面演示如何在业务服务端调用 Memory 搜索接口时主动传入 W3C traceparent(或读取返回的 X-AppBase-Trace-Id),随后通过可观测性 REST API 查询生成的完整链路详情:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY for the target environment}"

  # 1. 调用混合检索接口,传入自定义 W3C traceparent 并捕获响应头中的 X-AppBase-Trace-Id
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -D /tmp/memory_trace_headers.txt \
    -X POST "${APPBASE_ENDPOINT}/memory/memories/search" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "traceparent: 00-7a8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e-1a2b3c4d5e6f7a8b-01" \
    -H "Content-Type: application/json" \
    --data '{
      "userId": "user_zhangwei_001",
      "scope": "user",
      "query": "OceanBase Shared V2 向量索引 HNSW 参数与排障偏好",
      "searchMode": "hybrid",
      "limit": 5
    }' | jq .

  # 提取响应头中的权威 X-AppBase-Trace-Id
  TRACE_ID="$(grep -i '^x-appbase-trace-id:' /tmp/memory_trace_headers.txt | awk '{print $2}' | tr -d '\r')"
  echo "Captured X-AppBase-Trace-Id: ${TRACE_ID}"

  # 2. 按 capability:memory 标签与 userId 查询项目的 Memory 轨迹列表
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS --get "${APPBASE_ENDPOINT}/observability/traces" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    --data-urlencode "tag=capability:memory" \
    --data-urlencode "userId=user_zhangwei_001" \
    --data-urlencode "limit=10" | jq .

  # 3. 根据捕获的 TRACE_ID 查询单条 Trace 的完整 Span 瀑布树与 Generation Token 明细
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT}/observability/traces/${TRACE_ID}" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     | jq .
)

常见问题与排障(FAQ)

1. 为什么在“记忆 → 审计”中看到了成功的请求记录,但点击“Trace”后在链路列表中搜不到对应的 X-AppBase-Trace-Id?

2. 为什么 Memory Trace 的 Generation 节点没有模型输入和输出?

3. 为什么在“智能体运维 → 指标(Metrics)”中看到的模型调用次数与 Token 消耗高于业务代码直接调用 Chat 接口的统计值?


相关文档