[Discussion] Astra Trace 现状及其与 OpenInference / Langfuse 的数据映射

[loveRhythm1990]

背景与范围

这里讨论的 trace 是面向 Agent/Loop 可观测性的执行记录：它应当能够把一次执行中的父子步骤、因果关系、时间、输入输出、状态和评价信号重新关联起来，用于回答“Agent 为什么这样做、在哪一步失败、怎样改善 Loop”。

这个定义比普通日志更窄，也比代码中所有名为 trace 的对象更具体：

• Trace：一次完整执行的因果图。其边界可以是一个 Turn，也可以是一个 Agent Run；Astra 当前没有一个单一数据对象表达这个边界。
• Span / Observation：图中的一次有起止时间的操作，例如 Agent Run、LLM 调用、Tool 调用、检索或 Guard 判断。
• Event：Span 内的瞬时事实，例如 retry、stall、tool rejected。
• Log：面向排障的文本或结构化记录；它可能带 trace/span id，但不等于 Agent Trace。
• Snapshot / Artifact：某个时点的上下文、Prompt、Checkpoint 或完整请求响应，通常作为 Trace 的补充材料。
• Evaluation：作用于 Trace、Span、Session 或具体输出的分数、标签、解释与反馈。

本文只盘点 Astra 当前已经记录的数据、存储位置和关联方式，并以 OpenInference 与 Langfuse 作为对照，说明如果做语义类比或数据导出，需要怎样映射。本文不预设 Astra 要采用哪套规范，也不讨论实施方案。

范围不包含 Astra CLI 在用户本地生成的日志或启动记录。下文提到的文件均指 server/runtime 写入的服务端本地状态。

结论摘要

Astra 已经记录了构成 Agent Trace 所需的大部分素材，但它们目前分散在多种模型和存储中：

1. agent_events 最接近可查询的 Turn Trace 主体，保存 Turn、LLM Round、Tool Call、子 Agent 生命周期及关联标识。
2. Session Journal 和 StepRecorder 保存更细的执行时间线与控制流信号，但主体是服务端 JSONL/Checkpoint 文件。
3. 完整 LLM 请求响应、Prompt 组装、Context Assembly、Harness、Decision Audit 和 Evaluation 分别使用独立的文件、表或内存结构。
4. 当前 GET /sessions/{session_id}/turns/{turn_id}/trace 只从 agent_events 重建 Turn 视图，并不会自动拼入上述所有数据。
5. 现有记录总体是“事件 + 快照 + 附件”的集合，并不是 OpenTelemetry/OpenInference 意义下已经成形的 Span 树：部分操作缺少稳定的 span id、明确的 start/end/status 以及跨存储的一致父子关系。

Astra 当前有哪些 Trace/相关记录

1. Rust tracing / OpenTelemetry：基础设施可观测性

相关代码：

• crates/astra-logging/src/lib.rs
• crates/astra-logging/src/otel.rs
• crates/runtime/src/server/request_trace.rs

它记录 HTTP request span、access log、x-request-id 以及常规 Rust tracing 日志。默认输出到 stderr；启用 OTLP 时发送给外部 OpenTelemetry Collector/后端。

这部分主要回答服务请求、错误和性能问题。Astra 自身不会把这些日志写入业务数据库或一个由 Astra 管理的日志文件；外部日志/OTel 基础设施是否持久化取决于部署环境。它也不是当前 Turn Trace API 的数据来源。

2. Turn Trace：agent_events 事件图

相关代码：

• crates/astra-turn-core/src/trace_event.rs
• crates/runtime/src/server/run/lifecycle/persistence.rs
• crates/runtime/src/server/session/session_trace.rs
• crates/services/src/storage.rs

这是当前最接近 Agent Trace 查询面的数据。主要表是 agent_events，关系补充表是 agent_event_edges。

agent_events 已有的关联字段包括：

