▶️

OpenTelemetry が拡げる Gemini CLI の可観測性

2025/10/21に公開

2025 年 10 月 20 日行われた Jagu'e'r クラウドネイティブ分科会 Meetup#20 に登壇させていただきました。
「クラウドネイティブ × Gemini CLI」 をテーマに Long Session × 2 本・LT × 4 本が行われました。私は LT として、Gemini CLI のオブザーバビリティにフォーカスしてお話させていただきました。
ここでは、LT の中で話きれなかったこととして「AI エージェント × オブザーバビリティ」や「Semantic conventions for generative AI systems」の深掘りについてまとめていこうと思います。
また、Cloud Observability と連携する Vibe Coding で作成したアプリケーションについても軽く触れています。（解像度下げすぎてガビガビになりました。。）
※ Gemini CLI の Log Viewer 作ってみた にスクショを掲載しています。

 対象となる読者Gemini CLI のテレメトリーに興味がある方
Gemini CLI の色々な使い方を知りたい方

 AI エージェント × オブザーバビリティ今回 Gemini CLI について話をしましたが、少し引いて「AI エージェント」にオブザーバビリティが必要なのかについて簡単にまとめたいと思います。
ポイントは AI エージェントが持つ 「非決定論的な性質」 とそれに伴う 「内部動作の不透明さ」 かと思います。
AI エージェントによって課題を適切に解決したいものの、「非決定論的な性質」によって振る舞いが期待しているものとは限らず、「内部動作の不透明さ」= 振る舞いの過程がブラックボックスになりがちです。こういった AI エージェント特有の課題は一般的に認識されています。
だからこそ、AI エージェントにもオブザーバビリティは必要不可欠であり、オブザーバビリティに生成 AI ならではの観点が求められているのだと考えます。

 補足ここで言っている「非決定論」と「不透明」がやや抽象的なので具体例を書いておきます。
前者は「同じ指示でも、外部 API から取得する情報（例: 今日の天気）が変わるだけで、エージェントが使用するツールや思考パスが全く変わってしまう」などです。
後者は「どの思考ステップ（CoT）で判断を誤ったのか」「RAG で参照したどの情報源が不適切だったのか」「どの Function Calling が想定外のコストを発生させたのか」など見えなくて困ることなどを指しています。

 参考今回の Meetup でご一緒させていただいた @AotoLog_ さんと @east_k1mitsu さんの過去資料が参考になりました。
https://speakerdeck.com/aoto/the-frontlines-of-ai-agent-observability-by-datadog
https://speakerdeck.com/yunosukey/mlopsnixue-buezientonoke-guan-ce-xing

 Semantic conventions for generative AI systems上記で記述した 「オブザーバビリティに生成 AI ならではの観点」 というのが、OpenTelemetry で定義されている Semantic conventions for generative AI systems によってルール化されていると考えています。
下記の OpenTelemetry の公式ドキュメントにある通り、「入力と出力」「生成 AI の操作」「生成 AI モデルの操作」「生成 AI エージェントの操作」が具体的な項目です。
Semantic conventions for Generative AI operations are defined for the following signals:
Events: Semantic Conventions for Generative AI inputs and outputs - events.
Metrics: Semantic Conventions for Generative AI operations - metrics.
Model spans: Semantic Conventions for Generative AI model operations - spans.
Agent spans: Semantic Conventions for Generative AI agent operations - spans.
OpenTelemetry 公式ドキュメント - Semantic conventions / Generative AI
それぞれがどんな属性を持っているかをいくつか見ていきたいと思います。すべてを知るというよりかは規定されている属性にどういったものがあるかイメージをつけていただけたらなと思います。
!2025 年 10 月 20 日時点では Status は development となっています。

 Event生成 AI の入力と出力にフォーカスしている情報です。 gen_ai.usage.input_tokens や gen_ai.request.max_token などはわかりやすい例でしょうか。

 event.gen_ai.client.inference.operation.details

Attribute
Description
Example


gen_ai.operation.name
The name of the operation being performed.
chat

