logfire-infrastructure

Logfire でインフラストラクチャを監視する

アプリケーションレベルのトレース、ログ、AI／エージェントのスパンには、このスキルを使用しないでください。それには logfire-instrumentation を使用します。この2つは組み合わせて使用でき、通常、完全なセットアップでは両方を実行します。

仕組み

OpenTelemetry Collector は、ホスト、コンテナー、クラスター、インフラストラクチャサービスのメトリクスを、アプリケーションコードを変更せずに Logfire へ送信します。Logfire は完全準拠の OTel バックエンドであり、標準の OTLP トレース、ログ、メトリクスを Collector から取り込むため（Collector のリファレンスに記載されている例外が1つあります）、Collector がすべての処理を担います。これは任意の高度なツールです。アプリケーション自体のトレースだけが必要な場合は、logfire-instrumentation の言語 SDK だけで十分です。

ステップ 1：認証して、対象プロジェクトを正確に選択する

whoami で正しいプロジェクトに認証されていることを確認するまで、インフラストラクチャ設定ファイル（docker-compose.yml、Kubernetes マニフェストなど）を開いたり、読んだり、実行したりしないでください。このステップには、監視対象を把握する必要はありません。認証は人間の操作（ブラウザーでのサインイン）が必要になる可能性がある唯一のステップでもあるため、最初に開始すれば、ステップ 2 の検出作業後ではなく、最初のターンから待ち時間が始まります。

認証して、対象プロジェクトを正確に選択するを使い、提示された Logfire URL から CLI のターゲットを特定して、確認済みの CLI パスでターゲットを指定した whoami チェックを実行してください。uv を使わない JS／TS プロジェクトでは、リポジトリ内のバイナリを実行する可能性がある通常の npx ではなく、外部プレフィックスを指定する npm のフォールバックを使ってください。すでに正しいプロジェクトと解決済みの --region または --base-url ターゲットが表示されていれば、ステップ 2 に進んでください。そうでなければ、projects use で作成された書き込み用認証情報を安全に引き渡す方法も含め、そこで説明されている認証とプロジェクト選択の手順を最後まで実行してください。

ステップ 2：監視対象を特定する

推測せず、実際に使用されているインフラストラクチャを検出してください。

• ホスト／VM：マシン自体（CPU、メモリ、ディスク、ネットワーク、負荷）を監視します。
• Docker：実行中のコンテナーについて、docker-compose.yml／Dockerfile を確認します。
• Kubernetes：マニフェスト、kubeconfig、または kubectl のコンテキストを探します。
• データベース／キュー／キャッシュサーバー：Postgres、MySQL、Redis、MongoDB、Kafka、RabbitMQ、Nginx、Apache、Elasticsearch、Memcached について、docker-compose.yml／pyproject.toml／package.json を確認します。
• クラウドプロバイダー：ユーザーがプロバイダーを指定している場合、またはアプリケーションが明らかにそこで実行されている場合は、GCP または AWS のメトリクス（Cloud Monitoring、CloudWatch、ECS）を対象とします。

複数が同時に該当する場合もあります。1つの Collector で、複数のレシーバーを並列パイプライン上で実行できます。

ステップ 3：コレクターを設定する

ステップ 2 で特定したレシーバーについて、コレクターのリファレンスに従ってください。共通のエクスポーター設定に続き、各ソース（ホストメトリクス、Docker、Kubernetes、データベース／キュー／キャッシュサーバー、クラウドプロバイダーのメトリクス）専用のセクションがあり、それぞれ正確なレシーバー名、動作する設定、実際に問題になる注意点（Docker ソケットの権限、API バージョンの固定、host.docker.internal と localhost の違い、IAM 権限、ADOT と Contrib コレクターイメージの違い）が記載されています。

コレクターのリファレンスに記載されたサービスとリソースのメタデータ規約（host.name、service.name、service.instance.id）も設定してください。こうすることで、Hosts、Kubernetes、Metrics の各ページでデータが正しくグループ化されます。

コレクターを起動または再起動する前に、設定ファイルを検証してください。レシーバーのタイプミスや不適切なインデントは、コレクターが起動しても有用なログを出さず、パイプラインを黙って破棄するのではなく、検証エラーとして検出されるべきです。

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

どちらのバイナリも PATH 上にない場合は、実行中のコレクターコンテナーを調べる（たとえば kubectl exec を使う）か、イメージのエントリーポイント、systemd ユニット、Helm チャートに記載されたデプロイ方法固有の検証コマンドを使用してください。docker compose config または kubectl get pod <name> -o yaml を使うと、コマンドが明示的に設定されている場合に確認できます。

ステップ 4：検証する

レシーバーの接続は、コレクターが正常に起動しただけでは完了ではありません。何かのデータが届いたことだけでなく、データが対象のホスト／コンテナー／クラスターの正しいページに届いていることを確認してください。同じセッション内でクエリを実行していないメトリクスを、「到着した」と報告してはいけません。確認していないのにそれらしくまとめるより、検証できなかったと伝えるほうが適切です。

1. 設定を変更した後は、コレクターを再起動します（上記の検証を済ませてから）。
2. ページに表示されている任意のデータではなく、設定した正確なリソースをクエリします。 このセッションで Logfire MCP サーバーまたは API に接続できる場合は、直近数分以内にステップ 3 で設定した特定の host.name／コンテナー／クラスターをクエリしてください。その正確な識別子に対するクエリで 0 行が返された場合、ページに別のデータが表示されていても、そのデータは届いていません。それ以外の場合は、Hosts、Docker、Kubernetes の各製品ページ、またはデータベース／キュー／キャッシュ／クラウドソースの場合は Metrics エクスプローラーを開き、同じ正確な識別子を探してください。
3. 何も表示されない場合は、次の順に確認します。エクスポーターのエンドポイント／リージョンと書き込みトークン、レシーバーがアクティブなパイプラインに含まれていること（定義されているだけで service.pipelines から参照されていない状態ではないこと）、リソース属性（host.name、service.name）が設定されていること。リファレンスの Verify セクションに、トラブルシューティングの手順がすべて記載されています。
4. 特定のソースが表示されるまで修正して再確認します。「何らかの」データが表示されるだけでは不十分です。

最後に、たった今確認した内容に基づいてレポートを作成します。テンプレートではなく、whoami で確認した組織／プロジェクト／リージョン、有効なレシーバー、検証した正確なホスト／コンテナー／クラスター識別子を記載してください。ソースに応じてプロジェクトの whoami URL を使った関連ビューへの直接リンク（/hosts、/docker、/kubernetes、または /metrics）を必ず含めてください。ユーザーがどこを見ればよいか尋ねなくても、自分のソースの到着を確認できるようにします。プレースホルダーが含まれたレポートは、上記のステップが完了ではなく、スキップされたことを意味します。

リファレンス

• OTel Collector を介したホスト、Docker、Kubernetes、データベース／キュー／キャッシュ、クラウドプロバイダーのメトリクス — レシーバーの設定、IAM／権限に関する注意点、独自の検証手順。