观测完整运行树

三种历史记录

三类记录必须分开：

Transcript 是模型可见的对话状态；
Journal 是 Runtime 的语义执行记录；
Telemetry 是 Trace、Metric 与 Log 的运行投影。

它们的保留、隐私与正确性要求不同。混用会导致意外数据暴露，也会削弱恢复能力。

结构化 Journal

Journal 应记录稳定 Domain Event，包括 Run 与父级 ID、阶段、计数器和安全元数据。消费者应兼容新增事件类型，并幂等处理。

Journal 用于审计和恢复，但不是 Prompt、思维链或服务商 Payload 的完整转储。

OpenTelemetry

启用 otel Feature，通过 OpenTelemetry 导出面向 GenAI 的 Trace 与 Metric。在模型、工具、子 Agent 和工作流边界传播 Trace Context。

服务与部署 Resource Attribute 在启动时设置；数据到达 Exporter 前先应用采样与 Attribute 白名单。

启用观测

同时启用所需 Provider 与 otel Feature。Runifold 通过全局 OpenTelemetry Provider 发出数据；SDK、Sampler、Resource、Exporter、批处理和关闭流程仍由应用负责。

Cargo.toml

[dependencies]
runifold = { version = "=0.9.0", features = ["otel"] }
runifold-providers = { version = "=0.9.0", features = ["openai"] }

use runifold::ProviderModelExt;
use runifold_providers::openai::OpenAiClient;
 
let runtime = OpenAiClient::from_api_key(std::env::var("OPENAI_API_KEY")?)?
    .runtime("gpt-5")?
    .with_otel();
let agent = runtime
    .agent("support-triage")
    .system("Classify the request and explain the decision.")
    .build()?;
 
let outcome = agent.prompt("My order has not arrived", &run).await?;
println!("run={} tokens={:?}", run.run_id(), outcome.usage);

构造 Runtime 前先初始化 OpenTelemetry SDK，并在优雅关闭时 Flush Provider。Runtime 应在启动时创建一次，然后 Clone 给 Handler；每个请求重新构造还会重置共享熔断状态。

需要自定义 Model 与 Journal 时，创建一个 OtelRuntime，并从同一个实例调用 model(...) 和 journal(...)，这样它们共享因果关联。默认不采集模型正文和 Provider 错误消息；启用它们属于明确的隐私决策。

生产信号

至少监控：

成功、取消、Deadline 和预算耗尽比例；
按服务商、模型、Agent 与 Callable 划分的延迟；
Token、成本、轮次、工具调用与委派；
重试、熔断、Lease 恢复与不确定 Effect 数量；
结构化输出与检索质量失败。

不要把租户 ID 放入高基数 Metric Label；单次运行排查使用 Trace 或受控 Log。

故障调查流程

从应用 Request ID 与 Run ID 开始，先定位终止 Run Event，再沿 Child Run 找到模型与 Callable Attempt。Trace 回答时间花在哪里，Journal 回答哪些语义迁移已经提交；只有获得正文访问授权时才检查模型可见 Transcript。

现象	首要信号	下一步检查
首 Token 慢	Model Span 延迟	Route Health、排队、Provider 延迟
总耗时高	Child Span 瀑布图	Tool / Retrieval 延迟与重试次数
成本异常	Usage Event	轮次、Fallback、Race 失败分支预留
重复写入	Effect Journal 状态	幂等 Key 与对账证据
Trace 缺失	SDK / Exporter 健康	Runtime 前是否初始化全局 Provider
Cardinality 暴涨	Metric Attribute	移除 Run、Request、Tenant 与 Document ID

安全的生产默认值

默认关闭模型正文，在 SDK 边界采样，只允许白名单 Attribute，并分别设置 Trace 与 Journal 的保留策略。基于比例和分位数告警，不把单个租户放进 Label。务必测试 Exporter 故障：Telemetry 背压必须有界，而且不能静默改变执行正确性。

在不执行 Effect 的情况下检查 Run

Runifold 0.9 提供独立的只读运维 CLI。它读取导出的 Event 或 SQLite/PostgreSQL 规范 Journal，不加载 Provider 凭证、不执行迁移，也不会重新执行 Effect：

cargo install runifold-cli --version 0.9.0 --locked
runifold run inspect --events events.json
runifold run tail --events events.json --limit 50
runifold run inspect --sqlite runifold.db --run-id 019...
runifold run replay --events events.json --output replay-evidence.json
runifold checkpoint diff before.json after.json
runifold budget explain budget.json usage.json
runifold doctor --events events.json

Checkpoint Diff 只报告 JSON Pointer 和变化类型，不打印值。Replay 只生成因果证据；真实 Effect 执行仍受 Runtime 的显式恢复策略控制。导出 Run 看起来不完整时先运行 doctor，再沿标准化结果回到 Trace 与持久 Journal。