gen_ai.output.type
Represents the content type requested by the client.
text,json,image

gen_ai.request.model
The name of the GenAI model a request is being made to.
gpt-4

gen_ai.request.max_tokens
The maximum number of tokens the model generates for a request.
100

gen_ai.usage.input_tokens
The number of tokens used in the GenAI input (prompt).
100

gen_ai.usage.output_tokens
The number of tokens used in the GenAI response (completion).
180

OpenTelemetry 公式ドキュメント - Semantic conventions / Generative AI / Events

 Metrics生成 AI の操作にフォーカスしている情報です。Client メトリクスの大きなカテゴリは gen_ai.client.token.usage と gen_ai.client.operation.duration のようです。

 gen_ai.client.token.usage / gen_ai.client.operation.duration

Attribute
Description
Example


gen_ai.operation.name
The name of the operation being performed.
chat

gen_ai.provider.name
The name of the operation being performed.
gcp.vertex_ai

gen_ai.request.model
The name of the GenAI model a request is being made to.
gpt-4

OpenTelemetry 公式ドキュメント - Semantic conventions / Generative AI / Metrics

 Model Spans生成 AI モデルの操作にフォーカスしている情報です。スパンには Inference と  Embeddings と Execute tool span があるようです。ここでは Inference のみ取り上げます。

 Inference

Attribute
Description
Example


gen_ai.operation.name
The name of the operation being performed.
chat

gen_ai.input.messages
The chat history provided to the model as an input.
引用参照

gen_ai.system_instructions
The system message or instructions provided to the GenAI model separately from the chat history.
引用参照

OpenTelemetry 公式ドキュメント - Semantic conventions / Generative AI / Spans

 Agent Spans生成 AI エージェントの操作にフォーカスしている情報です。スパンには Create agent span と Invoke agent span、ツール実行スパンもあるようです。ここでは Invoke agent span を取り上げます。

 Invoke agent span

Attribute
Description
Example


gen_ai.operation.name
The name of the operation being performed.
chat

gen_ai.agent.description
Free-form description of the GenAI agent provided by the application.
Helps with math problems

gen_ai.agent.name
Human-readable name of the GenAI agent provided by the application.
Math Tutor; Fiction Writer

gen_ai.request.stop_sequences
List of sequences that the model will use to stop generating further tokens.
["forest", "lived"]

OpenTelemetry 公式ドキュメント - Semantic conventions / Generative AI / Agent spans
ここまでで Semantic conventions for generative AI systems のイメージがついたでしょうか。

 Gemini CLI × オブザーバビリティ
 必要性はあるか？懇親会で 「実際のところ Gemini CLI にオブザーバビリティってどこまで求められているか？」 という話になりました。1 つは Long Session の @east_k1mitsu さんの登壇の中でもあった、ログでの監査的な視点 = 「利用状況の分析とガバナンス」 だと思いました。これはいわずもがなですね。
Gemini Code Assist と Vertex AI の利用時のみにログが残るようです。
https://speakerdeck.com/yunosukey/gemini-clidemosekiyuadejian-lao-nakai-fa-wositai
他にはあるかというと、「パフォーマンスとコストの最適化」 がありそうです。Gemini CLI の一連の挙動の応答時間やトークン消費量の追跡は気にすべき点でしょうか。例えば、「この使い方だとトークンを過剰に消費している」といった問題を特定できたりするでしょう。
最後に 「デバッグと信頼性の向上」 があるかもしれません。AI が期待通りに動作しない場合に、「どこで失敗したのか」「どの思考プロセスで間違ったのか」を把握できることは問題解決に必要不可欠だとおもいます。エラー箇所の特定が困難なケースが多く、ログやトレースが必須となりますね。
この部分については、AI エージェントを搭載したアプリケーションでは、振る舞いが期待しているものかどうかの評価のためにも必要不可欠であることはわかります。一方で、Gemini CLI のような個人で利用する上だとそこまで必要性がない = Cloud Trace を見に行くことがあるか？というそうでもないような気がします。
Gemini と壁打ちしてみると、チャットツール的な利用では「プロセスがどうだったかは問題なくではなく、最終的な出力結果が全て」であるためトレースまでは見ることはないだろうと同意見でした。これは納得感があります。
一方で、Gemini CLI とスクリプトや他ツールとの組み合わせて使うような 「自動化の一部として Gemini CLI を組み込む」 のであれば、ある程度の再現性（上述した通り、非決定論的な振る舞いから 100% はない前提）は求められるはず。だからこそ、どのようなプロセスで処理をしたかのデバッグ要素で必要となるのではという意見も言われました。
この点についてはそこまで使い込んでいないから実感とはありませんでしたが、想像はできるので「Gemini CLI × オブザーバビリティ」との必要性のもやっとは少し解消されました。

 テレメトリーの送信方法
 Cloud Observability への直送Cloud Observability として Cloud Monitoring と Cloud Logging へのテレメトリ送信は ~/.gemini/settings.json を下記のようにするだけです。非常に簡単です。
