logfire-query

Logfire データをクエリする

このスキルを使用する場面

次の場合にこのスキルを呼び出します。

• ユーザーが Logfire のトレース、ログ、スパン、またはメトリクスをクエリしたい場合
• ユーザーがテレメトリデータから特定のイベント、エラー、またはパターンを検索したい場合
• ユーザーが Logfire に保存された OpenTelemetry データを分析したい場合
• ユーザーがコードにプログラムによるクエリ機能を追加したい場合
• ユーザーが「logfire をクエリする」「トレースを検索する」「ログを探す」「メトリクスを取得する」「件数を数える」「要約する」「比較する」「根本原因を特定する」と尋ねた場合

ユーザー向けの進捗状況

進捗の更新は簡潔にしてください。ルートの分類、ローカルスキルの指示、スキーマの選択、通常のクエリ設定について説明しないでください。更新が必要な場合は、「Logfire の最近のエラーをクエリしています。」のように、実行中の操作に焦点を当てた短い文を使ってください。

重要なルーティング：リクエストごとに 1 つのワークフロー

クエリツールを使用する前に、リクエストを分類してください。

• クエリルート：「分析する」「クエリする」「件数を数える」「要約する」「比較する」「根本原因を特定する」「最も遅いものを探す」「エラーを調べる」「メトリクスを取得する」「クエリ機能を追加する」。
• UI ルート：「開く」「ブラウザーで表示する」「Codex で表示する」「Logfire で表示する」「ライブビュー」「Explore を開く」「UI を開く」「リンクを教える」、または GUI／ブラウザーでの表示。logfire-ui を使用してください。URL を作成するだけの目的で query_run を呼び出さないでください。
• あいまいなルート：「最近のエラーを表示する」「ログを表示する」「スパンを表示する」のように、チャットでの分析を求めているのか、Logfire UI での表示を求めているのか明確でないプロンプトです。クエリ分析と UI 表示のどちらを希望するか、ユーザーに確認してください。
• 複合ルート：分析とリンクの両方を明示的に求められた場合は、依頼された分析を行う場合、または依頼された項目を特定する場合に限ってクエリし、その後、該当する Logfire リンクを提示してください。ユーザーから求められていない限り、UI／ブラウザーでの操作を追加しないでください。

「最も遅いトレースを探して開く」「最新のエラートレースを開く」のように、開く前に特定が必要な不明な項目を開くようユーザーが求めた場合に限り、Logfire UI を開く前にクエリしてください。

2 つの方法

項目	MCP query_run	REST API /v1/query
最適な用途	Codex での対話型分析	プロジェクトへのクエリコードの追加
認証	MCP セッション経由の OAuth	Bearer 読み取りトークン
セットアップ	プラグイン経由で設定済み	読み取りトークンが必要
形式	JSON の行	JSON、CSV、Apache Arrow
デフォルトの期間	直近 30 分	過去 24 時間
最大範囲	14 日間	14 日間
行数の上限	SQL に指定する必要あり	デフォルト 500、最大 10,000

スキーマのクイックリファレンス

records テーブル（スパンとログ）

クエリで使う主要な列：

列	型	説明
start_timestamp	timestamp (UTC)	スパン／ログが作成された時刻
end_timestamp	timestamp (UTC)	スパン／ログが完了した時刻
duration	double (seconds)	開始から終了までの時間。ログの場合は NULL
trace_id	string (32 hex)	一意のトレース識別子
span_id	string (16 hex)	一意のスパン識別子
parent_span_id	string (16 hex)	親スパン。ルートスパンの場合は NULL
span_name	string	類似レコードに付けるカーディナリティの低いラベル
message	string	引数が埋め込まれた、人が読める説明
level	integer	重要度（level = 'error' のような文字列比較に対応）
kind	string	span、log、span_event、または pending_span
service_name	string	サービス識別子
is_exception	boolean	例外が記録されたかどうか
exception_type	string	例外クラス名
exception_message	string	例外メッセージ
exception_stacktrace	string	完全なトレースバック
attributes	JSON	構造化データ。->>'key' でクエリ
tags	string[]	グループ化ラベル。array_has(tags, 'x') でクエリ
http_response_status_code	integer	HTTP ステータスコード
http_method	string	HTTP メソッド
http_route	string	HTTP ルートパターン
otel_status_code	string	スパンのステータス

metrics テーブル

列	型	説明
recorded_timestamp	timestamp (UTC)	メトリクスが記録された日時
metric_name	string	メトリクス名
metric_type	string	種類（gauge、counter、histogram）
unit	string	測定単位
scalar_value	double	メトリクス値
service_name	string	サービス識別子
attributes	JSON	メトリクスのディメンション

