Google Cloud プラグイン

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

インストール

npm i --save @genkit-ai/google-cloud

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

Google Cloud アカウントの設定

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

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

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

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

Genkit の構成

Google Cloud トレース、ロギング、モニタリングへのエクスポートを有効にするには、Genkit 構成に googleCloud プラグインを追加します。

import { googleCloud } from '@genkit-ai/google-cloud';

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

本番環境で実行すると、テレメトリーが自動的にエクスポートされます。

プラグインには、Google Cloud プロジェクト ID と Google Cloud プロジェクトの認証情報が必要です。Google Cloud 環境（Cloud Functions、Cloud Run など）からフローを実行している場合は、プロジェクト ID と認証情報が自動的に設定されます。他の環境で実行するには、GCLOUD_PROJECT 環境変数を Google Cloud プロジェクトに設定し、gcloud ツールを使用して認証する必要があります。

gcloud auth application-default login

詳細については、アプリケーションのデフォルト認証情報のドキュメントをご覧ください。

プラグイン構成

googleCloud() プラグインは、オプションの構成オブジェクトを受け取ります。

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

このオプションを使用すると、Google Cloud プロジェクト ID を明示的に指定できます。ほとんどの場合、これは不要です。

telemetryConfig

このオプションでは、OpenTelemetry NodeSDK インスタンスを構成します。

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

googleCloud({
  telemetryConfig: {
    forceDevExport: false, // Set this to true to export telemetry for local runs
    sampler: new AlwaysOnSampler(),
    autoInstrumentation: true,
    autoInstrumentationConfig: {
      '@opentelemetry/instrumentation-fs': { enabled: false },
      '@opentelemetry/instrumentation-dns': { enabled: false },
      '@opentelemetry/instrumentation-net': { enabled: false },
    },
    metricExportIntervalMillis: 5_000,
  },
});

forceDevExport

このオプションは、dev 環境（ローカルなど）で実行する場合、Genkit にテレメトリーとログデータをエクスポートします。

サンプラー

すべてのトレースをエクスポートすることが現実的でない場合、OpenTelemetry ではトレースのサンプリングが許可されます。

事前構成済みのサンプラーは 4 つあります。

autoInstrumentation と autoInstrumentationConfig

自動計測を有効にすると、コードを変更することなく、OpenTelemetry でサードパーティ ライブラリからテレメトリー データをキャプチャできます。

metricsExportInterval

このフィールドでは、指標のエクスポート間隔をミリ秒単位で指定します。

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

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

ログとトレース

サイドメニューで [ロギング] を見つけ、[ログ エクスプローラ] をクリックします。

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

特定のログ行の場合は、拡張メニュー アイコンをクリックして [トレースの詳細で表示] を選択すると、それぞれのトレースに移動できます。

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

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_name、error_code、error_message
genkit/フロー/レイテンシ フロー名

アクション レベルの指標

名前 ディメンション
genkit/アクション/リクエスト flow_name、error_code、error_message
genkit/アクション/レイテンシ フロー名

生成レベルの指標

名前 ディメンション
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/生成/レイテンシ flow_path、model、temperature、topK、topP、error_code、error_message

指標の可視化は、Metrics Explorer で行うことができます。サイドメニューを使用して [ロギング] を選択し、[Metrics Explorer] をクリックします。

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

指標の可視化は、タイプ（カウンタ、ヒストグラムなど）によって異なります。Metrics Explorer には堅牢な集計機能とクエリ機能があり、さまざまな分割項目で指標をグラフ化できます。

テレメトリーの遅延

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

割り当てと上限

留意すべき重要な割り当てがいくつかあります。

費用

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