你会遇到什么
这个工具解决什么问题：AI/LLM 系统的可观测性。Logfire 是 OpenTelemetry 原生的观测库：代码里插桩（logfire.configure + instrument_*），把 trace/span 送到托管平台或本地 preview 查看。 什么时候用：
- 你要看 LLM 调用的 trace/span（请求链、耗时、错误）；
- 你要给 Agent 应用加 OpenTelemetry 插桩；
- 你不想搭自己的观测栈，用托管平台或本地 preview。
什么时候别用：只想要日志文件时——它是 trace 导向的观测库；或数据合规要求遥测完全不出机器时（不登录/本地 preview 不外发）。 注意事项：上传托管平台需 logfire auth（token 存 ~/.logfire/）；本地 preview 模式可无 token。生产环境注意数据合规。
本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。
为什么会这样
它怎么工作：pip 装 logfire（依赖 opentelemetry 全家桶，首次 3-5 分钟）。CLI：logfire auth 登录托管平台（交互式）、logfire preview 本地预览、logfire --help 全局选项。代码内：import logfire; logfire.configure + instrument_* 插桩。轻量场景可装 logfire-api（仅插桩 API）。 关键概念：
- preview：本地预览模式（免 token）；
- auth：托管平台登录（token 存 ~/.logfire/）；
- instrument_*：代码插桩入口。
装完它动哪里：~/.logfire/（专属，token/配置）。
快速修复（不想看讲解，直接跑）
note: 本环境实测路径；国内必须带清华镜像（PyPI 官方超时）；首次安装 3-5 分钟属正常
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0
logfire --version预期输出: Running Logfire 4.41.0 with CPython ...
一步步来
第 1 步：装库（为什么锁版本：4.41.0 为收录实测版本）
讲解：logfire 依赖 opentelemetry 全家桶，首次安装 3-5 分钟属正常（耐心等，不是卡死）。国内 PyPI 官方超时，必须带清华镜像前缀。
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0
logfire --version预期输出: Running Logfire 4.41.0 with CPython ...
装好确认：
--version输出 4.41.0；logfire --help有完整 CLI 说明。
卡住怎么办：
- 安装很久 → opentelemetry 依赖多属正常（首次 3-5 分钟）；确认带清华镜像前缀；
- Python 版本 → 确认 >= 3.10。
第 2 步：代码插桩冒烟（本地 preview，免 token）
讲解：logfire.configure 是插桩入口；本地 preview 模式无 token 可跑，先验证库可用，再决定要不要接托管平台。
python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"预期输出: logfire configured: OK（本地 preview 无 token 可跑）
装好确认：
- 输出 logfire configured: OK，无认证报错。
卡住怎么办：
- 报 token 错误 → 本地 preview 不需要 token；如提示登录，用
logfire preview或先跳过 auth； - import 失败 → 确认 pip 与 python3 同环境。
第 3 步：登录托管平台 + 本地预览（按需）
讲解：logfire auth 走浏览器/设备码登录（token 存 ~/.logfire/），上传遥测才需要；logfire preview 起本地预览看 trace/span。
logfire auth预期输出: 浏览器/设备码登录流程（交互式；token 存 ~/.logfire/）
logfire preview预期输出: 本地预览地址（浏览 trace/span；Ctrl+C 退出）
装好确认：
- auth 后 ~/.logfire/ 有 token；
- preview 能打开预览地址。
卡住怎么办：
- auth 交互式卡住 → 用 --non-interactive 或设备码流程；
- preview 端口被占 → 看 --help 的全局选项（--base-url/--region 等）。
怎么确认修好了
第 1 步：确认库能 import 且能配置
讲解：import logfire + configure 不报错，说明库安装完整、依赖链正常；本地 preview 模式不需要 token 也能跑通这一句。
python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"预期输出: logfire configured: OK（本地 preview 无 token 可跑）
卡住怎么办：
- import 失败 → 确认 pip 与 python3 同环境（venv 场景先激活）；
- 报 token 错误 → 本地 preview 不需要 token，跳过 auth 即可。
第 2 步：确认 CLI 与可选接入面
讲解：logfire --version 确认 CLI 版本；需要上传托管平台时 logfire auth 后检查 ~/.logfire/ 出现 token，说明认证链路也通。
logfire --version预期输出: Running Logfire 4.41.0 with CPython ...
卡住怎么办：
- auth 交互式卡住 → 用 --non-interactive 或设备码流程；
- preview 端口被占 → 看 --help 的全局选项（--base-url/--region 等）。
其它环境的表现（常见变体）
- 安装耗时：依赖 opentelemetry 全家桶，首次安装 3-5 分钟属正常，不是卡死；国内必须清华镜像前缀。
- Windows / macOS：pip 安装与插桩代码一致；token 与配置同样存 ~/.logfire/。
- 数据外发：不登录、只用本地 preview 时遥测不外发；上传托管平台才需要 token（写 ~/.logfire/）。
- 写面：只写 ~/.logfire/（专属目录），与其它工具无共享注册面，共装判定全部 possible-compatible。
日常使用
启动与入口
CLI 按需调用；代码插桩是常态使用方式。
常用操作
操作一：查看命令清单
logfire --help预期输出: CLI 说明 + 全局选项（--non-interactive/--base-url/--region）
操作二：登录托管平台（上传遥测需要）
logfire auth预期输出: 浏览器/设备码登录流程（交互式；token 存 ~/.logfire/）
操作三：代码内插桩（库级集成，Python）
python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"预期输出: logfire configured: OK（本地 preview 无 token 可跑）
操作四：本地 preview 服务
logfire preview预期输出: 本地预览地址（浏览 trace/span；Ctrl+C 退出）
数据与目录
- 专属目录：
~/.logfire/（token/配置）。
卸载与清理
note: pip 包自动卸载 + 专属配置目录自动删；代码内插桩手动移除
pip uninstall -y logfire logfire-api 2>/dev/null || true
rm -rf ~/.logfire
command -v logfire >/dev/null 2>&1 && echo "残留: logfire 仍存在" || echo "logfire removed: OK"预期输出: logfire removed: OK
手动确认清单（代码改动，不自动删）：
- 代码库内 logfire.instrument_* / logfire.configure 调用（OpenTelemetry 插桩代码）
- pyproject/requirements 中的 logfire 依赖（pip uninstall 已处理本机环境；项目文件需手动删）
依赖警告
- 版本：
[4.41.0, 4.41.0]锁定（收录实测版本）。 - 环境：Python >= 3.10；依赖 opentelemetry 全家桶（首次安装 3-5 分钟）。
- 网络：PyPI 官方超时，必须清华镜像。
- 写面：
~/.logfire/（专属，无共享注册面）。 - 数据外发：上传托管平台时是（token 认证）；不登录/本地 preview 不外发。
- 共装：判定全部 possible-compatible——logfire 只写 ~/.logfire/（专属），无共享注册面。
FAQ（常见问题）
- 问：必须登录才能用吗？答：不是。本地 preview 模式可无 token；上传托管平台才需 logfire auth。
- 问：安装很慢？答：opentelemetry 依赖多属正常（首次 3-5 分钟）；国内用清华镜像前缀。
- 问：遥测数据会外发吗？答：上传托管平台时是（token 认证）；不登录/本地 preview 不外发。生产环境注意数据合规。
- 问：和别的插件冲突吗？答：判定全部 possible-compatible——logfire 只写 ~/.logfire/（专属），无共享注册面。
- 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。
验证证据
- 实测：
实测记录（本地留存）（2026-08-28，pip 安装 + version/help/configure 冒烟）；实测复现日志（2026-08-30）（官方 README 实测：venv + 清华源安装、--help 命令面 inspect/info 等、token 配置写面 ~/.logfire 探测、LOGFIRE_TOKEN 环境变量路径确认）。 - 未实测：托管平台上传（需 token 登录）；instrument_* 实际插桩链路（需业务代码）。
引用：logfire · 验证于 2026-08-28 · v4.41.0~4.41.0
相关问题（问题域）
出问题了？排障方案
排障手册：logfire
症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：维护者 检索素材（issue #728/#749）+ 匿名 API 补证（实测复现日志（2026-08-28））+ 本市场实测（2026-08-28 隔离 venv 安装/命令面/最小复现）。
采集纪律：零账号匿名检索；未碰 GitHub。check-words HARD 0。
基本信息
- 条目名称：logfire（pydantic/logfire，MIT，v4.41.0 收录）
- 求助信号：help=41 / recent3m=14 / trend=up（demand 基线 demand-signal-20260828）
- 分类：metrics（可观测性）
- 本市场安装路径：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0，验证logfire --version；卸载pip uninstall logfire - 依赖说明：opentelemetry 全家桶，首次安装约 15s（本市场实测，清华镜像）；FastAPI 集成需 extra：
pip install 'logfire[fastapi]'
症状 → 原因 → 解法 → 验证证据
1. FastAPI+SQLModel 测试报 sqlalchemy.exc.NoInspectionAvailable
症状
简单 FastAPI + SQLModel 应用，加了 logfire.instrument_pydantic 后用 TestClient 测试，报 sqlalchemy.exc.NoInspectionAvailable: No inspection system is available for object of type ...；去掉该行则正常。
原因
logfire 的 Pydantic 插桩会检查模型对象，与 SQLModel 的 SQLAlchemy 检查路径冲突（SQLModel 自身已知问题，fastapi/sqlmodel#71）；logfire 2.11.0 及更早版本触发，2024-12-30 于 2.11.1 修复（官方 issue #728，closed）。
解法
- 升级 logfire 到 >=2.11.1（本市场收录 4.41.0 已包含修复）：
pip install -U logfire（国内加-i https://pypi.tuna.tsinghua.edu.cn/simple）。 - 仍出现时：确认
instrument_pydantic与instrument_fastapi(app)的调用位置（4.41.0 的 FastAPI 插桩必须在 app 创建后传参调用，且需先装logfire[fastapi]extra）。
验证证据
- 官方 issue #728（closed 2024-12-27）：维护者 alexmojaki 评论「Fix released in 2.11.1」（匿名 API 补证，）。
- 本市场实测（2026-08-28，隔离 venv，Python 3.14.4）：按 issue 描述写最小用例（FastAPI + SQLModel + TestClient + instrument_pydantic + instrument_fastapi），logfire 4.41.0 下运行 HTTP 200、无 NoInspectionAvailable。
2. 升级后刷 Invalid type NoneType for attribute 'http.port' value 警告
症状
logfire 升级后（案例为 2.11.0 → 2.11.1）控制台大量出现 Invalid type NoneType for attribute 'http.port' value 警告；不配置 logfire 时不出现。
原因
根因不在 logfire：第三方 HTTP 客户端（案例为某 kiota 系 httpx 适配器）在 url.port 为 None 时仍把 http.port 设置为 None，OpenTelemetry 属性校验对 NoneType 报 warning；logfire 只是让该警告浮出水面（官方 issue #749，closed，维护者定位结论）。
解法
- 定位调用链中设置 http.port 的第三方 HTTP 客户端（kiota 系/httpx 适配器类），升级或等待其修复。
- 确认是第三方问题后，该 warning 无害，可忽略；不要在 logfire 侧绕过（无配置项需求）。
验证证据
- 官方 issue #749（closed 2024-12-30）：维护者定位到第三方 httpx 适配器，指出 http.port 只应在 url.port 非 None 时设置（匿名 API 补证，）。
- 本市场实测：logfire 4.41.0 命令面/最小复现未触发该 warning；如实标注「真实遥测链路未实测（需项目 token）」。
3. pip 安装失败/超时（PyPI 直连不稳）
症状
pip install logfire 长时间卡住或报 timeout / 连接错误；国内网络尤其明显。
原因
PyPI 官方源国内直连不稳定（本市场连通性基线：PyPI 直连失败）；logfire 依赖 opentelemetry 全家桶，依赖树大，中途超时概率高。
解法
- 清华镜像加速：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0。 - 隔离安装：
python3 -m venv <dir>后装进 venv，避免污染系统 Python（本市场实测方式）。 - FastAPI 集成一并装：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 'logfire[fastapi]'。 - 卸载：
<venv>/bin/pip uninstall logfire。
验证证据
- 本市场实测（2026-08-28）：清华镜像全量依赖安装成功（含 opentelemetry 全家桶，约 15s，）；
logfire --version输出 Running Logfire 4.41.0 with CPython 3.14.4 on Linux；PyPI 直连风险见连通性基线 connectivity-20260828。
未能实测项（如实标注）
- 真实遥测上报链路（需项目 token 与 logfire auth 登录）；全量集成场景（OpenAI/OpenClaw 追踪等）；Windows/macOS 环境——本环境为 Linux/WSL，未实测。
所属组合包 （1）
combo-model-access— 多模型接入与成本可观测
矩阵暂无该工具对子。