logfire-infrastructure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Monitor Infrastructure with Logfire

使用Logfire监控基础设施

Do not use this skill for application-level traces, logs, or AI/agent spans — that's

logfire-instrumentation

. The two compose: a full setup often runs both.

请勿将本技能用于应用级追踪、日志或AI/Agent链路——这类场景请使用

logfire-instrumentation

。两者可组合使用：完整的监控部署通常会同时运行这两个工具。

How This Works

工作原理

The OpenTelemetry Collector ships host, container, cluster, and infrastructure-service metrics to Logfire with no application code changes — Logfire is a fully compliant OTel backend and ingests standard OTLP traces, logs, and metrics from it (one narrow exception noted in the collector reference), so the Collector is the entire mechanism. This is optional and is an advanced tool: if the user only wants their app's own traces,

logfire-instrumentation

's language SDKs are enough on their own.

OpenTelemetry Collector可在无需修改应用代码的情况下，将主机、容器、集群及基础设施服务的指标发送至Logfire——Logfire是完全合规的OTel后端，可从中接收标准OTLP追踪、日志和指标（收集器参考文档中提及一个特殊例外情况），因此Collector是实现这一功能的核心组件。这是一个可选的高级工具：如果用户仅需监控应用自身的追踪数据，

logfire-instrumentation

的语言SDK已足够使用。

Step 1: Authenticate and Select the Exact Project

步骤1：认证并选择正确的项目

Do not open, read, or run any infrastructure config file (

docker-compose.yml

, a Kubernetes manifest, or similar) until

whoami

confirms you're authenticated to the right project — nothing about this step requires knowing what's being monitored. Auth is also the one step that can block on a human (browser sign-in), so starting it first means that wait begins on turn one, not after Step 2's detection work.

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) plus where the Collector's own write token comes from: Authenticate and Select the Exact Project.

在

whoami

命令确认您已认证到正确的项目之前，请勿打开、读取或运行任何基础设施配置文件（如

docker-compose.yml

、Kubernetes清单等）——此步骤无需了解具体要监控的内容。认证是唯一可能需要人工操作（浏览器登录）的步骤，因此先执行认证可让等待流程从第一步就开始，而非在完成步骤2的检测工作之后。

首先执行检查命令：

uvx logfire --non-interactive whoami

（JavaScript环境下为

npx logfire whoami

）——如果命令返回正确的项目和区域，则跳过此步骤直接进入步骤2。否则，请参考认证并选择正确的项目文档，获取完整的命令序列、参数说明、注意事项（如

--non-interactive

参数的要求、

auth

命令无法自动打开浏览器的原因、

LOGFIRE_TOKEN

与凭证文件的冲突问题），以及Collector自身写入令牌的获取方式。

Step 2: Identify What to Monitor

步骤2：确定监控对象

Detect the infrastructure actually in play, don't assume:

Host/VM: monitoring the machine itself (CPU, memory, disk, network, load).
Docker: read
```
docker-compose.yml
```
/
```
Dockerfile
```
s for running containers.
Kubernetes: look for manifests, a
```
kubeconfig
```
, or
```
kubectl
```
context.
Database/queue/cache servers: read
```
docker-compose.yml
```
/
```
pyproject.toml
```
/
```
package.json
```
for Postgres, MySQL, Redis, MongoDB, Kafka, RabbitMQ, Nginx, Apache, Elasticsearch, or Memcached.
Cloud provider: GCP or AWS metrics (Cloud Monitoring, CloudWatch, ECS), when the user names the provider or the app clearly runs there.

More than one can apply at once — a single Collector can run multiple receivers in parallel pipelines.

检测实际运行的基础设施，切勿主观臆断：

主机/虚拟机：监控机器本身的指标（CPU、内存、磁盘、网络、负载）。
Docker：读取
```
docker-compose.yml
```
或
```
Dockerfile
```
以识别运行中的容器。
Kubernetes：查找清单文件、
```
kubeconfig
```
配置或
```
kubectl
```
上下文。
数据库/队列/缓存服务器：读取
```
docker-compose.yml
```
、
```
pyproject.toml
```
或
```
package.json
```
，查找Postgres、MySQL、Redis、MongoDB、Kafka、RabbitMQ、Nginx、Apache、Elasticsearch或Memcached等服务。
云服务商：当用户指定服务商或应用明确运行在对应平台时，监控GCP或AWS的指标（如Cloud Monitoring、CloudWatch、ECS）。

可同时监控多种对象——单个Collector可在并行管道中运行多个接收器。

Step 3: Configure the Collector

步骤3：配置Collector

Follow the collector reference for the receiver(s) identified in Step 2 — it covers the shared exporter setup, then a dedicated section per source: host metrics, Docker, Kubernetes, database/queue/cache servers, and cloud-provider metrics, each with the exact receiver name, a working config, and the caveats that actually bite (Docker socket permissions, API version pinning,

host.docker.internal

localhost

, IAM permissions, ADOT vs. Contrib collector images).

Set the same service & resource metadata conventions the collector reference describes —

host.name

service.name

service.instance.id

— so data groups correctly across the Hosts, Kubernetes, and Metrics pages.

Before starting or restarting the Collector, validate the config file — a receiver typo or bad indentation should surface as a validation error, not a Collector that starts, logs nothing useful, and silently drops the pipeline:

bash

