docs: update observability tutorial for Phoenix

website/src/content/docs/docs/tutorials/index.mdx

@@ -9,7 +9,7 @@ Tutorials are hands-on lessons. Use this section when you want to learn a workfl
 
 ## What is in this section
 
-1. [Observe Bub with tapes and Jaeger](/docs/tutorials/observability/) — inspect Bub's own tape first, then export Logfire/OpenTelemetry traces to Jaeger.
+1. [Observe Bub with tapes and Phoenix](/docs/tutorials/observability/) — inspect Bub's own tape first, then export OpenTelemetry GenAI traces to Phoenix.
 2. [Connect MCP Servers with bub-mcp](/docs/tutorials/mcp/) — install the MCP plugin, wire up a time server, and call it from a Bub turn.
 3. [Persist tapes in SQLAlchemy with SQLite](/docs/tutorials/tapestore-sqlalchemy/) — replace the file-based tape store with a local SQLite database.
 4. [Run Bub with a local llama.cpp model](/docs/tutorials/local-llama-cpp/) — expose a GGUF Gemma model as a local OpenAI-compatible endpoint.

website/src/content/docs/docs/tutorials/observability.mdx

@@ -1,30 +1,36 @@
 ---
-title: Observe Bub with tapes and Jaeger
-description: Use Bub's tape as a first observability surface, then export Logfire/OpenTelemetry traces to Jaeger.
+title: Observe Bub with tapes and Phoenix
+description: Use Bub's tape as a first observability surface, then export OpenTelemetry GenAI traces to Phoenix.
 sidebar:
   order: 1
 ---
 
 This tutorial gives you two observability paths for one Bub workspace:
 
 1. Run a small natural-language task, then ask Bub about the tape it just wrote. This works without a tracing backend because Bub records each session as an append-only tape.
-2. Send Logfire/OpenTelemetry telemetry to Jaeger while running the same kind of task. Use this when you want traces outside the local workspace.
+2. Send OpenTelemetry telemetry to Phoenix while running the same kind of task. Use this when you want GenAI traces outside the local workspace.
 
-By the end, you will have a quick local health check and a Jaeger view for process-level telemetry.
+By the end, you will have a quick local health check and a Phoenix trace view for agent, model, and tool activity.
 
 ## Before you begin
 
 You need:
 
 - Bub installed and runnable with `uv run bub --help`.
 - One workspace where `uv run bub run "What tools do you have?"` can call your configured model.
-- Docker or Podman if you want to run Jaeger locally.
-- The Logfire extra installed before starting Bub with Jaeger:
+- Docker or Podman if you want to run Phoenix locally.
+- The Logfire extra installed before starting Bub with Phoenix:
 
 ```bash
 uv sync --extra logfire
 ```
 
+- The `bub-tapestore-otel` contrib plugin installed for richer tape and agent spans:
+
+```bash
+bub install bub-tapestore-otel@main
+```
+
 ## 1. Ask Bub for its current tape
 
 Run an English natural-language task first:
@@ -77,33 +83,36 @@ uv run bub run "Inspect the current tape and summarize the last turn."
 
 That second command may call the model, so use it only after provider credentials are configured.
 
-## 3. Start Jaeger locally
+## 3. Start Phoenix locally
 
-Run Jaeger with OTLP HTTP ingestion enabled:
+Run Phoenix with OTLP HTTP ingestion enabled:
 
 ```bash
-docker run --rm --name bub-jaeger \
-  -p 16686:16686 \
-  -p 4318:4318 \
-  jaegertracing/all-in-one:latest
+docker run --rm --name bub-phoenix \
+  -p 6006:6006 \
+  arizephoenix/phoenix:latest
 ```
 
 Open the UI:
 
 ```text
-http://localhost:16686
+http://localhost:6006
 ```
 
-## 4. Run Bub with Logfire and OTLP
+## 4. Run Bub with contrib and OTLP
 
-Bub already supports Logfire during CLI startup when the `logfire` extra is installed. Logfire emits OpenTelemetry data, so you can use any observability backend that accepts OTLP. This tutorial uses Jaeger.
+Bub already supports Logfire during CLI startup when the `logfire` extra is installed. The `bub-tapestore-otel` contrib plugin adds GenAI-oriented spans from Bub's tape store, including `invoke_agent bub`, `bub.agent.step`, chat, and tool execution spans. This tutorial sends both to Phoenix through OTLP.
 
 In another terminal, run:
 
 ```bash
 LOGFIRE_SEND_TO_LOGFIRE=false \
 LOGFIRE_SERVICE_NAME=bub \
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
+BUB_TAPESTORE_OTEL_ENABLED=true \
+BUB_TAPESTORE_OTEL_SERVICE_NAME=bub \
+BUB_TAPESTORE_OTEL_AGENT_NAME=bub \
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces \
+OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
 uv run --extra logfire bub run "What tools do you have, and what small tasks are they useful for?"
 ```
 
