Google Cloud プラグイン

Google Cloud プラグインは、Firebase Genkit のテレメトリー データとロギング データを Cloud Observability スイートにエクスポートします。これにより、Firebase AI Monitoring ダッシュボードが機能します。

インストール

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

このプラグインを含む Genkit コードをローカルで実行する場合は、Google Cloud CLI ツールもインストールする必要があります。

Google Cloud アカウントの設定

このプラグインを使用するには、Google Cloud アカウントまたはプロジェクトが必要です。すべての Firebase プロジェクトにはデフォルトで 1 つ含まれています（GCP Console）。または、https://cloud.google.com で登録することもできます。

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

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

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

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

Genkit の構成

Cloud Tracing、Logging、Monitoring（指標）を有効にするには、enableGoogleCloudTelemetry() を呼び出します。

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

enableGoogleCloudTelemetry();

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

認証と認可

このプラグインには、Google Cloud プロジェクト ID とアプリケーション認証情報が必要です。

Google Cloud

Google Cloud 環境（Cloud Functions、Cloud Run など）にコードをデプロイする場合、プロジェクト ID と認証情報は アプリケーションのデフォルト認証情報によって自動的に検出されます。

コードを実行しているサービス アカウント（「接続されたサービス アカウント」）に、IAM コンソールから次のロールを適用する必要があります。

• roles/monitoring.metricWriter
• roles/cloudtrace.agent
• roles/logging.logWriter

ローカルでの開発

ローカル開発では、ユーザー認証情報をプラグインで使用できるようにするために、追加の手順が必要です。

1. GCLOUD_PROJECT 環境変数を Google Cloud プロジェクトに設定します。

2. gcloud CLI を使用して認証します。

   gcloud auth application-default login

Google Cloud の外部にある本番環境

可能であれば、アプリケーションのデフォルト認証情報のプロセスを利用して、プラグインで認証情報を使用できるようにすることをおすすめします。

通常、これはサービス アカウント キー/ペアを生成し、それらの認証情報を本番環境にデプロイすることを含みます。

1. 手順に沿ってサービス アカウント キーを設定します。

2. サービス アカウントに次のロールがあることを確認します。

   • roles/monitoring.metricWriter
   • roles/cloudtrace.agent
   • roles/logging.logWriter

3. 認証情報ファイルを本番環境にデプロイします（ソースコードにチェックインしないでください）。

4. GOOGLE_APPLICATION_CREDENTIALS 環境変数を認証情報ファイルのパスに設定します。

   GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
   

サーバーレス環境によっては、認証情報ファイルをデプロイできない場合があります。この場合、上記の手順 3 と 4 の代わりに、認証情報ファイルの内容を使用して GCLOUD_SERVICE_ACCOUNT_CREDS 環境変数を設定できます。

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

プラグイン構成

enableGoogleCloudTelemetry() 関数は、OpenTelemetry NodeSDK インスタンスを構成するオプションの構成オブジェクトを受け取ります。

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

enableGoogleCloudTelemetry({
  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,
});

構成オブジェクトを使用すると、以下に示すテレメトリー エクスポートのさまざまな側面をきめ細かく制御できます。

認証情報

google-auth ライブラリの JWTInput を使用して認証情報を直接指定できます。

サンプラー

すべてのトレースをエクスポートできない場合は、OpenTelemetry でトレースサンプリングを使用できます。

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

• AlwaysOnSampler - すべてのトレースをサンプリングします。
• AlwaysOffSampler - トレースをサンプリングしない
• ParentBased - 親スパンに応じたサンプル
• TraceIdRatioBased - 構成可能な割合のトレースをサンプリングします。

autoInstrumentation と autoInstrumentationConfig

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

metricExportIntervalMillis

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

注: Google Cloud Monitoring の最小エクスポート間隔は 5,000 ミリ秒です。

metricExportTimeoutMillis

このフィールドには、指標エクスポートのタイムアウトをミリ秒単位で指定します。

disableMetrics

トレースやログのエクスポートを続行しながら、指標のエクスポートを無効にするオーバーライドを指定します。

disableTraces

指標とログのエクスポートを続行しながら、トレースのエクスポートを無効にするオーバーライドを指定します。

disableLoggingIO

入力ログと出力ログの収集を無効にするオーバーライドを指定します。

forceDevExport

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

注: ローカルで実行する場合、プロセスが終了する前に内部テレメトリー バッファが完全にフラッシュされず、テレメトリーのエクスポートが不完全になることがあります。

インテグレーションをテストする

