Google Cloud プラグイン

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

<ph type="x-smartling-placeholder">
</ph>

インストール

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',
  },
});

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

Authentication

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

アプリケーションのデフォルト認証情報

他の環境で実行するには、GCLOUD_PROJECT 環境変数を Google Cloud プロジェクトに設定し、gcloud ツールを使用して認証する必要があります。

gcloud auth application-default login

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

サービス アカウント認証情報

サービス アカウントを使用して Google Cloud 環境の外部で実行している場合は、認証情報を環境変数として設定できます。Google Cloud サービス アカウント キーの設定の手順に沿って操作します。

キーファイルをダウンロードしたら、GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用してファイルの場所を使用して認証情報を指定するか、JSON ファイルの内容を環境変数 GCLOUD_SERVICE_ACCOUNT_CREDS に直接コピーします。

ファイルパス:

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

ダイレクト コピー:

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"
}'

プラグイン構成

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 にテレメトリーとログデータをエクスポートします。

<ph type="x-smartling-placeholder">
</ph>

サンプラー

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

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

autoInstrumentation とautoInstrumentationConfig

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

metricsExportInterval

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

<ph type="x-smartling-placeholder">
</ph>

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

プラグインを構成するときに、forceDevExport: true を使用して、ローカル実行のテレメトリー エクスポートを有効にします。これにより、Google Cloud でモニタリングする最初のイベントを簡単に送信できます。

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] を選択すると、それぞれのトレースに移動できます。

トレース プレビュー ペインが開き、トレースの詳細を一目で確認できます。詳細を表示するには、ペインの右上にある [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_name

アクションレベルの指標

名前 ディメンション
genkit/アクション/リクエスト flow_name、error_code、error_message
genkit/アクション/レイテンシ 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/生成/レイテンシ 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 には無料枠が十分に用意されています。具体的な料金については、次のリンクをご覧ください。