@@ -112,35 +121,39 @@ Then run the local tape check with the same telemetry settings:
 ```bash
 LOGFIRE_SEND_TO_LOGFIRE=false \
 LOGFIRE_SERVICE_NAME=bub \
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
+BUB_TAPESTORE_OTEL_ENABLED=true \
+BUB_TAPESTORE_OTEL_SERVICE_NAME=bub \
+BUB_TAPESTORE_OTEL_AGENT_NAME=bub \
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces \
+OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
 uv run --extra logfire bub run ",tape.info"
 ```
 
-Use `LOGFIRE_SEND_TO_LOGFIRE=false` for local Jaeger tutorials so Bub does not try to send telemetry to the hosted Logfire backend. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` points Logfire's OpenTelemetry exporter at Jaeger's OTLP HTTP endpoint.
+Use `LOGFIRE_SEND_TO_LOGFIRE=false` for local Phoenix tutorials so Bub does not try to send telemetry to the hosted Logfire backend. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` points OpenTelemetry exporters at Phoenix's OTLP HTTP endpoint.
 
-## 5. Inspect the trace in Jaeger
+## 5. Inspect the trace in Phoenix
 
-In Jaeger:
+In Phoenix:
 
-1. Select the `bub` service.
-2. Click **Find Traces**.
-3. Open the most recent trace and look for Loguru events such as tape merge messages.
+1. Open the default project.
+2. Open the most recent trace.
+3. Look for `invoke_agent bub`, `bub.agent.step`, `chat <model>`, and `execute_tool <tool>` spans.
 
-![A Jaeger screenshot showing Bub telemetry exported through Logfire and OTLP](/docs/observability/jaeger-logfire.png)
+![A Phoenix screenshot showing Bub GenAI telemetry exported through OTLP](/docs/observability/phoenix-otel.png)
 
 This path complements tape inspection:
 
 - Tape answers "what did this Bub session remember?"
-- Jaeger answers "what did this Bub process emit while it ran?"
+- Phoenix answers "how did this Bub agent turn run across model calls, tool calls, and tape updates?"
 
-Use both when debugging production behavior: start with `,tape.info` to understand the session state, then use Jaeger to inspect timing, errors, and process-level logs.
+Use both when debugging production behavior: start with `,tape.info` to understand the session state, then use Phoenix to inspect timing, errors, model calls, and tool calls.
 
 ## Clean up
 
-Stop Jaeger with `Ctrl+C` if it is running in the foreground. If it is detached, remove it:
+Stop Phoenix with `Ctrl+C` if it is running in the foreground. If it is detached, remove it:
 
 ```bash
-docker rm -f bub-jaeger
+docker rm -f bub-phoenix
 ```
 
 ## Next steps

website/src/content/docs/docs/tutorials/tapestore-sqlalchemy.mdx

@@ -113,6 +113,6 @@ rm -f "$PWD/bub-tapes.db"
 
 ## Next steps
 
-- [Observe Bub with tapes and Jaeger](/docs/tutorials/observability/) — pair the durable tape with process-level telemetry.
+- [Observe Bub with tapes and Phoenix](/docs/tutorials/observability/) — pair the durable tape with GenAI telemetry.
 - [Tape and context](/docs/concepts/tape-and-context/) — what Bub records and how context is rebuilt.
 - [Plugins](/docs/build/plugins/) — the plugin contract `bub-tapestore-sqlalchemy` follows.

website/src/content/docs/zh-cn/docs/tutorials/index.mdx

@@ -9,7 +9,7 @@ sidebar:
 
 ## 本节内容
 