~/.gemini/settings.json
{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}
!資料では割愛しましたが、環境変数で GOOGLE_CLOUD_PROJECT の設定や gcloud auth application-default login での認証済みといったことは前提として必要となります。

 Cloud Monitoring上述した Semantic conventions for generative AI systems で規定された gen_ai.client.token.usage と gen_ai.client.operation.duration を確認することができました。
画像スクショ

 Cloud Loggingロギングでは Gemini CLI がどのように動いたかを構造化ログで確認することができます。下記は jsonPayload の一部です。
jsonPayloadjsonPayload: {
  auth_type: "vertex-ai"
  event.name: "gemini_cli.user_prompt"
  event.timestamp: "2025-10-20T09:53:09.970Z"
  host.arch: "arm64"
  message: "User prompt. Length: 681."process.owner: "hayashi"
  process.runtime.description: "Node.js"
  process.runtime.name: "nodejs"
  process.runtime.version: "23.5.0"
  prompt: "現在、Gemini CLIのテレメトリーログを表示するWebアプリケーション「gemini-cli-telemetry-viewer」を開発しています。

  **現在の機能:**
  - Cloud Loggingから Gemini CLI のテレメトリーログを取得
  - セッションIDでログをグループ化表示
  - 展開/折りたたみ可能なセッション一覧
  - 時間範囲フィルタ（直近5分〜24時間）
  - キーワード検索機能
  - ログ詳細表示（JSON形式）
  - ダークモード対応
  - Mantineベースのモダンなデザイン

  **技術スタック:**
  - Next.js 15 (App Router)
  - Mantine UI
  - Google Cloud Logging API
  - TypeScript

  **ログデータの構造例:**
  - event.name: イベント名（例: gemini_cli.user_prompt）
  - event.timestamp: タイムスタンプ
  - session.id: セッションID
  - prompt: ユーザープロンプト
  - message: ログメッセージ
  - model_name: 使用モデル
  - auth_type: 認証タイプ
  - host.name: ホスト名

  このアプリケーションに追加できる、ユーザーにとって価値のある機能追加案を5〜10個提案してください。"
  prompt_id: "42be1b574fafe"
  prompt_length: 681
  service.name: "gemini-cli"
  service.version: "v23.5.0"
  session.id: "d64b5090-c3bb-48df-b56b-ec5cbe4481a1"
}

 OpenTelemetry Collector 経由での送信リポジトリでは OpenTelemetry Collector を経由する方法も記載されています。Collector をローカルで起動しておいて、同様に ~/.gemini/settings.json を変更します。あとは OpenTelemetry Collector 側での設定に伴って送信されます。
~/.gemini/settings.json
{
  "telemetry": {
    "enabled": true,
    "otlpEndpoint": http://localhost:4317,
    "otlpProtocol": "grpc",
    "useCollector": true
  }
}

 トレースはどうなっている？資料の中でも触れていますが、関連する Issue が立っており 2025 年 10 月 21 日時点ではトレースは出力されないようです。