スキーマ全体：references/schema.md

SQL 構文

Logfire は Apache DataFusion（Postgres に似た構文）を使用します。主なパターン：

-- Time filtering
WHERE start_timestamp > now() - interval '1 hour'

-- JSON attribute access
WHERE attributes->>'user_id' = '123'
SELECT attributes->>'http.url' as url FROM records

-- Nested JSON
attributes->'request'->>'method'

-- Array filtering
WHERE array_has(tags, 'production')

-- Level filtering (string comparison works)
WHERE level = 'error'

-- Case-insensitive matching
WHERE message ILIKE '%timeout%'

-- Time bucketing for aggregation
SELECT time_bucket(interval '5 minutes', start_timestamp) as bucket,
       count(*) FROM records GROUP BY bucket ORDER BY bucket

MCP のアプローチ（対話型）

query_run MCP ツールを呼び出します：

• query（必須）：SQL クエリ文字列
• project（任意）：対象プロジェクト（デフォルトはユーザーの現在のプロジェクト）
• min_timestamp / max_timestamp（任意）：時間範囲を指定する ISO タイムスタンプ

デフォルトの範囲は直近 30 分です。最大範囲は 14 日間です。SQL には必ず LIMIT を含めてください。

よく使うクエリ

-- Recent errors
SELECT start_timestamp, message, exception_type, exception_message
FROM records WHERE is_exception LIMIT 20

-- Slow spans
SELECT span_name, duration, start_timestamp
FROM records WHERE duration > 1.0 ORDER BY duration DESC LIMIT 20

-- Endpoint errors
SELECT start_timestamp, message, http_response_status_code
FROM records WHERE http_route = '/api/users' AND level = 'error' LIMIT 20

-- Full trace
SELECT span_name, message, duration, parent_span_id
FROM records WHERE trace_id = '<id>' ORDER BY start_timestamp

-- Error breakdown by service
SELECT service_name, count(*) as errors
FROM records WHERE is_exception GROUP BY service_name ORDER BY errors DESC

クエリ実行後の UI リンク

ユーザーが分析と Logfire のリンクの両方を明示的に求めた場合は、まずクエリの分析を完了してから、結果がわかっている場合に限り Logfire のリンクを使用します：

• trace_id がわかっている場合、ユーザーがブラウザーでただちに開くよう求めたときに限り、project_logfire_link(trace_id=trace_id, project=project, handoff=True) を使用します。永続的に利用できるリンクや共有可能な URL には、project_logfire_link(trace_id=trace_id, project=project) を使用します。
• プロジェクト／フィルタービューには、logfire-ui のルーティングルールを使用します。
• ユーザーがリンクを開くよう求めていない限り、ブラウザーを開かないでください。

スパン数を求めるプロンプトで、ユーザーが集計クエリまたは分析を希望する場合は、次のような SQL を提示します：

SELECT
  time_bucket(interval '5 minutes', start_timestamp) AS bucket,
  count(*) AS span_count
FROM records
WHERE kind = 'span'
GROUP BY bucket
ORDER BY bucket
LIMIT 200

REST API のアプローチ（プログラムによる利用）

エンドポイント：GET https://logfire-api.pydantic.dev/v1/query

リージョン別のエンドポイント：

• US：https://logfire-us.pydantic.dev/v1/query
• EU：https://logfire-eu.pydantic.dev/v1/query

認証：Authorization: Bearer <read_token>

パラメーター：

• sql（必須）：SQL クエリ
• min_timestamp / max_timestamp（任意）：ISO タイムスタンプ
• limit（任意）：行数の上限（デフォルト 500、最大 10,000）

レスポンス形式（Accept ヘッダーで指定）：

• application/json — 列指向 JSON（デフォルト）
• application/json と row_oriented=true パラメーター — 行指向 JSON
• text/csv — CSV
• application/vnd.apache.arrow.stream — Apache Arrow

Python クライアント：LogfireQueryClient（同期）、AsyncLogfireQueryClient（非同期）、logfire.db_api（PEP 249／pandas）。

詳細な例：references/client-usage.md

クエリのベストプラクティス

1. 必ず LIMIT を指定する — まず 20 に設定し、必要に応じて増やします
2. 単純な時間範囲には SQL の WHERE ではなく、min_timestamp／max_timestamp パラメーターを使用する
3. 効率的にフィルターする — service_name、span_name、trace_id、is_exception は高速なフィルターです
4. JSON 属性へのアクセスには ->>'key' を使用する（テキストを返します）。ネストされた JSON オブジェクトには -> を使用します
5. SELECT * を避ける — 必要な列だけを選択します
6. 最大範囲は 14 日間 — クエリの範囲を 14 日間より長くすることはできません