logfire-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set Up Logfire

设置 Logfire

Logfire is an observability platform built on OpenTelemetry, with several distinct product surfaces. This skill authenticates, orients, and routes you to the specific skill for the surface you actually need — don't try to cover install/instrument/verify detail from within this file.

Keep the user informed with short updates, but proceed through ordinary, reversible setup without asking approval — no clean tree, branch, commits, or plan needed, and no commands the user could run only because you chose not to. Pause only for: browser auth, a genuinely ambiguous app/project after inspection, materially increasing production telemetry or cost, deploy/infra changes, or destructive/unrelated work — then ask one concrete question. Never report a check, a score, or a run as verified without having actually confirmed it in this session.

Logfire 是基于 OpenTelemetry 构建的可观测性平台，拥有多个不同的产品模块。本技能负责身份验证、场景定位，并将您引导至所需的专项技能——请勿尝试在此文件中涵盖安装/插桩/验证的详细步骤。

向用户提供简短的更新信息，但无需征得同意即可执行常规、可回滚的设置操作——无需清理代码树、创建分支、提交或制定计划，也不要提供仅因您未选择而让用户自行运行的命令。仅在以下情况暂停操作并询问一个明确的问题：浏览器身份验证、检查后发现应用/项目存在真正的歧义、显著增加生产环境遥测数据或成本、部署/基础设施变更，或破坏性/无关操作。未在本次会话中实际确认的情况下，切勿将检查、评分或运行状态报告为已验证。

Step 1: Authenticate and Select the Exact Project

步骤1：验证身份并选择准确项目

Auth comes first because everything after it depends on having a valid, confirmed connection to the exact right Logfire project: instrumenting or inspecting the repo before that is either wasted if the connection turns out wrong, or worse, ends up silently wired to the wrong project. Do not open, read, or run any project file until

whoami

confirms you're authenticated to the right project — nothing about this step requires knowing what's in the repo yet.

Check first —

uvx logfire --non-interactive whoami

(JS:

npx logfire whoami

) — and skip to Step 2 if it already reports the right project and region. Otherwise, full command sequence, flags, and gotchas (the

--non-interactive

requirement, why

auth

won't open a browser for you, the

LOGFIRE_TOKEN

-vs-credentials-file conflict, token-file safety): Authenticate and Select the Exact Project.

身份验证是第一步，因为后续所有操作都依赖于与正确的 Logfire 项目建立有效且已确认的连接：在身份验证前对代码库进行插桩或检查，若连接最终错误则纯属浪费时间，更糟的是可能会静默连接到错误的项目。在

whoami

命令确认您已验证到正确项目之前，请勿打开、读取或运行任何项目文件——此步骤无需了解代码库中的内容。

首先检查：

uvx logfire --non-interactive whoami

（JS 环境：

npx logfire whoami

）——如果已显示正确的项目和区域，则跳至步骤2。否则，完整的命令序列、标志和注意事项（

--non-interactive

的要求、

auth

命令为何不会为您打开浏览器、

LOGFIRE_TOKEN

与凭据文件的冲突、令牌文件的安全性）请参考：验证身份并选择准确项目。

Step 2: Understand the Repo

步骤2：了解代码库

Read

AGENTS.md

CLAUDE.md

README.md

and skim the language, runtime, and package manager. Then match what you find against the table below to decide what to fetch next:

Surface	Covers	Skill
App instrumentation	Traces, logs, metrics, and AI/agent spans from application code — Python, JavaScript/TypeScript, Rust, or any OpenTelemetry language	`logfire-instrumentation`
Infrastructure monitoring	Hosts, Docker, Kubernetes, database/queue/cache servers, cloud-provider metrics — no application code	`logfire-infrastructure`
Evals	Score AI/agent output against test-case datasets with `pydantic_evals`	`logfire-evals`
Querying telemetry	Search traces/logs/spans/metrics, summarize errors, find root cause	`logfire-query`
Live UI	Open project pages, the live view, trace links, or the Explore page in a browser	`logfire-ui`
Feature flags	Runtime-managed variables ( `logfire.var()` , `logfire.template_var()` )	no dedicated skill yet — see the product's own docs
AI Gateway	Spend caps, failover, and routing for model calls ( `logfire gateway` )	no dedicated skill yet — see the product's own docs

