「Retail」は「小売業向け Vertex AI Search」に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

モニタリングとトラブルシューティング

このページでは、カタログとユーザーイベントのインポートで発生したエラーや、Vertex AI Search for Retail のその他の API オペレーションで発生したエラーの情報を取得する方法について説明します。

アラートの設定方法については、Cloud Monitoring アラートを設定するをご覧ください。

はじめに

最高品質の結果を得るためには、正確なカタログ情報とユーザーイベントを API に提供することが重要です。エラーの原因をモニタリングして把握することで、サイトのエラーを見つけて修正できます。

集約された統合エラーを確認する

データアップロードプロセスや予測リクエスト、もしくは検索リクエストによって生成され、集計されたエラーを確認するには、[モニタリング] ページを使用します。

このページには、Vertex AI Search for Retail API のすべてのエラーが表示されます。商品カタログ、ユーザーイベント、レコメンデーション予測、検索結果、モデルに関連するエラーを表示できます。また、Cloud Storage ファイルの不正な行など、インポートのエラーもシステムによってログに記録されます。インポートファイルごとに最大 100 件のエラーがログに記録されます。エラーが表示される期間を定義し、エラータイプに基づいてフィルタできます。

個々のエラーをクリックすると、そのエラーのログが Cloud Logging に表示されます。

そのログを展開して、個々のエラーログを開くことができます。エラーログには、リクエストやレスポンスのペイロードやエラーの詳細など、リクエストに関する詳細情報が確認できます。この情報は、問題のあるメソッド呼び出しがサイトのどこにあるのかを判断するのに役立ちます。

無効な JSON エラーの場合は、status フィールドを展開すると問題の詳細情報を取得できます。

特定の統合オペレーションのステータスを確認する

特定の統合オペレーションのステータスは、[アクティビティステータス] ウィンドウで確認できます。

Search for Retail コンソールの [データ] ページに移動します。

[データ] ページに移動
[アクティビティのステータス] をクリックします。

[アクティビティのステータス] ウィンドウには、商品カタログ、ユーザーイベント、コントロールに対する長時間実行オペレーションのステータスが表示されます。

このウィンドウで特定の統合オペレーションのエラーを調べることができます。
エラーがあるオペレーションの [詳細] 列で [ログを表示] をクリックし、Cloud Logging のログファイルを検査できます。

Cloud Logging でログを確認する

Cloud Logging でログファイルを直接開くには、次の操作を行います。ログを表示するには、ログ閲覧者（roles/logging.viewer）のロールが必要です。

Google Cloud コンソールの [ログエクスプローラ] に移動します。[ログエクスプローラ] に移動
プロジェクトセレクタから Vertex AI Search for Retail プロジェクトを選択します。
[リソース] プルダウンメニューをクリックし、[Consumed API] > [Cloud Retail] を選択します。

ログエクスプローラの使用方法については、ログエクスプローラを使用してログを表示するをご覧ください。

たとえば、このリンクでは過去 1 時間に発生したすべての Vertex AI Search for Retail のエラーのログが開かれます。

Vertex AI Search for Retail のログを開く

書き込まれる API ログを構成するには、ロギングの構成をご覧ください。

ロギングの構成

Logging に書き込むサービスログを構成できます。Logging の構成では、ログの書き込みレベル、ロギングのオン / オフ、特定のサービスのデフォルトのロギング設定をオーバーライドする重大度を設定できます。

エンドユーザーが発行する各 API リクエストは、1 つのログエントリを生成できます。エントリには、API メソッド、呼び出された日時、レスポンスコード、リクエスト本文とレスポンス本文などの情報が含まれます。プロジェクトのロギング構成では、API によって生成されるログの種類が Logging に書き込まれます。また、特定の API サービスのロギング構成を細かく指定することもできます。

ロギング構成を更新するには、Vertex AI Search for Retail 編集者のロールが必要です。

Logging を構成するには、コンソールまたは LoggingConfig API を使用します。

コンソール

コンソールでロギング構成を更新する手順は次のとおりです。

Search for Retail コンソールの [モニタリング] ページに移動します。

[Monitoring] ページに移動します。
[ロギング構成] をクリックします。
グローバルロギングの構成を設定するには、ロギングレベルを選択します。[LOG_ALL] を選択した場合は、成功したログのサンプリングレートも入力します。
サービスレベル構成を設定するには、更新するサービスを選択してロギングレベルを選択します。この設定は、グローバルロギング構成をオーバーライドします。

curl

API を使用してロギング構成を更新するには、LoggingConfig リソースを使用します。API リファレンス　LoggingConfig　をご覧ください。

現在のロギング構成を表示するには、loggingConfig.Get を使用します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig"

PROJECT_ID: プロジェクトの ID。

ロギング構成を更新するには、loggingConfig.Patch メソッドを使用します。詳しくは API リファレンス　LoggingConfig　をご覧ください。