プラグインを構成するときに、forceDevExport: true を使用してローカル実行のテラメトリー エクスポートを有効にします。Google Cloud Logs、Metrics、Trace Explorer に移動してテレメトリーを表示します。

Google Cloud Observability スイート

コード（フローなど）がデプロイされたら、Cloud Monitoring ダッシュボードに移動してプロジェクトを選択します。ここから、本番環境のモニタリング用にログ エクスプローラ、指標エクスプローラ、トレース エクスプローラを簡単に移動できます。

ログとトレース

左側のメニューで、[探索] の見出しの下にある [ログ エクスプローラ] をクリックします。

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

注: プロンプトと LLM レスポンスは、Cloud Trace のトレースの属性から削除されます。特定のログ行については、拡張メニュー アイコンをクリックして [View in Trace] を選択すると、それぞれのトレースに移動できます。

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

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

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

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

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

指標

Genkit によってエクスポートされたすべての指標を表示するには、左側のメニューの [構成] の見出しにある [指標管理] をクリックします。

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

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

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

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

特徴指標

特徴は、Genkit コードの最上位のエントリ ポイントです。ほとんどの場合、これはフローになります。それ以外の場合は、トレース内の最上位のスパンになります。

名前	型	説明
genkit/feature/requests	カウンタ	リクエスト数
genkit/feature/latency	ヒストグラム	実行レイテンシ（ミリ秒）

各特徴指標には、次のディメンションが含まれています。

名前	説明
name	機能の名前。ほとんどの場合、これはトップレベルの Genkit フローです。
ステータス	機能リクエストが成功したかどうかに応じて「success」または「failure」
エラー	status=failure の場合にのみ設定されます。障害の原因となったエラーの種類が含まれます
ソース	Genkit のソース言語。例: 'ts'
sourceVersion	Genkit フレームワークのバージョン

アクションの指標

アクションは、Genkit 内の実行の一般的なステップを表します。これらの各ステップでは、次の指標が追跡されます。

名前	型	説明
genkit/action/requests	カウンタ	このアクションが実行された回数
genkit/action/latency	ヒストグラム	実行レイテンシ（ミリ秒）

各アクション指標には、次のディメンションが含まれます。

名前	説明
name	アクションの名前
featureName	実行中の親機能の名前
パス	特徴ルートからこのアクションへの実行パス。例: '/myFeature/parentAction/thisAction'
ステータス	アクションが成功したかどうかに応じて「success」または「failure」
エラー	status=failure の場合にのみ設定されます。障害の原因となったエラーの種類が含まれます
ソース	Genkit のソース言語。例: 'ts'
sourceVersion	Genkit フレームワークのバージョン

指標を生成

これらは、モデルとやり取りするアクションに関連する特別なアクション指標です。リクエストとレイテンシに加えて、入力と出力も追跡され、モデル固有のディメンションにより、デバッグと構成のチューニングが容易になります。

名前	型	説明
genkit/ai/generate/requests	カウンタ	このモデルが呼び出された回数
genkit/ai/generate/latency	ヒストグラム	実行レイテンシ（ミリ秒）
genkit/ai/generate/input/tokens	カウンタ	入力トークン
genkit/ai/generate/output/tokens	カウンタ	出力トークン
genkit/ai/generate/input/characters	カウンタ	文字を入力する
genkit/ai/generate/output/characters	カウンタ	出力文字
genkit/ai/generate/input/images	カウンタ	入力画像
genkit/ai/generate/output/images	カウンタ	出力画像
genkit/ai/generate/input/audio	カウンタ	音声ファイルを入力する
genkit/ai/generate/output/audio	カウンタ	出力音声ファイル

各生成指標には、次のディメンションが含まれます。

名前	説明
modelName	モデルの名前
featureName	実行中の親機能の名前
パス	特徴ルートからこのアクションへの実行パス。例: '/myFeature/parentAction/thisAction'
latencyMs	モデルがレスポンスに要した時間
ステータス	機能リクエストが成功したかどうかに応じて「success」または「failure」
エラー	status=failure の場合にのみ設定されます。障害の原因となったエラーの種類が含まれます
ソース	Genkit のソース言語。例: 'ts'
sourceVersion	Genkit フレームワークのバージョン

指標の可視化は、Metrics Explorer で行えます。左側のメニューで、[Explore] の見出しの下にある [Metrics Explorer] をクリックします。

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

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

テレメトリーの遅延

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

割り当てと上限

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

• Cloud Trace の割り当て
• Cloud Logging の割り当て
• Cloud Monitoring の割り当て

費用

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

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