「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 プロジェクトを選択します。
[リソース] プルダウンメニューをクリックし、[Consumed API] > [Cloud Retail] を選択します。

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

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

Vertex AI Search for Retail のログを開く

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

ロギングの構成

Logging に書き込まれるサービスログを構成できます。ロギング構成を使用すると、ログの書き込みを行う重大度レベルを設定し、ロギングをオンまたはオフに切り替え、特定のサービスのデフォルトのロギング設定をオーバーライドできます。

エンドユーザーが送信する API リクエストごとに、1 つのロギングエントリが生成されます。エントリには、API メソッド、呼び出されたタイミング’、レスポンスコード、リクエスト本文とレスポンス本文などの情報が含まれます。プロジェクトのロギング構成では、API によって生成されたどのタイプのログを Logging に書き込むかを指定します。また、特定の API サービスに対してロギング構成をきめ細かく指定することもできます。

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

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

コンソール

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

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

[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 コンソールでカタログとユーザーイベントのデータの取り込みをモニタリングする手順は次のとおりです。

カタログとユーザーイベントのデータ取り込みのエラー指標は、[モニタリング] ページで確認できます。

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

[データ] ページに移動
データのアップロードで問題が発生した場合に通知されるアラートを作成するには、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 でのログの表示について学習する。