• 身份：event_id、session_id、user_id、agent_id、agent_version
• 执行层级：turn_id、turn_seq、run_id、parent_run_id、parent_agent_id
• 因果与父子关系：parent_event_id、causal_chain_id
• LLM/Tool：round_index、tool_call_id、llm_model_used、llm_params、token usage、reasoning、tool name、duration
• 内容与扩展：event_type、trace_kind、content、metadata、skill 信息、user_feedback_score、created_at

当前生产路径中能看到的 trace_kind 主要有：

• turn
• llm_round
• tool_call
• agent_lifecycle
• trace_health

主要事件包括 user_query / user_message、llm_response、llm_round_completed、Tool 的 started/completed/failed/rejected/reused/suppressed/deferred、子 Agent 生命周期，以及 trace_persistence_degraded。

GET /sessions/{session_id}/turns/{turn_id}/trace 按用户、Session、Turn 查询 agent_events，再重建：

• Turn 根节点
• 根 Run 的 LLM Rounds 与 Tools
• 子 Agent Runs
• Trace completeness / persistence warning

这个 API 当前不查询 agent_event_edges、Journal、StepRecorder、Prompt/Context 表或 Evaluation 表。它返回 token、model、duration、reasoning、metadata 等字段，但 agent_events 中的 llm_params、user_feedback_score 等列目前没有全部进入 API 结果。

从 Span 模型看，这里保存的是若干离散事件。created_at 是事件发生时间，meta_duration_ms 只在部分事件上存在；它们并不总能直接表达一次操作完整的 start/end/status。

3. Session Journal / TraceSpan：服务端 Session 时间线

相关代码：crates/services/src/session_journal.rs

Session Journal 是 owner-scoped 的服务端 JSONL。典型路径为：

<local-state>/sessions/v1/users/<owner>/sessions/<session_id>.jsonl

local-state 默认通常位于 ~/.astra，也可通过 ASTRA_LOCAL_STATE_ROOT 调整。这里的 ~ 是 server 进程用户的本地状态目录，不是 Astra CLI 用户日志。

其中的 TraceSpan 记录：

• turn_start
• llm_call
• tool_selection
• tool_execution
• turn_end

Journal 还包含更广的执行/审计事件，例如完整 LLM payload、Context Assembly、Turn Evaluation 等。Journal 的直接持久化目标是 JSONL 文件；虽然存在把部分 journal/event 形态投影到 agent_events 的路径，但不能把 Journal 理解成与数据库逐行同步的副本。

4. ContextAssemblyTrace：上下文构造解释

相关代码：crates/astra-turn-core/src/context/assembly_trace.rs

它记录：

• Prompt 各部分的 token/内容构成
• 历史消息保留、压缩、丢弃情况
• Retrieval 结果
• Tool surface
• Token budget 与选择决策
• Provider request identity

当前存储有多个层次：

• Observability session 内存中保留最近 50 条。
• 完整 snapshot 可写为 Session Journal 的 ContextAssemblyRecorded 事件。
• 摘要信号以 context_trace_signal 进入 agent_events。
• 启用相应类别时，LLM context manifest 写入 context_manifests 和 context_manifest_items。
• 存在 workspace 时会更新本地 workspace.yaml 的 last_context_trace；远端 workspace metadata 可作为 session_artifacts 保存。

因此，agent_events 中的 context signal 不是完整 Context Assembly Trace，完整内容需要到 Journal、manifest 表或 workspace artifact 中寻找。

5. StepRecorder：Loop 控制流与 Checkpoint

相关代码：

• crates/astra-pipeline/src/step_protocol.rs
• crates/astra-pipeline/src/recorder.rs

StepRecorder 记录语义执行 DAG，包括 Agent 生命周期、LLM Round、Tool、stall/divergence/retry、compaction、memory、checkpoint 等。这些信号对于定位 Loop 缺陷很重要。

server 在绑定持久化后会写入 Session 目录：

<session-dir>/step_events.jsonl
<session-dir>/step_checkpoints/NNNNNN-light.json
<session-dir>/step_checkpoints/NNNNNN-heavy.json

