gcp-logs

GCP ログクエリスキル

使用する場面

• リレイヤー、バリデーター、スクレイパーの動作を調査する場合
• メッセージ処理の問題をデバッグする場合
• 運用インシデントを分析する場合
• エージェントのログから特定のエラーやパターンを探す場合

前提条件

• gcloud CLI がインストールされ、認証済みであること
• abacus-labs-dev GCP プロジェクトへのアクセス権があること

基本クエリテンプレート

リレイヤー（Omniscient）

gcloud logging read 'resource.type="k8s_container" AND resource.labels.project_id="abacus-labs-dev" AND resource.labels.location="us-east1-c" AND resource.labels.cluster_name="hyperlane-mainnet" AND resource.labels.namespace_name="mainnet3" AND labels.k8s-pod/app_kubernetes_io/component="relayer" AND labels.k8s-pod/app_kubernetes_io/instance="omniscient-relayer" AND labels.k8s-pod/app_kubernetes_io/name="hyperlane-agent"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

バリデーター

gcloud logging read 'resource.type="k8s_container" AND resource.labels.project_id="abacus-labs-dev" AND resource.labels.location="us-east1-c" AND resource.labels.cluster_name="hyperlane-mainnet" AND resource.labels.namespace_name="mainnet3" AND labels.k8s-pod/app_kubernetes_io/component="validator" AND labels.k8s-pod/app_kubernetes_io/name="hyperlane-agent"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

スクレイパー

gcloud logging read 'resource.type="k8s_container" AND resource.labels.project_id="abacus-labs-dev" AND resource.labels.location="us-east1-c" AND resource.labels.cluster_name="hyperlane-mainnet" AND resource.labels.namespace_name="mainnet3" AND labels.k8s-pod/app_kubernetes_io/component="scraper3" AND labels.k8s-pod/app_kubernetes_io/instance="omniscient-scraper" AND labels.k8s-pod/app_kubernetes_io/name="hyperlane-agent"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

ノイズのフィルタリング

価値のある情報を提供せず、コンテキストを消費するノイズの多いログ行を減らすには、次のフィルターを追加します。

-jsonPayload.fields.message="Found log(s) in index range"
-jsonPayload.fields.message="Dispatching get_public_key"
NOT "Instantiated AWS signer"
-jsonPayload.fields.message="Ingesting leaf"
-jsonPayload.fields.message="Message already marked as processed in DB"
-jsonPayload.fields.message="Message destined for self, skipping"
-jsonPayload.fields.message="Message has already been delivered, marking as submitted."
-jsonPayload.fields.message="Popped OpQueue operations"
-jsonPayload.fields.message="Validator returned latest index"
-jsonPayload.fields.message="Found signed checkpoint"
-jsonPayload.fields.return="Ok(None)"
-jsonPayload.fields.message="Fast forwarded current sequence"
-jsonPayload.fields.message="Cursor can't make progress, sleeping"
-jsonPayload.fields.message="fallback_request"
-jsonPayload.fields.message="No message found in DB for leaf index"
-jsonPayload.fields.message="Processor working on message"
-jsonPayload.fields.message="Message destined for unknown domain, skipping"

段階的なクエリ戦略（トークン効率）

ステップ 1：最初はメッセージフィールドのみを取得する

コンテキストの消費を最小限に抑えるため、まず message フィールドのみを取得します。

gcloud logging read '[BASE_QUERY] AND "[search_term]"' --project=abacus-labs-dev --limit=30 --format='json(jsonPayload.fields.message,timestamp)' --freshness=1d

これにより、ログのペイロード全体を取得せずに概要をすばやく把握できます。

ステップ 2：特定のエントリーの詳細なコンテキストを取得する

注目すべきログエントリーを特定したら、詳細をすべて取得します。

gcloud logging read '[BASE_QUERY] AND "[specific_identifier]"' --project=abacus-labs-dev --limit=20 --format=json --freshness=1d

ステップ 3：特定のフィールドを抽出する

特定の詳細が必要な場合は、jq または grep を使って抽出します。

gcloud logging read '[QUERY]' --format=json | jq '.[].jsonPayload.fields.error'

よく使うクエリパターン

メッセージ ID で検索する

gcloud logging read '[BASE_QUERY] AND "0x[MESSAGE_ID]"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

エラー／警告を検索する

gcloud logging read '[BASE_QUERY] AND severity>="WARNING"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

チェーン／ドメインで検索する

gcloud logging read '[BASE_QUERY] AND jsonPayload.spans.domain:"[chain_name]"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

停滞したメッセージを検索する（リトライ回数が多いもの）

gcloud logging read '[BASE_QUERY] AND jsonPayload.fields.num_retries>=5' --project=abacus-labs-dev --limit=30 --format=json --freshness=1d

ガス見積もりエラーを検索する

gcloud logging read '[BASE_QUERY] AND "eth_estimateGas"' --project=abacus-labs-dev --limit=30 --format=json --freshness=1d

アプリケーションコンテキストで検索する

gcloud logging read '[BASE_QUERY] AND jsonPayload.fields.app_context:"[APP_CONTEXT]"' --project=abacus-labs-dev --limit=30 --format=json --freshness=1d

時間範囲のオプション

• --freshness=1h - 過去 1 時間
• --freshness=1d - 過去 1 日
• --freshness=7d - 過去 1 週間
• または、フィルターに明示的なタイムスタンプを指定します：timestamp>="2026-01-27T00:00:00Z"

出力形式のオプション

• --format=json - JSON 全体（詳細で、コンテキストを多く消費）
• --format='json(jsonPayload.fields.message,timestamp)' - 特定のフィールドのみ（効率的）
• --format='value(jsonPayload.fields.message)' - 値のみ（構造なし）

注目すべき主なログフィールド

フィールド	説明
jsonPayload.fields.message	主なログメッセージ
jsonPayload.fields.error	エラーの詳細
jsonPayload.spans[].domain	関連するチェーン
jsonPayload.fields.num_retries	リトライ回数
jsonPayload.fields.operations	保留中のメッセージの詳細
jsonPayload.span.id	スパンコンテキスト内のメッセージ ID

環境ごとの違い

環境	名前空間	クラスター
mainnet3	mainnet3	hyperlane-mainnet
testnet4	testnet4	hyperlane-mainnet

ヒント

1. 最初は対象を絞る - まず、正確なメッセージ ID またはエラーパターンを検索します
2. ノイズフィルターを使う - 基本ログには多くのノイズが含まれるため、必ずフィルタリングします
3. 結果を制限する - コンテキストが過剰になるのを防ぐため、--limit を使います
4. 段階的に詳細化する - 最初はメッセージフィールドのみを取得し、必要に応じて詳細を増やします
5. クエリの時間範囲を限定する - --freshness またはタイムスタンプフィルターを使います
6. grep／jq にパイプする - 大きな結果をローカルで後処理します