-1. [使用 tape 与 Jaeger 观察 Bub](/zh-cn/docs/tutorials/observability/) — 先检查 Bub 自身的 tape，再把 Logfire/OpenTelemetry trace 导出到 Jaeger。
+1. [使用 tape 与 Phoenix 观察 Bub](/zh-cn/docs/tutorials/observability/) — 先检查 Bub 自身的 tape，再把 OpenTelemetry GenAI trace 导出到 Phoenix。
 2. [使用 bub-mcp 连接 MCP 服务器](/zh-cn/docs/tutorials/mcp/) — 安装 MCP 插件，接入时间服务器，并在 Bub turn 中调用。
 3. [用 SQLAlchemy 与 SQLite 持久化 tape](/zh-cn/docs/tutorials/tapestore-sqlalchemy/) — 把基于文件的 tape store 换成本地 SQLite 数据库。
 4. [使用本地 llama.cpp 模型运行 Bub](/zh-cn/docs/tutorials/local-llama-cpp/) — 把 GGUF Gemma 模型暴露成本地 OpenAI-compatible endpoint。

website/src/content/docs/zh-cn/docs/tutorials/observability.mdx

@@ -1,30 +1,36 @@
 ---
-title: 使用 tape 与 Jaeger 观察 Bub
-description: 先把 Bub 的 tape 当作第一层可观测性，再把 Logfire/OpenTelemetry trace 导出到 Jaeger。
+title: 使用 tape 与 Phoenix 观察 Bub
+description: 先把 Bub 的 tape 当作第一层可观测性，再把 OpenTelemetry GenAI trace 导出到 Phoenix。
 sidebar:
   order: 1
 ---
 
 本教程提供两条观察同一个 Bub workspace 的路径：
 
 1. 先运行一个小的英文自然语言任务，再询问 Bub 刚写入的 tape。由于 Bub 会把每个 session 记录为 append-only tape，这条路径不依赖外部 tracing backend。
-2. 在运行同类任务时，将 Logfire/OpenTelemetry telemetry 发送到 Jaeger。需要把进程级 telemetry 放到本地或生产可观测平台时使用这条路径。
+2. 在运行同类任务时，将 OpenTelemetry telemetry 发送到 Phoenix。需要把 GenAI trace 放到本地或生产可观测平台时使用这条路径。
 
-完成后，你会得到一个本地快速健康检查方式，以及一个 Jaeger trace 视图。
+完成后，你会得到一个本地快速健康检查方式，以及一个用于查看 agent、model 和 tool 活动的 Phoenix trace 视图。
 
 ## 前置条件
 
 你需要：
 
 - Bub 已安装，且 `uv run bub --help` 可以运行。
 - 一个 workspace，其中 `uv run bub run "What tools do you have?"` 能调用已配置的模型。
-- 如果要本地运行 Jaeger，需要 Docker 或 Podman。
-- 启动带 Jaeger 的 Bub 之前，安装 Logfire extra：
+- 如果要本地运行 Phoenix，需要 Docker 或 Podman。
+- 启动带 Phoenix 的 Bub 之前，安装 Logfire extra：
 
 ```bash
 uv sync --extra logfire
 ```
 
+- 安装 `bub-tapestore-otel` contrib 插件，获得更丰富的 tape 与 agent span：
+
+```bash
+bub install bub-tapestore-otel@main
+```
+
 ## 1. 询问 Bub 当前 tape
 
 先运行一个英文自然语言任务：
@@ -77,33 +83,36 @@ uv run bub run "Inspect the current tape and summarize the last turn."
 
 第二条命令可能会调用模型，因此只在 provider credential 已配置后使用。
 
-## 3. 在本地启动 Jaeger
+## 3. 在本地启动 Phoenix
 
-运行启用 OTLP HTTP ingest 的 Jaeger：
+运行启用 OTLP HTTP ingest 的 Phoenix：
 
 ```bash
-docker run --rm --name bub-jaeger \
-  -p 16686:16686 \
-  -p 4318:4318 \
-  jaegertracing/all-in-one:latest
+docker run --rm --name bub-phoenix \
+  -p 6006:6006 \
+  arizephoenix/phoenix:latest
 ```
 
 打开 UI：
 
 ```text
-http://localhost:16686
+http://localhost:6006
 ```
 
-## 4. 使用 Logfire 与 OTLP 运行 Bub
+## 4. 使用 contrib 与 OTLP 运行 Bub
 