当前生产路径没有把原始 StepEvent 持久化为一套对应的数据库事件表。数据库中另有 session_checkpoints 和 session_artifacts，但它们不等于 step_events.jsonl 的逐项数据库副本，当前 Turn Trace API 也不读取 StepRecorder 文件。

6. 完整 LLM Exchange 与 Prompt Assembly

相关代码：crates/runtime/src/turn/llm/exchange_capture.rs

开启 llm_exchanges / full_llm_capture 后，完整请求响应会写为服务端文件：

llm_capture_t{turn}_r{round}_{source}_{outcome}_{timestamp}.json

文件权限设为 0600。存在远端 store 时，同一类内容也可作为 artifact_kind = "llm_capture" 写入数据库 session_artifacts；部分路径还会把 LlmRequestFull / LlmResponseFull 写入 Session Journal。

Prompt Assembly 另有数据库表：

• prompt_request_records
• prompt_deltas

它们由 prompt_assembly trace category 控制。也就是说，LLM Round 的摘要、完整 provider exchange 和 Prompt 构造并不在同一张表中。

7. Harness、Decision Audit 与 Evaluation

Harness

Harness snapshot 默认可存在内存 ring 并通过 SSE 暴露；启用 harness_snapshots 时可进入数据库 harness_snapshots。Harness 库虽然提供 JSON/JSONL 保存能力，但当前未发现 server 生产路径自动把它作为常规 trace 文件写出。

Decision audit

Context/decision introspection 使用数据库表：

• ctx_snapshots
• ctx_decision_audits

Permission DecisionEnvelope.trace 与全局 audit ring 当前主要在内存中；排除 CLI 本地日志后，未发现一条 server 生产路径把完整 permission decision trace 持久化到数据库或服务端 trace 文件。

Evaluation / Feedback

TurnEvaluation 会计算 success、quality、confidence 以及 tool error、blocked tool、stall、verdict warning 等信号，server 当前会把它写入 Session Journal 的 TurnEvaluation 事件。

数据库还存在独立的评估/反馈表：

• eval_quality_assessments
• eval_calibration_assessments
• eval_gate_results
• eval_training_datasets
• eval_user_feedback

其中 eval_user_feedback 带 session_id / turn_id；agent_events 本身也有 user_feedback_score 列。这些评估数据当前没有被 GET .../trace 组装成 Turn 或 Span 的 evaluation。

8. SessionTraceConfig 不等同于已持久化的数据面

crates/core/src/trace_types.rs 定义了 14 个 category：Tool Calls、LLM Exchanges、Context Assembly、Decision Explain、Phase Transition、Budget、Reflection、Verification、Thinking、Memory Retrieval、Skill Execution、Harness Snapshots、Prompt Assembly、Guard Evaluation。

这个枚举表达的是可配置分类，不代表每个分类已经有独立、完整、可查询的持久化实现。当前 runtime 中能够明确看到独立持久化控制的包括 LLM Exchange、Context Assembly、Prompt Assembly、Harness Snapshot；其他信号可能进入 StepRecorder、Journal、agent_events 或只停留在内存路径，需按实际写入点判断。

存储位置汇总

数据	数据库	服务端文件	内存 / 外部	当前 Turn Trace API 是否读取
Turn / LLM Round / Tool / Agent lifecycle	agent_events	部分也出现在 Journal	—	是
显式 event edge	agent_event_edges	—	—	否
Session Journal / TraceSpan	部分事件可被投影，但不是完整镜像	<session_id>.jsonl	—	否
StepRecorder	原始 StepEvent 无对应生产表	step_events.jsonl、checkpoint JSON	可在运行时持有	否
Context Assembly	context_manifests、context_manifest_items、摘要可进 agent_events / session_artifacts	Journal、workspace.yaml	最近 50 条	只读取 agent_events 中已有摘要事件
完整 LLM request/response	可作为 session_artifacts.llm_capture	llm_capture_*.json、Journal	—	否
Prompt Assembly	prompt_request_records、prompt_deltas	—	—	否
Harness snapshots	harness_snapshots	当前无常规 server 自动文件落盘	ring / SSE	否
Context decision audit	ctx_snapshots、ctx_decision_audits	—	—	否
Turn Evaluation	独立 eval 表可保存各类 assessment/feedback；agent_events 有 feedback 列	Session Journal	运行时计算	否
Permission decision trace	当前未发现 server 生产持久化路径	排除 CLI 后无	audit ring / envelope	否
HTTP/Rust tracing	Astra 业务库不存	默认 stderr，不是 Astra 管理文件	可发外部 OTLP	否