https://github.com/google-gemini/gemini-cli/issues/9178

 参考これらの情報は docs/telemetry.md にまとまっています。
https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/telemetry.md#logs-and-metrics

 Gemini CLI の Log Viewer 作ってみた一連の処理をトレーシングできないということで、関連ログをひとまとまりにして表示させるアプリケーションを作ってみたくなりました。もちろん、Vibe Coding で。

 開発方法Claude Code 主体で Gemini と相談させながら開発しました。仕様書駆動開発に挑戦したかったのですが時間がなくまたの機会に。
Chrome Devtools MCP が非常に便利でした。UI の微妙な変更を Chrome Devtools から情報を得ながら修正できるので今後使っていきたいです。
今回一緒に登壇させていただいた @aipacommander さんの登壇でも Chrome Devtools に触れられていました！
https://speakerdeck.com/commander_aipa/gemini-cli-x-gcloud-cli-x-chrome-devtools-mcp-de-google-cloudnicheng-tuteiruapurikesiyonnobagufixwoiigan-zinisuru

 参考https://github.com/jamubc/gemini-mcp-tool
https://github.com/ChromeDevTools/chrome-devtools-mcp

 開発ポイント
 モダンな UI への改良最初にコーディングしてもらったらめちゃくちゃ質素な UI で実装してくれました。LT で見せるのもありもう少しモダンな UI に改良したかったので、「Gemini と相談しながら最大 3 回壁打ちして実装を検討してください」と「UI コンポーネントとして Mantine を使用してモダンな UI に変更してください」という二つの指示を与えたら何度かラリーをしたのちに動画のような UI を実装してくれました。

 セッション ID でグルーピングCloud Logging で構造化ログを眺めていたら一連のやりとりのセッション ID は共通して含まれていたので Claude Code に「ログに含まれるセッション ID でグルーピングして、一つのセッションレコードとして表示してください」というような指示を与えたら実装してくれました。

 トークン消費量のバッジ表示同様にログの中にトークン消費量の情報が含まれていたので、これを「セッションレコードに合計トークン数として表示」と「各ログレコードに含まれていた場合にはトーク数として表示」という二つの仕様を与えたら実装してくれました。

 さいごにJagu'e'r クラウドネイティブ分科会 Meetup#20 にて登壇させていただいた内容を補足する内容として「AI エージェント × オブザーバビリティ」「Semantic conventions for generative AI systems」「Gemini CLI × オブザーバビリティ」という項目でまとめてみました。
トレースが見れなかった & Vibe Coding ネタになりそうということで「Gemini CLI Logs Viewer」を開発してみました。Google Cloud も絡めて非常に楽しかったです。
https://twitter.com/pHaya72

Attribute	Description	Example
gen_ai.operation.name	The name of the operation being performed.	chat
gen_ai.output.type	Represents the content type requested by the client.	text,json,image
gen_ai.request.model	The name of the GenAI model a request is being made to.	gpt-4
gen_ai.request.max_tokens	The maximum number of tokens the model generates for a request.	100
gen_ai.usage.input_tokens	The number of tokens used in the GenAI input (prompt).	100
gen_ai.usage.output_tokens	The number of tokens used in the GenAI response (completion).	180

対象となる読者

AI エージェント × オブザーバビリティ

補足

参考

Semantic conventions for generative AI systems

Event

event.gen_ai.client.inference.operation.details

Metrics

gen_ai.client.token.usage / gen_ai.client.operation.duration

Model Spans

Inference

Agent Spans

Invoke agent span

Gemini CLI × オブザーバビリティ

必要性はあるか？

テレメトリーの送信方法

Cloud Observability への直送

Cloud Monitoring

Cloud Logging

OpenTelemetry Collector 経由での送信

トレースはどうなっている？

参考

Gemini CLI の Log Viewer 作ってみた

開発方法

参考

開発ポイント

モダンな UI への改良

セッション ID でグルーピング

トークン消費量のバッジ表示

さいごに

Discussion