Claude Codeでgcloud logging readを使い、Cloud Loggingのエラーを調べる

Cloud Loggingのエラーを調べるとき、ログを丸ごとClaude Codeに渡す必要はありません。gcloud logging readでfilterを書いて絞り、--limitと--format=jsonで量を抑えてからclaude -pにパイプすれば、原因の切り分けだけを任せられます。

この記事では、filterの書き方、時間範囲の指定、取得量の制限、パイプの渡し方、そしてClaudeにgcloudを実行させるときの権限設定を順に扱います。AWS側の同じ作業はClaude CodeでCloudWatch Logsを集計しエラーの急増を見つけるにあります。

gcloud logging readは「新しい順」に返す

gcloud logging readは、LOG_FILTERに一致するログエントリをタイムスタンプの新しい順に返します。複数のログにまたがる場合は、別々のログのエントリが混ざって出ます。

Claudeに渡す前に知っておきたい指定は次の5つです。

--limitの既定が無制限である点が、このあと効いてきます。何も付けずに実行すると、1日分のログが全件返ります。

エラーだけを取り出すfilterの形

公式のコマンド例には、重大度とリソースの種類で絞る形があります。

# ERROR以上のエントリ
gcloud logging read "severity>=ERROR"
 
# Compute Engineのエントリ
gcloud logging read "resource.type=gce_instance"

2つを組み合わせるときはANDでつなぎます。Logging query languageでは、比較の間のANDを省いて改行や空白で並べても、暗黙のANDとして扱われます。ただしANDとORは大文字で書く必要があります。

resource.type = "gce_instance" AND severity >= "ERROR"

文字列の比較は大文字小文字を区別しません。textPayload:robotのように:を使うと、そのフィールドのどこかにrobotを含むエントリに一致します。除外したい語はAND NOT textPayload:robotと書きます。

JSONで出力されるエントリのフィールドは、timestamp、severity、textPayload、jsonPayload、resource、insertIdなどです。filterの左辺は、ログエントリ(LogEntry型)に定義されたフィールドでなければなりません。

時間範囲は--freshnessかtimestampのどちらか一方で指定する

時間の絞り込みには、2通りの書き方があります。

1つ目は--freshnessです。--freshness=2hのように期間を渡すと、それより古いエントリが除かれます。2つ目はfilterの中にtimestampの条件を書く方法です。

timestamp>="2026-10-28T00:00:00Z" AND timestamp<="2026-10-28T01:00:00Z"

障害の経緯を時系列で読ませたいときは、--order=ascで古い順に取り出す手もあります。降順のままだと、--limitで切ったときに最新側だけが残り、発端のエラーが落ちるためです。昇順で取るときは、前述のとおりfilterにtimestampの下限を書きます。

--freshnessの既定は1dなので、「3日前の障害を見たい」のにtimestampも--freshnessも付けないと、何も返らない結果になりえます。時間が絡む調査では、どちらで範囲を決めたかをプロンプトに書いておくと、Claudeが後から再実行するときにも迷いません。

量を抑えてclaude -pに渡す

claude -pは標準入力を読めるので、他のコマンドと同じようにパイプで受け取れます。公式の例も、ビルドログをパイプして根本原因を説明させる形です。

gcloud logging read \
  'resource.type="cloud_run_revision" AND severity>=ERROR' \
  --freshness=2h --limit=50 --format=json \
| claude -p 'これらのエラーログを、原因が同じものごとにまとめて説明して'

resource.typeの値cloud_run_revisionは例です。自分のサービスの種類に合わせて置き換えてください。

渡す量を決める要素は3つあります。

• --limit: 件数の上限。新しい順に返るので、最新のN件が残ります
• --freshnessまたはtimestamp: 期間の上限と下限
• --format=json: Claudeが読みやすい構造で受け渡す

標準入力には上限があります。パイプで渡せるデータは10MBまでで、超えるとClaude Codeはエラーメッセージを出して、ゼロ以外の終了ステータスで止まります。それ以上の量を扱うときは、いったんファイルに保存し、プロンプトにそのパスを書いて読ませる方法が公式に案内されています。

gcloud logging read 'severity>=ERROR' --freshness=6h --limit=200 \
  --format=json > errors.json
 
claude -p "errors.json を読み、エラーの種類ごとに件数と代表的なメッセージを一覧にして"

jqで項目を落とす

--format=jsonのエントリには、調査に要らないフィールドも含まれます。jqで必要な項目だけ残すと、同じ件数でもトークンを節約できます。

