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>
サンプラー
すべてのトレースをエクスポートすることが現実的でない場合、OpenTelemetry ではトレースのサンプリングが許可されます。
事前構成済みのサンプラーは 4 つあります。
- AlwaysOnSampler - すべてのトレースをサンプリングします。
- AlwaysOffSampler - トレースなしのサンプル
- ParentBased - 親スパンに基づくサンプル
- TraceIdRatioBased - 構成可能なトレースの割合をサンプリングする
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 Trace の割り当て
<ph type="x-smartling-placeholder">
- </ph>
- 属性キーあたり 128 バイト
- 属性値あたり 256 バイト
- Cloud Logging の割り当て
<ph type="x-smartling-placeholder">
- </ph>
- ログエントリあたり 256 KB
- Cloud Monitoring の割り当て
費用
Cloud Logging、Cloud Trace、Cloud Monitoring には無料枠が十分に用意されています。具体的な料金については、次のリンクをご覧ください。