检查应用运行
先查看 Bub 应用的会话历史，再按需导出执行轨迹，检查模型与工具调用的耗时。你可以从本地 Tape 命令开始，接入 Phoenix 或 Logfire 后查看一次运行中的多次调用。
本指南使用应用的 CLI 和配置。会话记录与轨迹导出各有自己的生命周期：即使没有外部追踪服务，默认 Agent 仍会保存选定的对话与运行记录。事件与调用控制说明了事件、输出流和持久化记录之间的区别。
你需要：
- Bub 已安装，且
bub --help可以运行。 - 一个工作区，其中
bub run "What tools do you have?"能调用已配置的模型。 - 如果要本地运行 Phoenix，需要 Docker 或 Podman。
- 如果要添加追踪依赖，请先激活应用虚拟环境。
1. 询问 Bub 当前 tape
Section titled “1. 询问 Bub 当前 tape”先运行一个英文自然语言任务：
bub run "What tools do you have, and what small tasks are they useful for?"然后让 Bub 检查刚刚被这个轮次更新过的 Tape：
bub run ",tape.info"期望输出类似：
name: becda04eb9f7369c__065943a03cbe6395
entries: 98
anchors: 2
last_anchor: session/start
entries_since_last_anchor: 44
last_token_usage: 7458
last_token_cache_hit_rate: 72.50%
这些字段在模型行为异常时很有用：
entries表示会话已积累多少历史。anchors表示锚点数量，last_anchor标记最新的上下文边界。entries_since_last_anchor表示是否可以通过 handoff 缩短下一次提示词。last_token_usage会在模型路径记录 token usage 后出现。last_token_cache_hit_rate表示同一次模型调用中命中缓存的提示词 token 比例（提供商提供明细时可用）。
Tape 保存对话条目和选定的运行记录，上下文选择器决定哪些条目进入模型输入。,tape.info 和 ,tape.search 用于检查这些记录，持久化边界见 Tape 与上下文。
2. 在 tape 中搜索症状
Section titled “2. 在 tape 中搜索症状”需要查找之前的工具调用、错误或 handoff 时，使用 tape.search：
bub run ",tape.search query=loop.step"你也可以让模型检查 Tape 并解释它看到的变化：
bub run "Inspect the current tape and summarize the last turn."第二条命令可能会调用模型，因此只在提供商凭据已配置后使用。
3. 在本地启动 Phoenix
Section titled “3. 在本地启动 Phoenix”运行启用 OTLP HTTP ingest 的 Phoenix：
docker run --rm --name bub-phoenix \
-p 6006:6006 \
arizephoenix/phoenix:latest打开 UI：
http://localhost:60064. 使用 OTLP 运行 Bub
Section titled “4. 使用 OTLP 运行 Bub”在已激活的应用环境中安装追踪依赖：
uv pip install "bub[app,trace]"trace extra 包含 OpenTelemetry API、SDK 和 HTTP/protobuf OTLP 导出器。Bub 使用这些依赖直接向 Phoenix 发送 GenAI span。
在另一个终端运行：
OTEL_SERVICE_NAME=bub \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces \
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
bub run "What tools do you have, and what small tasks are they useful for?"然后用相同遥测设置运行本地 Tape 检查：
OTEL_SERVICE_NAME=bub \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces \
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
bub run ",tape.info"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 是完整的 trace URL。也可以设置 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:6006，导出器会追加 /v1/traces；trace 专用变量优先。Bub 支持 http/protobuf（默认值），headers、timeout、resource attributes 和采样均通过标准 OpenTelemetry 环境变量配置。
显式 OTLP 端点会选择直接导出，即使安装了 Logfire 也不会再配置 Logfire。已有追踪提供器会被保留，重复初始化不会重复添加导出器，OTEL_SDK_DISABLED=true 会禁用这条初始化路径。SDK 批量导出，并在进程正常退出时发送队列中剩余的 span。
需要认证时，设置 OTEL_EXPORTER_OTLP_TRACES_HEADERS（或 OTEL_EXPORTER_OTLP_HEADERS）。如需指定 Phoenix 项目，在 headers 中加入 x-project-name=my-project；否则使用 default 项目。
5. 在 Phoenix 中检查 trace
Section titled “5. 在 Phoenix 中检查 trace”在 Phoenix 中：
- 打开 default project。
- 打开最近的 trace。
- 查找
invoke_agent bub、chat <model>和execute_tool <tool>span。
这条路径与 Tape 检查互补：
- Tape 回答“这个 Bub 会话记住了什么？”
- Phoenix 回答“这个 Bub Agent 轮次如何经过模型调用、工具调用和 Tape 更新？”
排查生产行为时建议两者一起使用：先用 ,tape.info 判断会话状态，再用 Phoenix 查看耗时、错误、模型调用和工具调用。
将执行轨迹发送到 Logfire
Section titled “将执行轨迹发送到 Logfire”如需将执行轨迹发送到 Logfire，安装包含 bub[app,trace] 和 Logfire 的 logfire extra。没有显式配置 OTLP 端点时，Bub CLI 会在启动时配置 Logfire，无需额外的追踪插件。
在已激活的应用环境中添加 Logfire，清除两个 OTLP 端点变量，再登录并选择 Logfire 项目：
unset OTEL_EXPORTER_OTLP_TRACES_ENDPOINT OTEL_EXPORTER_OTLP_ENDPOINT
uv pip install "bub[logfire]"
logfire auth
logfire projects use
bub run "检查这个仓库并总结它的结构。"部署时通过环境变量提供 LOGFIRE_TOKEN。在 Logfire 的 Agents 页面查找 bub。每次执行包含 chat <model> 和 execute_tool <tool> span；子 Agent 位于启动它的工具 span 下，同一会话的执行通过 gen_ai.conversation.id 关联。
Trace 内容与生命周期
Section titled “Trace 内容与生命周期”Span 记录模型输入输出、工具参数和最终结果（结果 hook 与 spill 处理之后）、提供商返回的 token usage，以及错误。消息中的内联媒体内容不会上传。模型回退会更新模型属性，并把失败尝试记录为事件。Token usage 只写入模型 span，避免与 Agent span 重复计数。
Loop step、handoff 和 spill 写入等 Tape 事件会附加到当前 span。Tape 事件及聊天记录的元数据包含 trace_id 和 span_id，便于关联查询。Tape 存储与遥测导出相互独立。
导出 trace 需要安装 trace extra，并配置 OTLP 端点或追踪提供器。嵌入 Bub 时，请显式初始化遥测：设置端点环境变量后调用 configure_otlp()，或自行配置追踪提供器。缺少可选依赖时，Bub 会跳过追踪：
from bub.tracing import configure_otlp
configure_otlp() # 读取 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 或 OTEL_EXPORTER_OTLP_ENDPOINT。
# 通过应用现有的嵌入入口创建并运行 Bub。流提供 aclose()。嵌入使用方若可能提前停止消费，应使用 contextlib.aclosing(stream)，及时关闭模型流、Tape 分支和 span。Trace 上下文在恢复迭代或关闭流时激活，交给调用方处理事件时释放。取消会关闭 span 并设置 bub.cancelled；模型失败和超时会设置错误状态。
从 bub-tapestore-otel 迁移
Section titled “从 bub-tapestore-otel 迁移”实时 Agent trajectory 推荐使用原生追踪。Contrib 插件会在工作完成、Tape 提交后，把一批记录投影为 span；其 span 时间戳反映投影过程，step 耗时另存为属性。原生 span 直接测量执行耗时，保留并发工具的时间关系和子 Agent 的父子关系，并且在未提交终止 Tape 事件的取消场景中也能关闭。
需要把已保存的 Tape 条目转成 span 时，可以使用该插件。原生追踪则在运行时采集执行过程，与现有 Tape 存储配合使用。
迁移步骤：
- Phoenix/OTLP 安装
traceextra，Logfire 安装logfireextra，并按本页配置目标。 - 如果仍安装着 contrib 插件，设置
BUB_TAPESTORE_OTEL_ENABLED=false。 - 保留现有 Tape 存储后端。
原生 span 同时提供 Phoenix 所需的 OpenInference 分类、模型/token、消息和工具输入输出属性。这些兼容属性与标准 gen_ai.* 属性分开。Loop step 记录为 Agent span 上的事件。
Tape 投影方式的细节见 contrib 插件实现。
如果 Phoenix 在前台运行，用 Ctrl+C 停止。若以 detached 方式运行，删除容器：
docker rm -f bub-phoenix- Tape 与上下文：理解 Bub 记录什么，以及如何重建上下文。