gcloud logging read 'severity>=ERROR' --freshness=2h --limit=100 --format=json \
| jq '[.[] | {t: .timestamp, sev: .severity,
    res: .resource.labels,
    msg: (.textPayload // .jsonPayload)}]' \
| claude -p '共通する原因を推定して、確認すべきログを挙げて'

jsonPayloadの中身はアプリケーションごとに違います。jsonPayload.messageのようにキーを決め打ちする前に、手元で1件出力して構造を確かめてください。

Claudeにfilterを書かせて実行まで任せる

ここまでは人間がfilterを書く流れでした。次はClaudeにfilterを書かせ、gcloud logging readの実行までを任せる形です。

claude -pでBashを許可するには--allowedToolsを使います。公式のコミット作成の例と同じく、Bash(コマンド *)の形で、コマンドの先頭一致で許可を絞れます。末尾の *の前にはスペースが必要です。

claude -p "直近2時間にmy-projectで出たERROR以上のログを調べ、原因を推定して。
gcloud logging readには必ず --limit と --format=json を付けること" \
  --allowedTools "Bash(gcloud logging read *)"

この許可は、gcloud logging readで始まるコマンドだけを通します。別のコマンドは、-pの手動モードでは承認する手段がなければ拒否されます。

毎回の起動で同じ制約を効かせたいときは、プロジェクトの.claude/settings.jsonに許可ルールを書き、CLAUDE.mdに取得量のルールを置く方法もあります。

{
  "permissions": {
    "allow": ["Bash(gcloud logging read *)"]
  }
}

## ログ調査のルール
- gcloud logging read には必ず --limit と --format=json を付ける
- 時間範囲は --freshness か timestamp のどちらか一方で指定する
- まず severity>=ERROR で絞り、足りなければ WARNING まで広げる

CIや定期ジョブのように、誰も承認できない環境では--permission-mode dontAskが使えます。許可していない呼び出しはすべて拒否され、--allowedToolsの許可だけが通ります。スクリプトで再現性を高めたいときは--bareも候補で、フックやMCPサーバー、CLAUDE.mdを読み込まずに起動します。その場合はANTHROPIC_API_KEYを環境変数に設定する必要があります。

認証が切れてgcloudが失敗するときは、Claude CodeのawsAuthRefreshとgcpAuthRefreshで認証切れを自動更新の設定が使えます。

結果を機械で読める形で受け取る

調査結果を次の処理に渡したいときは、--output-format jsonと--json-schemaを組み合わせます。スキーマに合った出力はstructured_outputフィールドに入ります。

gcloud logging read 'severity>=ERROR' --freshness=2h --limit=100 --format=json \
| claude -p 'エラーを原因ごとに分類して' \
  --output-format json \
  --json-schema '{"type":"object","properties":{"causes":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"count":{"type":"integer"}},"required":["summary","count"]}}},"required":["causes"]}' \
| jq '.structured_output'

Claudeが依頼を断った場合など、有効な構造化出力が得られなかったときはstructured_outputが含まれません。スクリプトでは、使う前にこのフィールドの有無を確かめてください。

読む対象を切り替える指定

何も指定しないと、gcloudの現在のプロジェクトのログを読みます。現在のプロジェクトはgcloud config list --format='text(core.project)'で確かめられます。別のプロジェクトを読むなら--projectを付けます。

読む範囲を変える指定は、次のうちどれか1つしか同時に使えません。

これとは別に、--resource-namesでリソース名をカンマ区切りで複数渡せます。ログバケットのビューを直接読むときは、--bucket、--location、--viewの3つをそろえて指定します。1つでも欠けると指定として成り立ちません。

Claudeにプロンプトで「どのプロジェクトか」を明示しないと、現在のプロジェクトを読みに行きます。本番と検証でgcloudの設定を切り替えている環境では、プロンプトに--projectの値を書いておくほうが取り違えを防げます。

追い質問とコストの見方

1回目の調査で原因の候補が出たら、--continueで同じ会話を続けて、追加の取得を頼めます。

# 1回目
gcloud logging read 'severity>=ERROR' --freshness=2h --limit=100 --format=json \
| claude -p 'エラーを原因ごとに分類して'
 
# 直近の会話を続ける
claude -p "一番多い原因の前後30分を、timestampで切って読み直して" --continue \
  --allowedTools "Bash(gcloud logging read *)"

--output-format jsonにすると、応答にtotal_cost_usdとモデルごとの内訳が含まれます。ログ調査のスクリプトを定期実行するときは、この値で1回あたりの費用を把握できます。--continueや--resumeで会話を続けた場合は、続けた会話全体の合計が出ます。どちらもクライアント側の推定値で、実際の請求額とは差が出ることがあります。

よくあるつまずき

結果が空、または想定より少ないときは、次の順で確かめます。

1. --freshnessの既定(1日)に収まっているか。timestampを含むfilterなら、--freshnessではなくfilterの時間窓が効いているか
2. --projectが意図したプロジェクトか。現在のプロジェクトが別のものになっていないか
3. filterのANDとORが大文字か。小文字だと論理演算子として扱われません
4. resource.typeの値がログの実際のリソース種別と一致しているか。まず--limit=1で1件取り、resourceの中身を見ると確実です
5. --limitが小さすぎて、目的のエントリが期間の古い側にあって切れていないか。新しい順に返るため、古い側から切れます

gcloud自体が認証エラーで失敗する場合は、claude -pの問題ではなくgcloud側の認証状態です。Claude Code経由でGoogle Cloudを使うときの401や403は、Google Cloud credentials expiredの直し方で切り分けられます。

調べさせた結果を鵜呑みにしない

ログの要約は、渡した範囲のログに基づく推定です。--limitで切った分や、--freshnessの外にあるエントリは、Claudeからは見えません。原因の候補が出たら、該当時刻の前後をtimestampで切り直して再取得し、仮説を確かめる流れにすると安全です。

Claudeにテーブル定義や課金データまで見せたい場面では、gcloud MCPサーバーをClaude Codeに追加してGoogle Cloudを操作するの方法もあります。ログの読み取りだけなら、CLIをパイプでつなぐ形のほうが、渡すデータを自分で決められます。

まとめ

gcloud logging readは、新しい順に返し、期間は--freshness(既定1日)かfilter内のtimestampで決め、件数は--limitで止めないと無制限です。この3点を押さえてからclaude -pに渡すと、10MBの標準入力上限にも当たりにくくなります。時間窓を切って調べ直す場面ではtimestampを使い、それ以外の定期チェックは--freshnessで十分、と使い分けるのが分かりやすい構成です。