この例では、loggingConfig.Patch を使用してグローバルロギング構成を LOG_WARNINGS_AND_ABOVE に設定します。また、サービスレベルの 2 つの構成を設定します。CatalogService は LOG_WARNINGS_AND_ABOVE に、ControlService は LOG_ALL に設定されます。

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig" \
  --data '{
    "name": "projects/PROJECT_ID/loggingConfig",
    "default_log_generation_rule": {"logging_level": "LOG_ERRORS_AND_ABOVE"},
    "service_log_generation_rules": [
      {
        "service_name": "CatalogService",
        "log_generation_rule": {
          "logging_level": "LOG_WARNINGS_AND_ABOVE"
          }
      },
      {
        "service_name": "ControlService",
        "log_generation_rule": {
            "logging_level": "LOG_ALL", "info_log_sample_rate": "0.1"
            }
        }
      ]
    }'

ロギングレベル

一部の重大度レベルのログのみが Logging に書き込まれます。ロギングレベルの設定によって、API メソッドによって生成されたログが Logging に書き込まれます。

サービスレベルロギング構成が API メソッドに設定されていない場合、グローバルロギングレベルの設定が使用されます。

デフォルトのロギングレベル設定は LOG_WARNINGS_AND_ABOVE です。

logging_level フィールドには次の値を指定できます。

LOGGING_DISABLED: ログが書き込まれません。
LOG_ERRORS_AND_ABOVE: エラーのみをログに記録します。
LOG_WARNINGS_AND_ABOVE: エラーと警告のみを記録します。
LOG_ALL: 成功したログ（INFO ログなど）をすべてログに記録します。

成功したログのサンプリングレート

ロギングレベルの設定を LOG_ALL に設定しても、成功したすべてのログを記録しない場合は、サンプリングレートを指定できます。たとえば、ステータスの確認に成功しているかどうかログを定期的にモニタリングしたり、成功したログの割合を確認したりできます。サンプリングレートを指定すると、大量の INFO ログエントリが Logging に書き込まれなくなり、Logging のコストが高くなる可能性があります。

サンプリングレートを指定するには、info_log_sample_rate 0 より大きく 1 以下の有効な浮動小数点値にします。サンプリングレートによって、INFO ログが Logging に書き込まれる可能性が決まります。デフォルト値は 1 です（すべての INFO ログが書き込まれます）。

サービスレベルの構成

特定のサービスに対してロギング構成を設定できます。これにより、そのサービスのグローバルロギング設定が上書きされます。たとえば、グローバルロギングレベルを LOG_WARNINGS_AND_ABOVE に設定しても、UserEventService サービスのロギングレベルを LOG_ALL に設定することで、ユーザーイベントの統合が成功したかどうかを確認できます。

ServiceLoggingLevel オブジェクトを使用して、詳細なロギングレベルを設定します。

service_name フィールドには次の値を指定できます。

CompletionService
ControlService
MerchantCenterStreaming
ModelService
PredictionService
ProductService
ServingConfigService
UserEventService

エラータイプ

このセクションでは、ログに表示されるエラータイプの定義について説明します。