No specific scope given (e.g. "set up Logfire in this repo end to end")? Default to
```
logfire-instrumentation
```
for ordinary application code. Incidental Docker, Kubernetes, infrastructure, or eval files do not expand the initial setup: get one representative application service to verified first data, then offer the matching additional skill(s). If the repository is clearly infrastructure-only, route directly to
```
logfire-infrastructure
```
instead.
A request already scoped to one surface ("monitor my Postgres server", "set up evals for this agent") → fetch that skill directly, skipping the rest of this table.
Genuinely ambiguous between two adjacent surfaces (e.g. "watch my Postgres" could mean Collector-level infrastructure metrics or app-level query instrumentation)? Ask one clarifying question rather than guessing — loading the wrong skill wastes the user's time reading instructions for a job they didn't ask for.

读取

AGENTS.md

CLAUDE.md

README.md

文件，浏览语言、运行时和包管理器信息。然后根据下表匹配您的发现，决定下一步调用哪个技能：

适用场景	涵盖内容	技能
应用插桩	来自应用代码的跟踪、日志、指标以及 AI/Agent 链路——支持 Python、JavaScript/TypeScript、Rust 或任何 OpenTelemetry 兼容语言	`logfire-instrumentation`
基础设施监控	主机、Docker、Kubernetes、数据库/队列/缓存服务器、云提供商指标——不涉及应用代码	`logfire-infrastructure`
评估（Evals）	使用 `pydantic_evals` 根据测试用例数据集为 AI/Agent 输出评分	`logfire-evals`
遥测查询	搜索跟踪/日志/链路/指标、汇总错误、查找根本原因	`logfire-query`
实时 UI	在浏览器中打开项目页面、实时视图、跟踪链接或探索页面	`logfire-ui`
功能标志	运行时管理变量（ `logfire.var()` 、 `logfire.template_var()` ）	暂无专属技能——请查看产品官方文档
AI 网关	模型调用的支出上限、故障转移和路由（ `logfire gateway` ）	暂无专属技能——请查看产品官方文档

未指定具体范围（例如：“在本代码库中完整设置 Logfire”）？对于普通应用代码，默认选择
```
logfire-instrumentation
```
。附带的 Docker、Kubernetes、基础设施或评估文件不会扩展初始设置范围：先让一个代表性的应用服务完成首次数据验证，再提供匹配的附加技能。如果代码库明显仅包含基础设施内容，则直接路由至
```
logfire-infrastructure
```
。
请求已明确针对某一模块（例如：“监控我的 Postgres 服务器”、“为我的 Agent 设置评估”）→ 直接调用对应技能，跳过下表其余内容。
两个相邻模块之间存在真正的歧义（例如：“监控我的 Postgres”可能指采集器级别的基础设施指标，也可能指应用级别的查询插桩）？请提出一个澄清问题，而非猜测——加载错误的技能会浪费用户阅读无关说明的时间。

Step 3: Fetch the Right Skill(s)

步骤3：调用正确的技能

Fetch the skill(s) identified in Step 2 now, for the actual install/instrument/verify steps. Each one's own authenticate step still runs its own

whoami

check first — that's what confirms it's the same project and region resolved here, not an assumption carried over — and only then skips the rest of its auth commands. They're independently fetchable on purpose, so this composes whether someone reaches a specific skill through this hub or on its own.

Never print, log, hard-code, commit, or echo a token, in any of these skills, at any point. The one exception — reading

.logfire/logfire_credentials.json

token

key programmatically to hand a non-native-SDK application its write token, never to display it — is in auth.md.

现在调用步骤2中确定的技能，执行实际的安装/插桩/验证步骤。每个技能的身份验证步骤仍会先自行运行

whoami

检查——这是为了确认使用的是此处已确定的同一项目和区域，而非依赖传递的假设——之后才会跳过其余身份验证命令。这些技能设计为可独立调用，因此无论用户是通过本枢纽技能还是直接访问，都能正常组合使用。

在任何技能中，任何时候都不得打印、记录、硬编码、提交或回显令牌。唯一的例外情况是：通过编程方式读取

.logfire/logfire_credentials.json

的

token

键，为非原生 SDK 应用提供写入令牌，但不得显示该令牌——此操作详见 auth.md。