logfire 详细指南

版本 4.41.0~4.41.0 ｜分类 metrics ｜安全（已审查）｜素材：项目官方文档（英文 README/docs）+ 本市场实测（2026-08-28）
配套：站内文档（manifest + guide + 证据）｜快速版：站内文档

1. 场景：什么时候会用它

Logfire（Pydantic 团队出品，MIT，约 4.4 千星）是面向 AI/LLM/agent 系统的可观测平台：用 OpenTelemetry 原生采集 LLM 调用、token 用量、延迟、成本，提供仪表盘和查询。CLI + Python 库双形态，支持本地 preview（免 token）和托管平台上传。

一句话：给 LLM 应用装"监控屏"——每次调用花多少钱、多慢、哪一步出的错，一目了然。

这个工具解决什么问题：AI/LLM 系统的可观测性。Logfire 是 OpenTelemetry 原生的观测库：代码里插桩（logfire.configure + instrument_*），把 trace/span 送到托管平台或本地 preview 查看。

什么时候用：

你要看 LLM 调用的 trace/span（请求链、耗时、错误）；
你要给 Agent 应用加 OpenTelemetry 插桩；
你不想搭自己的观测栈，用托管平台或本地 preview。

什么时候别用：只想要日志文件时——它是 trace 导向的观测库；或数据合规要求遥测完全不出机器时（不登录/本地 preview 不外发）。

注意事项：上传托管平台需 logfire auth（token 存 ~/.logfire/）；本地 preview 模式可无 token。生产环境注意数据合规。

2. 能力清单

能力	作用
LLM 调用追踪	每次调用的模型/token/延迟/成本
自动插桩	openai/anthropic/langchain 等集成（logfire.instrument_*）
本地 preview	免 token 本地看 trace
托管平台	多环境仪表盘、告警、查询
成本/用量度量	见 Agent 执行版 guide
OpenTelemetry 集成	见 Agent 执行版 guide

3. 快速安装

note: 本环境实测路径；国内必须带清华镜像（PyPI 官方超时）；首次安装 3-5 分钟属正常

# 来源: Trove 详细指南 · 验证于 2026-08-28
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0
logfire --version

预期输出: Running Logfire 4.41.0 with CPython ...

第 1 步：确认库能 import 且能配置

讲解：import logfire + configure 不报错，说明库安装完整、依赖链正常；本地 preview 模式不需要 token 也能跑通这一句。

# 来源: Trove 详细指南 · 验证于 2026-08-28
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，说明认证链路也通。

# 来源: Trove 详细指南 · 验证于 2026-08-28
logfire --version

预期输出: Running Logfire 4.41.0 with CPython ...

卡住怎么办：

auth 交互式卡住 → 用 --non-interactive 或设备码流程；
preview 端口被占 → 看 --help 的全局选项（--base-url/--region 等）。

安装变体

路径	命令	实测
主路径（实测）	`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0 && logfi…`	✅ 本市场实测
镜像/代理	见快速版与 semi_auto_note；国内安装按 logfire 指引	实测

半自动说明：实测命令 = pip install -i 清华镜像 logfire==4.41.0（2026-08-28 本环境验证，隔离 venv，Python 3.14）；国内必须带清华镜像（PyPI 官方超时）；依赖 opentelemetry 全家桶，首次安装约 3-5 分钟；上传托管平台需 logfire auth 登录（token 存 ~/.logfire/），本地 preview 模式可无 token；无 daemon 常驻

安装耗时：依赖 opentelemetry 全家桶，首次安装 3-5 分钟属正常，不是卡死；国内必须清华镜像前缀。
Windows / macOS：pip 安装与插桩代码一致；token 与配置同样存 ~/.logfire/。
数据外发：不登录、只用本地 preview 时遥测不外发；上传托管平台才需要 token（写 ~/.logfire/）。
写面：只写 ~/.logfire/（专属目录），与其它工具无共享注册面，共装判定全部 possible-compatible。

4. 为什么会这样（机制与共享面）

它怎么工作：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/配置）。

~/.logfire/：专属配置/token（实测生成）
代码库内：OpenTelemetry 插桩（logfire.instrument_* 调用，代码级集成）
运行时：CLI 命令（preview/auth），无常驻 daemon

5. 常用操作

第 1 步：装库（为什么锁版本：4.41.0 为收录实测版本）

讲解：logfire 依赖 opentelemetry 全家桶，首次安装 3-5 分钟属正常（耐心等，不是卡死）。国内 PyPI 官方超时，必须带清华镜像前缀。

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 可跑，先验证库可用，再决定要不要接托管平台。

# 来源: Trove 详细指南 · 验证于 2026-08-28
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。

# 来源: Trove 详细指南 · 验证于 2026-08-28
logfire auth

预期输出: 浏览器/设备码登录流程（交互式；token 存 ~/.logfire/）

# 来源: Trove 详细指南 · 验证于 2026-08-28
logfire preview

预期输出: 本地预览地址（浏览 trace/span；Ctrl+C 退出）

装好确认：

auth 后 ~/.logfire/ 有 token；
preview 能打开预览地址。

卡住怎么办：

auth 交互式卡住 → 用 --non-interactive 或设备码流程；
preview 端口被占 → 看 --help 的全局选项（--base-url/--region 等）。