MISSING_FIELD: 必須項目の値が設定されていません。（例: カタログアイテムのタイトルがない）
INVALID_TIMESTAMP: タイムスタンプが無効です（例: 遠すぎる未来の日時、形式が正しくない）。
FIELD_VALUE_TOO_SMALL: フィールドの値が必要な最小値よりも小さい（例: 価格がマイナスになっている）。
INCORRECT_JSON_FORMAT: リクエスト内の JSON の形式が正しくありません（例: { 角かっこがない）。
INVALID_LANGUAGE_CODE: 言語コードの形式が正しくありません。
FIELD_VALUE_EXCEEDED: フィールドの値が上限を超えています。
INVALID_RESOURCE_ID: リソース ID が無効です（例: リソース名に存在しない catalog_id）。
FIELD_SIZE_EXCEEDED: フィールド内のエントリ数が上限を超えています。
UNEXPECTED_FIELD: 空であることが想定されたフィールドに値があります（例: 詳細ページビューイベントのトランザクション）。
INVALID_FORMAT: フィールドの形式が正しくない（例: 文字列の形式が正しくない）。
RESOURCE_ALREADY_EXISTS: すでに存在するリソースを作成しようとしました（例: 作成済みのカタログアイテム）。
INVALID_API_KEY: API キーがリクエスト内のプロジェクトと一致しません。
INSUFFICIENT_PERMISSIONS: リクエストを実行する権限がありません。このエラーは通常、必要な IAM 権限がないことに関連します。
UNJOINED_WITH_CATALOG: カタログに存在しないカタログアイテム ID がリクエストに含まれています。カタログが最新であることをご確認ください。
BATCH_ERROR: リクエストに複数のエラーがあります（例: 10 個のアイテムがあるインラインインポートの検証に複数の理由で失敗した）。
INACTIVE_RECOMMENDATION_MODEL: サービス提供が有効ではないモデルに対してクエリを実行しました。
ABUSIVE_ENTITY: リクエストに関連付けられた訪問者 ID またはユーザー ID が、短期間に異常な数のイベントを送信しています。
FILTER_TOO_STRICT: 予測リクエストフィルタによってすべての予測結果がブロックされました。呼び出しで strictFiltering が false として指定されている場合を除き、汎用の（パーソナライズされていない）人気商品が返されます。false の場合は商品は返されません。この問題が発生する原因としては、一般的に次のようなものがあります。
- カタログに存在しないフィルタタグを指定しています。フィルタタグの更新が反映されるまでに最大で 1 日かかることがあります。
- フィルタが狭すぎます。

データの読み込み指標を表示する

カタログとユーザーイベントデータの取り込みを Google Cloud コンソールでモニタリングする手順は次のとおりです。

カタログとユーザーイベントデータの取り込みのエラー指標を [Monitoring] ページに表示します。

モニタリングページに移動
データアップロードシステムが正常に実行されたら、[データ] ページの [カタログ] タブと [イベント] タブを使用して、カタログについての集計情報を確認し、アップロードしたプロダクトをプレビューし、ユーザーイベント統合指標を可視化します。

[データ] ページに移動
データのアップロードで問題が発生した場合に通知されるアラートを作成するには、Cloud Monitoring アラートを設定するの手順に従ってください。

カタログデータの概要

[データ] ページの [カタログ] タブを使用して、各カタログブランチのデータ統計の概要を表示します。このページには、商品カタログブランチごとに、インポートした商品の数、在庫数、最後にインポートした商品が表示されます。

アップロードしたカタログアイテムのプレビューを確認し、商品フィールドに基づいてフィルタできます。

レコメンデーションまたは小売検索結果をステージングしてプレビューする方法として、データをさまざまなブランチにインポートできます。たとえば、ホリデーシーズンに備えて、新しいカタログデータをデフォルト以外のブランチにアップロードし、Vertex AI Search for Retail の結果が正しく生成されることを確認してからウェブサイトで公開することができます。

ユーザーイベント記録の統計情報

ユーザーイベントの種類ごとに、[イベント] タブで、記録したイベントの数、そのうち商品に関連付けられなかったイベントの数（結合されていないイベント）、前の期間との数の相違を確認できます。プリセット期間を選択することも、カスタム期間を入力することもできます。

指標グラフには、一定期間にわたって取り込まれたユーザーイベントが表示されます。これは、ユーザーイベントの種類によってフィルタリングできます。

データ品質の指標

[データ品質] ページでは、Retail Search のデータ品質の推奨基準を満たしているプロダクトとユーザーイベントの割合を示す指標を確認できます。このページを使用して、検索結果の品質を改善し、検索のパフォーマンス階層のロックを解除するために、インポートまたは更新する必要があるデータを評価します。

検索のパフォーマンス階層とデータ品質の確認の詳細については、検索のパフォーマンス階層のロックを解除するをご覧ください。

すべてのカタログのデータ品質指標のリストについては、カタログのデータ品質指標をご覧ください。

レコメンデーションと Retail Search 用のすべてのユーザーイベント要件と推奨事項については、ユーザーイベントの要件とベストプラクティスをご覧ください。

非結合イベント

ユーザーイベントまたは API リクエストが Vertex AI Search for Retail にアップロードされていないプロダクトを参照する場合、結合されていないイベントになります。結合されていないユーザーイベントは引き続きログに記録され、結合されていないリクエストも処理されますが、今後の予測に対して、にさらに強化するためには使用できません。このため、ログに記録されないイベントの割合が、ユーザーイベントと予測リクエストの両方で非常に低い値であることを確認する必要があります。

結合されていないユーザーイベントの割合は、[データ] ページの [イベント] タブで確認できます。

API エラー

メソッド名別に時系列で API エラーのグラフを表示するには、[モニタリング] ページのボタンバーで API 指標の表示をクリックします。

API メソッドのアクティビティをモニタリングする

API メソッド別のトラフィック、エラー、レイテンシの可視化は、[モニタリング] ページで確認できます。プリセット期間を選択することも、カスタム期間を入力することもできます。

各グラフの詳細を確認するには:

グラフの下にあるメソッド名をクリックして、グラフ内で分離します。
グラフにカーソルを合わせると、各メソッドと、その時点での値のコールアウトが表示されます。
グラフの一部をクリックしてドラッグし、その期間を拡大できます。

次のステップ

データフィードのエラーアラートを設定する方法について学習する。
Error Reporting について学習する。
Logging でのログの表示について学習する。