2026-09-16

Grafana CloudのCLI「gcx」を試してみる

個人で開発しているアプリケーションの監視には基本的にGrafana Cloudを利用しています。 Grafana CloudはgcxというCLIを提供しており、こちらを利用することでGrafana Cloud上の操作をコマンド経由で行うことができます。 (AWS CLIのようなもの)

今回はこのgcxについて、ログ取得をテーマにして簡単に理解していこうと思います。

gcxコマンドのセットアップ

公式インストール手順に沿ってインストールを行います。

インストールが完了したら、ログインしてみます。

❯ gcx login
Refreshing context "xxx" (server: https://xxx.grafana.net)

┃ Authentication method
┃ > OAuth (browser) — recommended for cloud stacks; experimental on some
┃   configurations, fall back to a service account token if you hit issues
┃   OAuth (browser on another computer) — gcx prints a URL; you paste the
┃   redirect URL back. Use this over SSH
┃   Service account token (requires permissions for managing service accounts)

一番上のOAuth (browser)を選択するとブラウザが開くので、そこで権限を選択します。今回はRead権限しか必要ないので、Read以外の全てのチェックマークを外して確認します。

gcxでログを取得する

gcxのセットアップとログイン処理が完了したので、まずは簡単にログの取得を試してみます。

リファレンスはGitHubにあるので、それを見て使いかたを確認します。

素朴にログをappラベルでフィルタリングする場合には、次のようなコマンドを実行すれば良さそうです。

-dにはLokiデータソースのUIDを指定します。以下のgrafanacloud-logsと、appラベルの値であるxxxは、自分の環境に合わせて置き換えてください。

# 過去7日間のapp = xxxのログを最大50件取得
gcx logs query -d grafanacloud-logs '{app="xxx"}' --since 7d

TIME        │ LEV… │ SOURCE      │ STREAM       │ MESSAGE      │ DETAILS
...

--since 7dは検索期間の指定で、取得件数の上限はデフォルトで50件です。上限を変更したい場合は--limitで指定できます。

また、例えばerrorという文字列を含むログに絞る場合は、次のようにフィルタリングできます。

gcx logs query -d grafanacloud-logs '{app="xxx"} |= "error"' --since 7d

何も指定しないと表形式みたいな感じでログが表示されました。 -o オプションを指定することで出力フォーマットを指定することができるようです。 raw、jsonをはじめとして、agentsというagent用の出力まで用意されていてモダンな感じがしますね。

-o, --output string       Output format. One of: agents, json, raw, table, wide, yaml (default "table")

試しにagents形式で出力してみたところ、一切の無駄な文字列を含まないギチギチの形のログが出力されました。そりゃそうか。

公式skillについて

gcxではコマンド経由でagent skillを扱うことができます。

リファレンスに色々載っているので少し試してみます。

例えば以下のコマンドでは提供されているskill一覧を確認することができます。今回試したバージョンでは24のskillが確認できました。

❯ gcx agent skills list
24 skill(s) bundled with gcx
...

コマンド経由でskillのinstallも可能です。

❯ gcx agent skills install setup-gcx
Installed 1 skill(s) to /Users/xxx/.agents/skills

┌───────────────────────────────────────┬───────────────────────────────────────┐
│ FIELD                                 │ VALUE                                 │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ ROOT                                  │ /Users/xxx/.agents                    │
│ SKILLS DIR                            │ /Users/xxx/.agents/skills             │
│ SKILLS                                │ 1                                     │
│ FILES                                 │ 2                                     │
│ WRITTEN                               │ 2                                     │
│ OVERWRITTEN                           │ 0                                     │
│ UNCHANGED                             │ 0                                     │
└───────────────────────────────────────┴───────────────────────────────────────┘

Skill names: setup-gcx

また、installせずにgetしてmd形式のskillを取得することもできるみたいです。これはAI時代に優しい仕様です。

❯ gcx agent skills get gcx
---
name: gcx
description: >
  Manages Grafana Cloud resources via the gcx CLI. Trigger when the user wants to
  inspect, create, update, delete, query, or automate any Grafana resource -
  dashboards, datasources, alerts, SLOs, synthetic checks, oncall, incidents,
  fleet, k6, knowledge graph, or adaptive telemetry.
user-invocable: true
disable-model-invocation: false
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion
---

# gcx — Grafana Cloud CLI
...

まとめ

今までGrafana Cloud上のログ調査などはMCPサーバーを利用していたのですが、gcxもAI時代にしっかりフィットする感じに作られているのでなかなかいいなと思いました。

今後も積極的に活用していこうと思います。