Grafana LokiのログをClaudeで検索する — LogQLを書かない運用

障害調査の途中でLogQLの文法を思い出しながらログを絞り込むのは、地味に時間を食います。mcp-grafanaのLokiツールを使うと、「過去30分でエラーレベルのログを絞り込んで」という自然言語の指示から、Claude CodeがLogQLクエリを組み立ててGrafanaのLokiデータソースに投げます。クエリの中身を検証しないラベル戦略の監査ツールまで揃っているのが、ダッシュボード操作系のツールとの違いです。

Loki Queryingツールでできること

mcp-grafanaのLokiカテゴリは6つのツールで構成されます。ログクエリとメトリッククエリ両方に対応するquery_loki_logs、利用可能なラベル名の一覧を返すlist_loki_label_names、特定ラベルの値一覧を返すlist_loki_label_values、ログストリームの統計情報を返すquery_loki_stats、検出済みのログパターンを返すquery_loki_patterns、そしてラベル戦略を監査するanalyze_loki_labelsです。設定カテゴリには、Alloyのloki.process設定スニペットを生成するsuggest_loki_alloy_label_configもあります。

Claude Codeでの有効化

インストールとRBACスコープ設計の全体はmcp-grafanaの導入とRBAC設計を参照してください。Lokiツールは既定で有効なカテゴリです。ログ調査用のサービスアカウントを分けるなら、対象のLokiデータソースUIDにスコープを絞り込みます。

claude mcp add-json grafana-loki \
  '{"command":"uvx","args":["mcp-grafana","--enabled-tools","loki,datasource,search"],"env":{"GRAFANA_URL":"https://myinstance.grafana.net","GRAFANA_SERVICE_ACCOUNT_TOKEN":"<サービスアカウントトークン>"}}'

LogQLを書かずにログを検索する

query_loki_logsはログクエリとメトリッククエリの両方を実行できます。「〇〇サービスの過去1時間のエラーログを見せて」と頼めば、Claudeがラベルセレクタとフィルタを組み立ててLogQLとして実行します。1回のクエリで返す行数の上限は--max-loki-log-limit(既定100件)で制御でき、Loki側のmax_entries_limit_per_queryより1以上小さい値にしておくと、結果が切り詰められたことをツール側で検出できます。

ラベルを調べる

どんなラベルで絞り込めるか分からないときはlist_loki_label_namesでラベル名の一覧を、list_loki_label_valuesで特定ラベルが取りうる値を確認します。Prometheusの同種ツールと同じ発想で、クエリを組み立てる前段としてラベル空間を把握する用途に使います。

ログ量とパターンを把握する

query_loki_statsはログストリームの統計(ストリーム数・チャンク数・バイト数)を返します。query_loki_patternsは検出済みのログパターンを返し、大量のログの中から共通の構造や異常なパターンを見つける用途に向きます。どちらもログの中身そのものではなく、インデックスと統計情報を読むツールです。

Loki自体は、行フィルタを伴わないログクエリに対してmax_query_bytes_readを強制しません。ラベルセレクタが広く時間範囲も長いクエリは、テラバイト単位のスキャンになり得ます。

ラベル戦略を監査する

ログの絞り込みが遅い、ラベルの種類が多すぎて把握できない、といった悩みにはanalyze_loki_labelsが使えます。稼働中のLokiに対してライブでラベル戦略を監査することも、静的な設定を渡して監査することもでき、オプションでクエリのパフォーマンス診断まで行います。カーディナリティ(ラベル値のばらけ具合)が高すぎるラベル設計は、Lokiのインデックスサイズとクエリ速度の両方を悪化させるため、新しいログ収集を始める前に一度確認しておく価値があります。

監査の結果、承認済みのラベルだけを付与する設定に直したいときはsuggest_loki_alloy_label_configが使えます。Grafana Alloyのloki.processステージ向けの設定スニペットを生成するツールで、RBAC権限は不要です。ログ収集エージェント側の設定変更まで、Claudeとの対話だけで叩き台を作れます。

クエリのコストを抑えるガードレール

先ほどの通り、テラバイト単位のスキャンになり得る広いクエリをLoki自体は止めません。これを制御するのが--loki-guardrail-modeで、query_loki_logsに対するコストガードレールとして働き、既定はoffです。選択的なストリームセレクタを要求し、時間範囲の上限を課し、実行前にLokiのインデックス・統計APIでバイト数を見積もってから実行するかどうかを判断します。

しきい値は--loki-guardrail-max-bytes(既定100GiB、0で無効化)と--loki-guardrail-max-range(既定24時間、[30d]のようなレンジベクターの期間も含めて計算、0で無効化)で調整します。段階的に導入するなら、まずshadowでどのクエリが引っかかるかを観察してからenforceへ切り替える運用が安全です。VictoriaLogsのデータソースでは、括弧付きセレクタ({...})の形をしたクエリだけがガードレールの対象になり、セレクタなしの素のLogsQL構文は素通りします(安価なインデックス見積もりができないため)。

ガードレールの状況を監視する

--loki-guardrail-modeを有効にした運用では、Prometheusメトリクスエンドポイント(--metrics)を有効にすると、ガードレールの判定結果を示すカウンターが追加されます。

• mcp_loki_guardrail_admitted_total — 全チェックを通過したクエリ
• mcp_loki_guardrail_would_block_total — shadowモードでブロック対象になったが実行されたクエリ
• mcp_loki_guardrail_blocked_total — enforceモードで拒否されたクエリ
• mcp_loki_guardrail_fail_open_total — 評価できずそのまま通過したクエリ