与 OpenInference 的语义对照

OpenInference 是建立在 OpenTelemetry 上的语义约定，不规定 Astra 必须使用哪种数据库或后端。下面只表示“现有 Astra 数据若用 OpenInference 术语解释，最接近什么”，不表示已经完成兼容。

Astra 现有概念	最接近的 OpenInference span kind / 表达	当前数据来源	直接映射时的缺口
一个 Turn 的根执行	AGENT（或承载整次执行的 root span）	agent_events	需要确定 Trace 边界是 Turn 还是更长的 Run，并形成稳定 trace/span id 与明确起止时间
子 Agent Run	AGENT	Agent lifecycle events、run_id / parent_run_id	lifecycle 是多个事件，需要折叠成一个 span，并处理未正常结束的 Run
LLM Round / provider attempt	LLM	agent_events、LLM capture、Journal、Prompt 表	Round 与实际 provider attempt 未完全等价；input/output/model/parameters/usage/timing 分散在多处
Tool lifecycle	TOOL	Tool events、tool_call_id	started/completed/failed 等需按 call id 合成 span，参数、结果、错误和状态需确定来源
Retrieval	RETRIEVER	Context Assembly、StepRecorder	当前不是独立的持久化 span，query/documents/score 主要嵌在 snapshot/event 中
Context Assembly / pipeline step	CHAIN	Context trace、StepRecorder	需要从 snapshot/DAG 中决定哪些步骤构成 span，哪些只是 span event
Prompt Assembly	PROMPT 或 LLM span 的 prompt attributes	Prompt tables、manifest、LLM capture	Prompt identity/version 与最终 provider input 分开保存
Guard / permission decision	GUARDRAIL	Guard events、permission decision	排除 CLI 后，完整 permission trace 缺少 server 持久化载体
TurnEvaluation / feedback	EVALUATOR span 或 OpenInference evaluation attributes	Journal、eval tables、feedback	需要稳定指向被评价的 trace/span/session；当前各数据面没有共同 target id
retry、stall、divergence、compaction	Span events / attributes	StepRecorder、Journal	原始信息主要在文件事件流，未与 agent_events span identity 对齐

OpenInference 的 LLM/Tool/Retriever 等属性还能为现有字段提供命名对照，例如 input/output、model、invocation parameters、token count、tool name/call id、retrieval documents、session/user metadata。Astra 当前“有数据”不等于“可直接逐字段导出”：首先需要把离散事件还原成有父子关系和生命周期的 span。

如果导出到 Langfuse，需要怎样映射

Langfuse 的基本数据模型是 Session → Traces → Observations；一次 Trace 通常代表一次请求/执行，Observation 表示其中的 generation、tool 或其他步骤。Langfuse v4 的自定义 OpenTelemetry 接入以完整 OTel span 为输入，同一 Trace 的 observations 共享 trace id，并通过 parent span 形成层级；LLM 评价分数使用独立的 Score 数据模型/API。参考：

• Langfuse data model
• OpenTelemetry integration
• Custom OTel ingestion / v4 mapping
• Scores data model

现有 Astra 数据可按下表理解：

