logfire-setup

设置 Logfire

将每个明确指定的使用场景交由下方对应的专家处理；安装和验证也由这些专家负责。不要扩大原本限定的请求范围。

按常规流程进行可逆的设置，并简要更新进度，无需征求批准；不要求工作区干净、创建分支、提交更改或制定计划。遇到浏览器身份验证、无法解决的应用／项目歧义、生产成本或遥测量显著增加、部署／基础设施变更，或破坏性／无关操作时，请暂停并提出一个具体问题。仅报告本次会话中实际观察到的验证结果。

第 1 步：验证身份并选择确切的项目

如果请求已经限定为前端可观测性、应用 Gateway、编码 Agent 设置、查询或打开 UI，请先从下表加载相应的专家。其凭据要求与常规 SDK 检测不同；不要仅为了转交请求而创建项目写入令牌。

对于常规 SDK 检测，请先使用 whoami 确认确切的项目，再检查或运行应用文件。

参阅验证身份并选择确切的项目，根据提供的 Logfire URL 确定 CLI 目标，并使用经过验证的 CLI 路径运行可识别目标的 whoami 检查——对于没有 uv 的 JS/TS 项目，请使用外部前缀 npm 回退方案，而不要直接使用 npx，因为它可能会执行仓库本地的二进制文件。如果检查已报告正确的项目以及已解析的 --region 或 --base-url 目标，请跳至第 2 步；否则，请继续完成其中的身份验证和项目选择流程。

第 2 步：了解代码库

阅读 AGENTS.md/CLAUDE.md/README.md，并大致了解所用语言、运行时和包管理器。然后将发现的内容与下表对照，决定接下来要获取什么：

范围	涵盖内容	技能
应用埋点	来自应用代码的跟踪、日志、指标和 AI/Agent Span——适用于 Python、JavaScript/TypeScript、Rust 或任何 OpenTelemetry 语言	logfire-instrumentation
前端可观测性	浏览器错误、RUM、Web Vitals 和会话回放	logfire-frontend
基础设施监控	主机、Docker、Kubernetes、数据库/队列/缓存服务、云服务提供商指标——不涉及应用代码	logfire-infrastructure
评估	在 Python 或 Node.js 中针对测试用例数据集设置并运行 AI/Agent 评估	logfire-evals
查询遥测数据	搜索跟踪/日志/Span/指标、汇总错误、查找根本原因	logfire-query
实时 UI	在浏览器中打开项目页面、实时视图、跟踪链接或 Explore 页面	logfire-ui
功能标志	运行时管理的变量（logfire.var()、logfire.template_var()）	暂无专用技能——请参阅产品自带的文档
应用网关	通过 Pydantic AI Gateway 路由应用的模型调用	logfire-gateway
编码 Agent	记录 Claude/Codex 会话，或配置编码 Agent 的 Gateway 路由	logfire-coding-agents

• 如果没有明确的范围，先让一个有代表性的应用服务成功采集到首批数据。偶然出现的 Docker/评估文件不会扩大任务范围。仅涉及基础设施的代码库应转交给 logfire-infrastructure。
• 如果请求已经限定到一个范围（“监控我的 Postgres 服务”“为这个 Agent 设置评估”）→ 直接获取对应技能，跳过表中的其余内容。
• 如果确实无法判断属于两个相邻范围中的哪一个（例如，“监控我的 Postgres”可能指 Collector 层面的基础设施指标，也可能指应用层面的查询埋点），请先提出一个澄清问题，不要猜测——加载错误的技能会浪费用户阅读与其任务无关说明的时间。

第 3 步：获取正确的技能

加载选定的技能，并遵循其凭据流程。SDK 专家使用 whoami 验证项目；CLI 专家保留已准备好的交接内容；查询/UI 技能则可以使用现有的原生 MCP 访问权限。不要强行让所有范围采用同一种身份验证方式。

在任何时候，都不得在任何技能中打印、记录、硬编码、提交或回显令牌。唯一例外是在程序中读取 .logfire/logfire_credentials.json 的 token 键，将写入令牌交给使用非原生 SDK 的应用，但绝不显示该令牌；详见 auth.md。