otelcol-contrib validate --config=collector-config.yaml

根据步骤2中识别的接收器，参考收集器参考文档进行配置——文档涵盖了通用导出器设置，以及针对每种数据源的专属章节：主机指标、Docker、Kubernetes、数据库/队列/缓存服务器和云服务商指标，每个章节都包含确切的接收器名称、可用配置以及实际使用中的注意事项（如Docker套接字权限、API版本固定、

host.docker.internal

与

localhost

的区别、IAM权限、ADOT与Contrib收集器镜像的差异）。

按照收集器参考文档中描述的服务与资源元数据规范设置

host.name

、

service.name

、

service.instance.id

，确保数据能在主机、Kubernetes和指标页面中正确分组展示。

在启动或重启Collector之前，请验证配置文件——接收器名称拼写错误或缩进不当应在验证阶段就暴露为错误，而非让Collector启动后无有效日志输出并静默丢弃数据管道：

bash

otelcol-contrib validate --config=collector-config.yaml

or, for the core (non-Contrib) distribution: otelcol validate --config=...


If neither binary is on `PATH`, inspect the running Collector container (for example with `kubectl exec`) or use the deployment-specific validation command from the image entrypoint, systemd unit, or Helm chart. `docker compose config` or `kubectl get pod <name> -o yaml` can show the command when it is explicitly configured.


如果`PATH`中没有上述二进制文件，请检查运行中的Collector容器（例如使用`kubectl exec`命令），或使用镜像入口脚本、systemd单元或Helm Chart中特定于部署的验证命令。当命令被显式配置时，`docker compose config`或`kubectl get pod <name> -o yaml`命令可查看该命令。

Step 4: Verify

步骤4：验证

Wiring a receiver isn't done when the Collector starts cleanly — confirm the data actually reached the right page for the right host/container/cluster, not just that something arrived. Never report a metric as "arrived" without having queried for it in this same session — a plausible-sounding summary that wasn't checked is worse than saying you couldn't verify.

Restart the Collector after any config change (having validated it, above).
Query for the exact resource you configured, not just any data on the page. If a Logfire MCP server or API is connected in this session, query for the specific
```
host.name
```
/ container / cluster you set in Step 3 within the last few minutes — a query that returns zero rows for that exact identifier means it didn't land, even if the page shows data from something else. Otherwise, open the specific product page — Hosts, Docker, or Kubernetes — or the Metrics explorer for database/queue/cache/cloud sources, and look for that same exact identifier.
If nothing appears, check in order: the exporter endpoint/region and write token, that the receiver is in an active pipeline (not defined but never referenced under
```
service.pipelines
```
), and that resource attributes (
```
host.name
```
,
```
service.name
```
) are set — the reference's own Verify section has the full troubleshooting path.
Fix and re-check until the specific source is visible, not just "some" data.

Close with a final report built from what you just confirmed — org/project/region from

whoami

, which receiver(s) are active, and the exact host/container/cluster identifier you verified — not a template. Include a direct link to the relevant view (

/hosts

/docker

/kubernetes

, or

/metrics

, based on the source) using the project's URL from

whoami

, so the user can see their own source arrive without having to ask where to look. A report with a placeholder in it means a step above was skipped, not finished.

仅Collector启动成功并不代表接收器配置完成——需确认数据已实际到达对应主机/容器/集群的正确页面，而非仅确认有数据传入。切勿在未在当前会话中查询验证的情况下，报告指标已“到达”——未经验证的看似合理的总结，比无法验证的表述更糟糕。

重启Collector：在任何配置变更后（需先完成上述配置验证）重启Collector。
查询您配置的具体资源，而非页面上的任意数据。 如果当前会话已连接Logfire MCP服务器或API，请查询过去几分钟内您在步骤3中设置的特定
```
host.name
```
/容器/集群——若针对该确切标识符的查询返回零结果，则说明数据未成功传入，即使页面显示了其他来源的数据。否则，请打开对应的产品页面——主机、Docker或Kubernetes，或针对数据库/队列/缓存/云数据源的指标探索器，查找该确切标识符。
如果未显示任何数据，请按以下顺序检查：导出器端点/区域和写入令牌，确认接收器已配置在活跃管道中（并非仅定义但未在
```
service.pipelines
```
中引用），以及资源属性（
```
host.name
```
、
```
service.name
```
）是否已正确设置——参考文档的验证章节包含完整的故障排查路径。
修复并重新检查，直到特定数据源可见，而非仅显示“部分”数据。

最后根据您确认的内容生成最终报告——包含

whoami

命令返回的组织/项目/区域、活跃的接收器、以及您验证过的确切主机/容器/集群标识符——请勿使用模板。包含指向相关视图的直接链接（根据数据源选择

/hosts

、

/docker

、

/kubernetes

或

/metrics

），链接使用

whoami

命令返回的项目URL，以便用户无需询问即可查看自己的数据源是否已传入。报告中若存在占位符，则说明上述某个步骤被跳过，并未完成。

References

参考文档

Host, Docker, Kubernetes, database/queue/cache, and cloud-provider metrics via the OTel Collector — receiver configs, IAM/permission caveats, and its own verify loop.

通过OTel Collector监控主机、Docker、Kubernetes、数据库/队列/缓存及云服务商指标——包含接收器配置、IAM/权限注意事项及专属验证流程。