いずれもbackend(loki / victorialogs / unknown)のラベルを持ちます。複数のチェックに同時に引っかかったクエリは、セレクタ→レンジ→バイト数の順で最初に引っかかった理由だけがカウントされます。shadowからenforceへ切り替える前に、would_block_totalがどの程度発生しているかをこのメトリクスで確認しておくと、切り替え後に正当なクエリまで拒否してしまう事故を避けやすくなります。

特定の名前空間だけに絞り込む

Grafana OSSにはデータソース単位・ユーザー単位のラベルアクセス制御が無いため、機微な情報を含むログストリームを閲覧させたくない場合は--loki-enforced-matchersでMCPサーバー自体に制限をかけます。指定したLogQLラベルマッチャーが、サーバーが発行するすべてのネイティブLokiクエリにAND条件として追加されます。

# prod / staging環境だけを許可(許可リスト)
uvx mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api
 
# vault / payments名前空間を除外
uvx mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

Lokiはセレクタ内のマッチャーをAND条件で評価するため、ユーザー側のクエリは強制されたマッチャーの範囲を狭める方向にしか動けません。ポリシーと矛盾するセレクタ(除外設定下で{namespace="vault"}を指定するなど)は、単に結果が空になります。適用範囲はquery_loki_logs・query_loki_stats・query_loki_patterns・list_loki_label_names・list_loki_label_valuesの5つです。

この制限は「フェイルクローズ」で動作し、マッチャーとして解釈できないクエリはフィルタなしで送るのではなく拒否されます。ただしVictoriaLogsのデータソースはLogsQLを安全に書き換えられないため、--loki-enforced-matchersを有効にすると丸ごと拒否されます。

制限を効かせるには他の経路も止める: --loki-enforced-matchersはLokiクエリツールにしか効きません。grafana_api_requestはLokiデータソースのプロキシへ直接クエリを投げられるため--disable-apiが必須です。get_panel_imageはLokiパネルをサーバー側でレンダリングするため--disable-rendering、Sift調査はサーバー側で全ストリームを横断解析するため--disable-sift、ask_assistantはGrafana Assistant経由で全ストリームを読めるため--disable-assistant(書き込みツールが有効なときだけ登録されるので--disable-writeでも塞げます)も合わせて無効化してください。これらを止めずに--loki-enforced-matchersだけ設定すると、制限は画面上は効いているように見えて別ルートから抜けられます。

メトリクスとログの使い分け

mcp-grafanaはPrometheus向けのツール群(query_prometheus、list_prometheus_label_namesなど)も持っていて、Lokiのツールとよく似た構成になっています。両者の境界は「数値の推移を追うか、テキストの中身を読むか」です。エラー率の急増をダッシュボードで検知したあと、原因になっている具体的なログ行を追うのがLokiツールの役割で、Prometheusツールが返す集計値だけでは分からない詳細をここで埋めます。

同じ障害調査の中でも、まずPrometheusで異常を数値として確認し、次にLokiで該当時間帯・該当ラベルのログを絞り込む、という順序で使うと自然です。ツール名の対応も揃っていて、list_prometheus_label_namesとlist_loki_label_names、list_prometheus_label_valuesとlist_loki_label_valuesのように、同じ発想のツールがデータソースごとに用意されています。

よくあるつまずき

--disable-queryを付けても統計とパターンは残る: query_loki_logsとquery_loki_patternsは無効になりますが、query_loki_statsとanalyze_loki_labelsはセレクタを送るだけでログの中身は返さないため登録されたままです。ログ内容そのものへのアクセスを完全に止めたいなら--disable-lokiでカテゴリごと無効化する必要があります。

負のマッチャーだけではラベル一覧が取れない: namespace!~"vault"のような除外だけのマッチャーは、Lokiが「正のマッチャーを含まない単独セレクタ」を受け付けないため、ラベル列挙系のツールをうまくスコープできません。--loki-label-enumeration-fallbackでreject(既定、列挙自体を拒否)かunfiltered(ラベルのメタデータだけ無制限に列挙を許可、ログ本文は出さない)を選びます。

サーバー起動時の警告を読み飛ばす: --loki-enforced-matchersを設定していても、--disable-apiなどの併用フラグが足りないとサーバーはその旨を起動時にログへ警告として出します。この警告を見落とすと、制限をかけたつもりで実際には迂回経路が残ります。

VictoriaLogsで急に拒否されるようになる: --loki-enforced-matchersを有効にした状態でVictoriaLogsデータソースへ問い合わせると、クエリはLogsQLを安全に書き換えられないという理由で丸ごと拒否されます。Lokiと同じ設定のまま複数バックエンドを併用している環境では、想定外のデータソースだけ動かなくなったように見えることがあります。

まとめ

Lokiツールを使えば、LogQLの文法を都度思い出さなくても自然言語からログ検索・ラベル調査・ログ量の把握まで進められます。実務での要点は、コストの大きいクエリを--loki-guardrail-modeで制御することと、機微なログストリームを見せたくないなら--loki-enforced-matchersと関連フラグをセットで止めることの2つです。ダッシュボード操作を含めた全体のRBAC設計はmcp-grafanaの導入とRBAC設計、障害時の当番確認はGrafana OnCallをClaudeで操作する記事を合わせて確認してください。