启动与入口

CLI 按需调用；代码插桩是常态使用方式。

常用操作

操作一：查看命令清单

# 来源: Trove 详细指南 · 验证于 2026-08-28
logfire --help

预期输出: CLI 说明 + 全局选项（--non-interactive/--base-url/--region）

操作二：登录托管平台（上传遥测需要）

# 来源: Trove 详细指南 · 验证于 2026-08-28
logfire auth

预期输出: 浏览器/设备码登录流程（交互式；token 存 ~/.logfire/）

操作三：代码内插桩（库级集成，Python）

# 来源: Trove 详细指南 · 验证于 2026-08-28
python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"

预期输出: logfire configured: OK（本地 preview 无 token 可跑）

操作四：本地 preview 服务

# 来源: Trove 详细指南 · 验证于 2026-08-28
logfire preview

预期输出: 本地预览地址（浏览 trace/span；Ctrl+C 退出）

数据与目录

专属目录：~/.logfire/（token/配置）。

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（5 实测兼容 / 14 推断可能兼容 / 0 推断可能冲突）；完整对子、状态与证据见冲突对子（共装矩阵）。

7. 排障速查

暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

8. 卸载与残留检查

# 来源: Trove 详细指南 · 验证于 2026-08-28
pip uninstall -y logfire logfire-api 2>/dev/null || true; rm -rf ~/.logfire

note: pip 包自动卸载 + 专属配置目录自动删；代码内插桩手动移除

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 已处理本机环境；项目文件需手动删）

9. FAQ

运行环境预检（需 Python >= 3.10）
官方 pip 路径（本环境实测）；国内必须带清华镜像（PyPI 官方超时）；依赖 opentelemetry 全家桶，首次安装 3-5 分钟
仅插桩 API 可装 logfire-api（轻量）；上传托管平台需 logfire auth 登录（token 存 ~/.logfire/）；本地 preview 模式可无 token
每条操作 = 一个命令块 + 预期输出
依赖重：opentelemetry 全家桶，首次安装 3-5 分钟；国内 pip 必须带清华镜像

问：必须登录才能用吗？答：不是。本地 preview 模式可无 token；上传托管平台才需 logfire auth。
问：安装很慢？答：opentelemetry 依赖多属正常（首次 3-5 分钟）；国内用清华镜像前缀。
问：遥测数据会外发吗？答：上传托管平台时是（token 认证）；不登录/本地 preview 不外发。生产环境注意数据合规。
问：和别的插件冲突吗？答：判定全部 possible-compatible——logfire 只写 ~/.logfire/（专属），无共享注册面。
问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。

版本：[4.41.0, 4.41.0] 锁定（收录实测版本）。
环境：Python >= 3.10；依赖 opentelemetry 全家桶（首次安装 3-5 分钟）。
网络：PyPI 官方超时，必须清华镜像。
写面：~/.logfire/（专属，无共享注册面）。
数据外发：上传托管平台时是（token 认证）；不登录/本地 preview 不外发。
共装：判定全部 possible-compatible——logfire 只写 ~/.logfire/（专属），无共享注册面。

10. 出处

条目签名：pydantic/logfire（MIT，原样收录 v4.41.0）

实测：实测记录（本地留存）（2026-08-28，pip 安装 + version/help/configure 冒烟）。
未实测：托管平台上传（需 token 登录）；instrument_* 实际插桩链路（需业务代码）。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

官方 README：安装与认证（pip install / logfire auth / 首次运行行为） [官方文档 · logfire 官方 · 2026-08-30（v4.41.0 README）]
`pip install logfire` → `logfire auth` 认证（浏览器 OAuth；或设 `LOGFIRE_TOKEN` 环境变量走 write token）→ 代码里 `logfire.configure` 后开测
官方 README：手动 tracing API（configure / info / span / debug） [官方文档 · logfire 官方 · 2026-08-30（v4.41.0 README）]
手动埋点三件套——`logfire.configure` 初始化、`logfire.info('Hello, {name}!', name=...) ` 结构化日志（{} 占位符）、`with logfire.span('...{question}...'):` 追踪块（span 内 debug/info 自动归属）；日期等类型自动格式化
官方 CLI：命令面（info / run / projects / read-tokens / inspect / gateway 等） [官方文档 · logfire 官方 · 2026-08-30（v4.41.0）]
CLI 命令——auth（认证）/ clean（清空本地数据目录）/ gateway（本地 OAuth 代理，AI Gateway）/ inspect（检查已装包并推荐有用集成）/ whoami（当前用户与项目 URL）/ projects / read-tokens（项目读 token）/ prompt（生成给 LLM 的提示，面向 Logfire MCP）/ info（版本与环境）/ run（带 Logfire 插桩跑 Python 脚本）；global 选项 --non-interactive / --base-url（自托管）/ --region us|eu
官方 README：集成（FastAPI 等生态） [官方文档 · logfire 官方 · 2026-08-30（v4.41.0 README）]
不手动埋点也可用集成——`logfire.instrument_fastapi(app)` 一键插桩 FastAPI（数据库连接器/http 库/logging handler 同理）；README 说支持很多流行包（文档页 integrations）

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 logfire 方案页｜可观测性问题域