-安装 `logfire` extra 后，Bub 在 CLI 启动时已经支持 Logfire。Logfire 会发出 OpenTelemetry 数据，因此你可以使用任何支持 OTLP 的可观测性 backend；本教程使用 Jaeger。
+安装 `logfire` extra 后，Bub 在 CLI 启动时已经支持 Logfire。`bub-tapestore-otel` contrib 插件会从 Bub tape store 生成面向 GenAI 的 span，包括 `invoke_agent bub`、`bub.agent.step`、chat 和 tool execution span。本教程通过 OTLP 把两者发送到 Phoenix。
 
 在另一个终端运行：
 
 ```bash
 LOGFIRE_SEND_TO_LOGFIRE=false \
 LOGFIRE_SERVICE_NAME=bub \
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
+BUB_TAPESTORE_OTEL_ENABLED=true \
+BUB_TAPESTORE_OTEL_SERVICE_NAME=bub \
+BUB_TAPESTORE_OTEL_AGENT_NAME=bub \
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces \
+OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
 uv run --extra logfire bub run "What tools do you have, and what small tasks are they useful for?"
 ```
 
@@ -112,35 +121,39 @@ uv run --extra logfire bub run "What tools do you have, and what small tasks are
 ```bash
 LOGFIRE_SEND_TO_LOGFIRE=false \
 LOGFIRE_SERVICE_NAME=bub \
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
+BUB_TAPESTORE_OTEL_ENABLED=true \
+BUB_TAPESTORE_OTEL_SERVICE_NAME=bub \
+BUB_TAPESTORE_OTEL_AGENT_NAME=bub \
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces \
+OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf \
 uv run --extra logfire bub run ",tape.info"
 ```
 
-本地 Jaeger 教程建议设置 `LOGFIRE_SEND_TO_LOGFIRE=false`，避免 Bub 尝试把 telemetry 发送到托管 Logfire backend。`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 指向 Jaeger 的 OTLP HTTP endpoint。
+本地 Phoenix 教程建议设置 `LOGFIRE_SEND_TO_LOGFIRE=false`，避免 Bub 尝试把 telemetry 发送到托管 Logfire backend。`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 指向 Phoenix 的 OTLP HTTP endpoint。
 
-## 5. 在 Jaeger 中检查 trace
+## 5. 在 Phoenix 中检查 trace
 
-在 Jaeger 中：
+在 Phoenix 中：
 
-1. 选择 `bub` service。
-2. 点击 **Find Traces**。
-3. 打开最近的 trace，查找 tape merge 等 Loguru 事件。
+1. 打开 default project。
+2. 打开最近的 trace。
+3. 查找 `invoke_agent bub`、`bub.agent.step`、`chat <model>` 和 `execute_tool <tool>` span。
 
-![展示 Bub telemetry 通过 Logfire 与 OTLP 导出到 Jaeger 的截图](/docs/observability/jaeger-logfire.png)
+![展示 Bub GenAI telemetry 通过 OTLP 导出到 Phoenix 的截图](/docs/observability/phoenix-otel.png)
 
 这条路径与 tape 检查互补：
 
 - Tape 回答“这个 Bub session 记住了什么？”
-- Jaeger 回答“这个 Bub process 运行时发出了什么？”
+- Phoenix 回答“这个 Bub agent turn 如何经过 model call、tool call 和 tape update？”
 
-排查生产行为时建议两者一起使用：先用 `,tape.info` 判断 session 状态，再用 Jaeger 查看耗时、错误和进程级日志。
+排查生产行为时建议两者一起使用：先用 `,tape.info` 判断 session 状态，再用 Phoenix 查看耗时、错误、model call 和 tool call。
 
 ## 清理
 
-如果 Jaeger 在前台运行，用 `Ctrl+C` 停止。若以 detached 方式运行，删除容器：
+如果 Phoenix 在前台运行，用 `Ctrl+C` 停止。若以 detached 方式运行，删除容器：
 
 ```bash
-docker rm -f bub-jaeger
+docker rm -f bub-phoenix
 ```
 
 ## 下一步

website/src/content/docs/zh-cn/docs/tutorials/tapestore-sqlalchemy.mdx

@@ -113,6 +113,6 @@ rm -f "$PWD/bub-tapes.db"
 
 ## 下一步
 
-- [使用 tape 与 Jaeger 观察 Bub](/zh-cn/docs/tutorials/observability/) —— 把持久化 tape 和进程级 telemetry 配合使用。
+- [使用 tape 与 Phoenix 观察 Bub](/zh-cn/docs/tutorials/observability/) —— 把持久化 tape 和 GenAI telemetry 配合使用。
 - [Tape 与 context](/zh-cn/docs/concepts/tape-and-context/) —— 理解 Bub 记录什么，以及如何重建 context。
 - [Plugins](/zh-cn/docs/build/plugins/) —— `bub-tapestore-sqlalchemy` 遵循的插件契约。