Astra 来源	Langfuse 目标	导出时需要完成的转换或选择
session_id	Session id / trace session context	在同一 Session 的相关 observations 上传播一致值
Turn 或根 run_id	Trace + root observation	确定 Trace 边界；生成/保持稳定 OTel trace id 与 root span id
run_id / parent_run_id	Agent observations 及 parent relationship	把 Agent lifecycle 事件合并成有 start/end/status 的 observation
round_index + LLM events/capture	generation observation	合并 model、parameters、input/output、reasoning、usage、timing；区分逻辑 Round 与 provider retry/attempt
tool_call_id + Tool events	tool/span observation	合并 started 与 terminal event，补齐 tool name、arguments、result/error、status、duration
Context / retrieval / prompt records	span observation、input/metadata，必要时拆出 retrieval/prompt step	选择完整内容来自 Journal、manifest、Prompt 表还是 artifact，并处理敏感信息
user_id、agent/version、tags、environment	Trace/observation attributes	把 trace-wide context 传播到 Langfuse 可识别的 OTel attributes；不能只放在某一条末端 event 上
TurnEvaluation、eval tables、feedback	Langfuse Score	将 score/label/explanation 指向具体 trace、observation 或 session；Score 不是仅靠 OTLP span 自动得到
StepRecorder 的 stall/retry/divergence	observation events / metadata 或独立 observation	先与对应 run/round/tool 建立 identity，再决定是事件还是步骤
trace_persistence_degraded	observation status/event/metadata	保留“本次 Astra trace 不完整”的事实，避免下游把缺失数据误判为未发生

这里有两个需要区分的层次：

1. OpenInference 类比解决“这些 Agent 数据在通用语义中是什么”。
2. Langfuse 导出还需要符合 Langfuse 当前支持的 OTel attributes、OTLP/HTTP 接入和 Score API。即使 Astra 字段能对应 OpenInference，也不能据此假定 Langfuse 会自动识别全部 OpenInference attributes。

哪些现有记录与 Agent 能力 Trace 关系较弱

以下记录可以帮助系统排障，但通常不是用来复盘 Loop 决策和识别 Agent 缺陷的主体：

• HTTP access span、request id、数据库/网络错误、服务启动和资源指标等基础设施 telemetry。
• storage sink、batch、flush、retry 等“如何持久化 trace”的内部日志；其中 trace_persistence_degraded 例外，因为它直接说明 Agent Trace 是否完整。
• 一般运行日志中没有稳定 Session/Turn/Run 关联的文本。

Harness snapshot 和 permission/guard decision 是否属于主体取决于分析问题：研究 Loop 状态机或工具受阻时很相关；只分析模型生成质量时则更像补充信号。

从当前状态仍无法直接回答的问题

这些不是方案，而是做 OpenInference 对照或 Langfuse 导出时必须从现有语义中澄清的边界：

1. Agent Trace 的根到底对应一个 Turn、一个 root Run，还是可跨 Turn 的任务。
2. run_id / turn_id / causal_chain_id 中哪个身份应稳定映射到外部 trace id；历史数据能否确定性生成同一 id。
3. 一个 llm_round 是否包含多个 provider attempt；重试应是同一 LLM observation 的 event，还是多个 observation。
4. 同一字段在 agent_events、Journal、StepRecorder、manifest 和 artifact 中重复时，导出读取哪个版本，以及如何去重。
5. Evaluation/feedback 评价的是 Session、Turn、Run、LLM Round、Tool Call 还是最终答案；当前 target identity 是否足够。
6. 完整 Prompt、reasoning、Tool 参数、检索内容的权限、脱敏与保留期如何继承到外部系统。
7. 文件数据不可用、异步持久化失败或部分表未开启时，如何表达 trace completeness。

因此，Astra 的现状不是“没有 Trace 数据”，而是相关数据已经存在于多个事件流、表、文件与内存结构中；当前可查询的 Turn Trace 只覆盖其中一部分。OpenInference 可以用来描述这些数据的语义，Langfuse 则提供一个具体的导出目标，但两者都需要先以 Astra 现有身份、生命周期和存储边界为基础进行映射。