Google Cloud のテレメトリーとロギングのプラグイン

Google Cloud プラグインは、Firebase Genkit のテレメトリー データとロギング データを Google Cloud のオペレーション スイートにエクスポートします。

前提条件

このプラグインを使用するフローをローカルで実行する場合は、Google Cloud CLI ツールをインストールする必要があります。

Google Cloud アカウントの設定

このプラグインを使用するには、Google Cloud アカウント（まだお持ちでない場合は登録してください）と Google Cloud プロジェクトが必要です。

プラグインを追加する前に、プロジェクトで次の API が有効になっていることを確認します。

これらの API は、プロジェクトの API ダッシュボードに表示されます。

API の有効化と無効化について詳しくは、こちらをクリックしてください。

構成

Google Cloud Tracing、Google Cloud Logging、Google Cloud Monitoring へのエクスポートを有効にするには、googlecloud パッケージをインポートして Init() を実行します。Init() を呼び出した後、テレメトリーは自動的にエクスポートされます。

import "github.com/firebase/genkit/go/plugins/googlecloud"

if err := googlecloud.Init(
	ctx,
	googlecloud.Config{ProjectID: "your-google-cloud-project"},
); err != nil {
	return err
}

テレメトリー データをエクスポートする Google Cloud プロジェクトを指定する必要があります。オプション パラメータもあります。

  • ForceExport: 開発環境で実行している場合でもテレメトリー データをエクスポートします（genkit start または genkit flow:run を使用している場合など）。これにより、簡単に統合をテストし、Google Cloud でモニタリング用の最初のイベントを送信できます。

    このオプションを使用する場合は、Google Cloud の認証情報をローカルで使用できるようにする必要があります。

    gcloud auth application-default login

  • MetricInterval: テレメトリー情報をエクスポートする間隔（ナノ秒単位）。デフォルトは 60 秒（60e9 ナノ秒）です。

  • LogLevel: エクスポートするログエントリの最小重要度レベル。デフォルトは slog.LevelInfo です。

このプラグインには、Google Cloud プロジェクトの認証情報が必要です。Google Cloud 環境（Cloud Run など）からフローを実行している場合、認証情報は自動的に設定されます。他の環境で実行するには、アプリケーションのデフォルト認証情報を設定する必要があります。

Google Cloud のオペレーション スイートによる本番環境のモニタリング

フローをデプロイしたら、Google Cloud のオペレーション スイートに移動してプロジェクトを選択します。

ログとトレース

サイドメニューで [Logging] を見つけて、[Logs Explorer] をクリックします。

デプロイされたフロー（console.log() など）に関連付けられているすべてのログが表示されます。接頭辞 [genkit] が付いたログは、デバッグに役立つ情報が含まれる Genkit 内部ログです。たとえば、Config[...] 形式の Genkit ログには、特定の LLM 推論の temperature や topK 値などのメタデータが含まれています。Output[...] 形式のログには LLM レスポンスが含まれており、Input[...] ログにはプロンプトが含まれています。Cloud Logging には、機密ログをきめ細かく制御できる堅牢な ACL があります。

特定のログ行については、拡張メニューの アイコンをクリックして [View in trace details] を選択すると、それぞれのトレースまで移動できます。

トレースのプレビュー ペインが開き、トレースの詳細が一目で確認できます。詳細を表示するには、ペインの右上にある [View in Trace] リンクをクリックします。

Cloud Trace で最も重要なナビゲーション要素は、トレース散布図です。これには、指定された期間に収集されたすべてのトレースが含まれます。

各データポイントをクリックすると、散布図の下にその詳細が表示されます。

詳細ビューには、すべてのステップを含むフロー形状と、重要なタイミング情報が表示されます。Cloud Trace では、このビュー内で特定のトレースに対応するすべてのログをインターリーブできます。[Logs & events] プルダウンで [Show expanded] を選択します。

生成されたビューでは、プロンプトや LLM レスポンスなど、トレースのコンテキストでログを詳細に確認できます。

指標

Genkit がエクスポートするすべての指標を表示するには、サイドメニューから [Logging] を選択し、[Metrics management] をクリックします。

指標管理コンソールには、収集されたすべての指標（Cloud Run とその周辺環境に関連する指標を含む）の表形式のビューが表示されます。[Workload] オプションをクリックすると、Genkit で収集された指標を含むリストが表示されます。接頭辞 genkit が付いた指標は、内部 Genkit 指標です。

Genkit は、フローレベル、アクションレベル、生成レベルの指標など、いくつかのカテゴリの指標を収集します。各指標には、堅牢なフィルタリングとグループ化を容易にする、いくつかの有用なディメンションがあります。

一般的なディメンションには、次のようなものがあります。

  • flow_name - フローの最上位の名前。
  • flow_path - スパンとルートスパンまでの親スパンチェーン。
  • error_code - エラーの場合、対応するエラーコード。
  • error_message - エラーの場合、対応するエラー メッセージ。
  • model: モデルの名前
  • temperature - 推論の温度の値。
  • topK - 推論の topK の値。
  • topP - 推論の topP の値。

フローレベルの指標

名前 ディメンション
genkit/flow/requests flow_name、error_code、error_message
genkit/flow/latency flow_name

アクションレベルの指標

名前 ディメンション
genkit/action/requests flow_name、error_code、error_message
genkit/action/latency flow_name

生成レベルの指標

名前 ディメンション
genkit/ai/generate flow_path、model、temperature、topK、topP、error_code、error_message
genkit/ai/generate/input_tokens flow_path、model、temperature、topK、topP
genkit/ai/generate/output_tokens flow_path、model、temperature、topK、topP
genkit/ai/generate/input_characters flow_path、model、temperature、topK、topP
genkit/ai/generate/output_characters flow_path、model、temperature、topK、topP
genkit/ai/generate/input_images flow_path、model、temperature、topK、topP
genkit/ai/generate/output_images flow_path、model、temperature、topK、topP
genkit/ai/generate/latency flow_path、model、temperature、topK、topP、error_code、error_message

指標の可視化は、Metrics Explorer で行えます。サイドメニューで [Logging] を選択し、[Metrics Explorer] をクリックします。

[指標を選択] プルダウンをクリックし、[汎用ノード]、[Genkit]、指標を選択して、指標を選択します。

指標の可視化は、そのタイプ（カウンタ、ヒストグラムなど）によって異なります。Metrics Explorer には、さまざまなディメンションで指標をグラフ化するための堅牢な集計とクエリ機能が用意されています。

テレメトリーの遅延

フローの特定の実行に関するテレメトリが Cloud のオペレーション スイートに表示されるまでに少し時間がかかることがあります。ほとんどの場合、この遅延は 1 分未満です。

割り当てと上限

以下に示す割り当ての上限に注意してください。

費用

Cloud Logging、Cloud Trace、Cloud Monitoring には無料枠が十分に用意されています。具体的な料金については、次のリンクをご覧ください。