Monitor and troubleshoot

Stay organized with collections Save and categorize content based on your preferences.

This page describes how to get information about errors that have occurred in catalog and user event imports, and other Retail API operations.

For help with setting up alerts, see Set up alerts.

Introduction

Providing accurate catalog information and user events to the Retail API is important to getting the highest quality results. Monitoring and understanding the source of errors helps you find and fix any errors in your site.

See aggregated integration errors

To see the aggregated errors generated by your data upload processes and prediction or search requests, use the Monitoring page.

This page displays all errors for the Retail API. You can view errors related to the product catalog, user events, Recommendations AI predictions, Retail Search results, and models. The system also logs errors from imports, such as a malformed line in your Cloud Storage file. The system logs up to 100 errors per import file. You can define the time period for which errors are displayed and filter based on the error type.

You can click an individual error to see the logs for that error in Cloud Logging.

You can open individual error logs by expanding that log. Error logs provide more detail about the request, including the request and response payloads and error details. This information can help you determine where the erroneous method call is located in your site.

For invalid JSON errors, you can get more information about the issue by expanding the status field.

See status for a specific integration operation

You can see the status of a specific integration operation in the Activity status window:

  1. Go to the Retail Data page in the Google Cloud console.

    Go to the Data page

  2. Click Activity status.

    The Activity status window shows the status of long-running operations on your product catalog, user events, and controls.

    You can inspect errors for specific integration operations in this window.

  3. Click View logs in the Detail column of any operation with an error to inspect its log files in Cloud Logging.

Error types

  • MISSING_FIELD: A required field value is not set; for example, a catalog item is missing its title.
  • INVALID_TIMESTAMP: The timestamp is invalid, such as being too far in the future, or formatted incorrectly.
  • FIELD_VALUE_TOO_SMALL: The value in the field is lower than the required minimum; for example, a negative price.
  • INCORRECT_JSON_FORMAT: The JSON in the request is incorrectly formatted, such as a missing { bracket.
  • INVALID_LANGUAGE_CODE: The language code is incorrectly formatted.
  • FIELD_VALUE_EXCEEDED: The value in the field is higher than the allowed maximum.
  • INVALID_RESOURCE_ID: The resource ID is invalid; for example, a non-existent catalog_id in the resource name.
  • FIELD_SIZE_EXCEEDED: The number of entries in the field exceeds the maximum limit.
  • UNEXPECTED_FIELD: A field that was expected to be empty has a value; for example, a transaction for a detail page view event.
  • INVALID_FORMAT: The field is not formatted correctly, such as a malformed string
  • RESOURCE_ALREADY_EXISTS: You tried to create a resource that already exists, such as a previously created catalog item.
  • INVALID_API_KEY: The API key does not match the project in your request.
  • INSUFFICIENT_PERMISSIONS: You do not have permission to execute the request; this error is usually related to the lack of a required IAM permission.
  • UNJOINED_WITH_CATALOG: The request includes a catalog item ID that does not exist in the catalog. Make sure your catalog is up to date.
  • BATCH_ERROR: The request has multiple errors; for example, an inline import with 10 items that fail validation for different reasons.
  • INACTIVE_RECOMMENDATION_MODEL: You queried a model that is not active for serving.
  • ABUSIVE_ENTITY: The visitor ID or user ID associated with the request has sent an abnormal number of events in a short period of time.

  • FILTER_TOO_STRICT: The prediction request filter blocked all prediction results. Generic (not personalized) popular items are returned, unless the call specified strictFiltering as false, in which case no items are returned. Some common reasons why this issue occurs:

    • You are specifying a filter tag that doesn't exist in your catalog. It can take up to a day for a filter tag update to take effect.
    • Your filter is too narrow.

View logs directly

You can also open your log files directly in Logging. For example, this link opens logs for all Retail errors in the past hour: Open Retail logs

View data load metrics

After your data upload system is running successfully, you can also use the Catalog and Event tabs on the Retail Data page to view error metrics for your data ingestion to ensure that everything is running smoothly.

You can also add alerts to let you know if something goes wrong with your data upload system.

Catalog data summary

Use the Catalog tab on the Data page to view high-level data statistics for each catalog branch. This page displays how many products you have imported, how many are in stock, and when you last imported products for each product catalog branch.

You can also see a preview of the catalog items you have uploaded, and filter based on product fields.

You can import data to different branches as a way to stage and preview Recommendations AI or Retail Search results. For example, to prepare for a holiday season, you might upload new catalog data to a non- default branch and make sure Retail results are generated correctly before making it live on your website.

User event recording statistics

For each type of user event, you can see in the Event tab how many you have recorded, how many of those were not able to be associated with a product (unjoined events), and how the numbers differed from previous periods. You can select a preset time period or enter custom time range.

The metric graph displays user events ingested over time, which you can filter by user event type.

Data quality metrics

On the Data page, click View data quality to open the Data quality panel.

Data quality metrics show the percentages of products and user events that fulfill recommended standards of data quality.

While improving data quality according to these metrics is not required for using the Retail API, doing so is highly encouraged to get better quality recommendation and search results.

Catalog data quality

The Catalog tab on the Data page shows the percentage of products in your catalog that meet catalog quality metrics for Retail Search.

For a list of all catalog data quality metrics, see Catalog data quality metrics.

Event data quality

The Event tab on the Data page shows how many of your user events meet data quality best practices for both Recommendations AI and Retail Search.

The Event data quality tab has two sections:

  • General Retail API metrics: The first section in this tab shows metrics that are applicable to both Recommendations AI and Retail Search. Following the suggestions of these metrics can improve recommendations and search results.

    You can filter the metrics in this section by time range of the user events assessed.

  • Search metrics: The metrics in this section are applicable to Retail Search only. Following the suggestions of these metrics can improve search results.

    These metrics are not filterable by time range.

    The metric Search events is updated in near-real time. The Search events with filters metric is updated for the first time between 4 and 24 hours after you first upload search events. It is then updated about every 4 hours.

    Other metrics in this section are not shown until after the Search events metric has reached 100%. After Search events is fulfilled, you can see these metrics about 24 hours later. They are then updated once a day.

    Unique products visited and Avg. search clicks per product are related metrics. If these metrics have low percentages, improving either metric by importing more search event data will also improve the other metric.

For all user event requirements and recommendations for Recommendations AI and Retail Search, see User event requirements and best practices.

Unjoined events

When a user event or API request refers to a product that has not been uploaded to Retail, it is an unjoined event. Unjoined user events are still logged, and unjoined requests are handled, but neither can be used to further enhance the model for future predictions. For this reason, you should make sure that your unlogged event percentage is very low for both user events and prediction requests.

You can see your unjoined user event percentage in the Event tab on the Data page.

API errors

You can see a graph of API errors over time, displayed by method name, by clicking View API metrics on the button bar of the Monitoring page.

Monitor API method activity

For visualizations of traffic, errors, and latency by API method, go to the Monitoring page. You can select a preset time period or enter custom time range.

To see more details about each graph:

  • Underneath a graph, click a method name to isolate it in the graph.
  • Hover your cursor over a graph to see a callout with each method and its values at that point in time.
  • Click and drag over any section of the graph to zoom in on that period of time.

What's next