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

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

注: ロギングは、OpenTelemetry ロギング API をサポートする slog パッケージによって容易になります。ログのエクスポートは、専用の Google Cloud エクスポータによって行われます。

前提条件

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

Google Cloud アカウントの設定

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

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

• Cloud Logging API
• Cloud Trace API
• Cloud Monitoring API

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

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

構成

Google Cloud Tracing、Logging、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 でモニタリング用の最初のイベントを送信できます。

  このオプションを使用する場合は、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 推論の温度や topK 値などのメタデータが含まれています。Output[...] 形式のログには LLM レスポンスが含まれ、Input[...] ログにはプロンプトが含まれます。Cloud Logging には、機密ログをきめ細かく制御できる堅牢な ACL があります。

注: プロンプトと LLM レスポンスは、Cloud Trace のトレース属性から削除されます。

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

トレースのプレビュー ペインが表示され、トレースの詳細を簡単に確認できます。詳細を表示するには、ペインの右上にある [トレース内で表示] リンクをクリックします。

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

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

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

生成されたビューでは、トレースのコンテキストでログを詳細に確認できます（プロンプトや 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 Trace の割り当て
  • 属性キーあたり 128 バイト
  • 属性値あたり 256 バイト
• Cloud Logging の割り当て
  • ログエントリあたり 256 KB
• Cloud Monitoring の割り当て

費用

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

• Cloud Logging の料金
• Cloud Trace の料金
• Cloud Monitoring の料金