logfire-infrastructure

使用 Logfire 监控基础设施

不要将此技能用于应用级追踪、日志或 AI/Agent span——请使用 logfire-instrumentation。两者可以组合使用：完整的设置通常会同时运行两者。

工作原理

OpenTelemetry Collector 无需更改任何应用代码，即可将主机、容器、集群和基础设施服务的指标发送到 Logfire。Logfire 完全兼容 OTel 后端，并可接收来自 Collector 的标准 OTLP 追踪、日志和指标（一个例外情况见Collector 参考），因此 Collector 就是全部实现机制。这是可选的高级工具：如果用户只想监控应用自身的追踪，单独使用 logfire-instrumentation 的语言 SDK 即可。

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

在 whoami 确认你已通过身份验证并连接到正确的项目之前，不要打开、读取或运行任何基础设施配置文件（docker-compose.yml、Kubernetes 清单或类似文件）——完成此步骤无需了解要监控的内容。身份验证也是唯一可能需要等待人工操作（浏览器登录）的步骤，因此先启动它，就能在第一轮开始等待，而不是等到步骤 2 的检测工作完成后才开始。

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

步骤 2：确定要监控的内容

检测实际使用的基础设施，不要想当然：

• 主机/VM：监控机器本身（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 可以在并行管道中运行多个接收器。

第 3 步：配置 Collector

根据第 2 步确定的接收器，参阅Collector 参考文档——其中涵盖通用的 exporter 设置，并针对每个数据源设有专门章节：主机指标、Docker、Kubernetes、数据库／队列／缓存服务器，以及云提供商指标；每个章节都包含确切的接收器名称、可用的配置，以及实际容易踩到的注意事项（Docker socket 权限、API 版本固定、host.docker.internal 与 localhost 的区别、IAM 权限、ADOT 与 Contrib Collector 镜像的区别）。

按照Collector 参考文档中的说明，设置相同的服务和资源元数据约定——host.name、service.name、service.instance.id——以便在 Hosts、Kubernetes 和 Metrics 页面上正确分组数据。

启动或重启 Collector 之前，先验证配置文件——接收器拼写错误或缩进有误时，应显示验证错误，而不是让 Collector 启动后不输出有用日志，并悄无声息地丢弃管道：

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

如果 PATH 中没有这两个二进制文件，请检查正在运行的 Collector 容器（例如使用 kubectl exec），或使用镜像入口点、systemd 单元或 Helm chart 中针对部署的验证命令。docker compose config 或 kubectl get pod <name> -o yaml 可以显示显式配置的命令。

第 4 步：验证

接收器配置完成不代表 Collector 顺利启动就万事大吉——请确认数据确实到达了对应主机／容器／集群的正确页面，而不只是确认有数据到达。未经本次会话中的查询，绝不要报告某项指标“已到达”——未经检查却听起来可信的总结，比坦言无法验证更糟。

1. 每次更改配置后都要重启 Collector（如上所述，先验证配置）。
2. 查询你配置的确切资源，而不只是页面上的任意数据。 如果本次会话中已连接 Logfire MCP 服务或 API，请在最近几分钟内查询你在第 3 步设置的特定 host.name／容器／集群；如果查询该确切标识符返回零行，即表示数据没有到达，即使页面显示了其他数据也一样。否则，请打开具体的产品页面——Hosts、Docker 或 Kubernetes——或者数据库／队列／缓存／云数据源对应的 Metrics 浏览器，并查找同一个确切标识符。
3. 如果没有显示任何内容，请依次检查：exporter 端点／区域和写入令牌；接收器是否位于有效管道中（而非仅定义了接收器，却未在 service.pipelines 下引用）；以及资源属性（host.name、service.name）是否已设置——参考文档中的 Verify 章节提供了完整的故障排查流程。
4. 修复并重新检查，直到能看到特定数据源，而不只是“某些”数据。

最后提交一份基于刚刚确认的信息撰写的报告——包括 whoami 返回的组织／项目／区域、处于活动状态的接收器，以及你已验证的确切主机／容器／集群标识符——不要使用模板。附上相关视图的直接链接（根据数据源使用 /hosts、/docker、/kubernetes 或 /metrics），链接中使用 whoami 返回的项目 URL，让用户无需询问查看位置就能看到自己的数据源。如果报告中含有占位符，说明上面的某一步被跳过了，而不是已完成。

参考资料

• 通过 OTel Collector 获取主机、Docker、Kubernetes、数据库／队列／缓存和云提供商指标——接收器配置、IAM／权限注意事项，以及该文档自身的验证流程。