Supervisa y soluciona problemas

En esta página, se describe cómo obtener información sobre errores que ocurrieron en importaciones de eventos de usuario y de catálogo, y en otras operaciones de la API en Vertex AI Search para la venta minorista.

Para obtener ayuda con la configuración de alertas, consulta Configura alertas de Cloud Monitoring.

Introducción

Proporcionar información de catálogo y eventos de usuario precisos a la API es importante para obtener resultados de la más alta calidad. Supervisar y comprender la fuente de errores te ayuda a encontrar y corregir cualquier error en tu sitio.

Cómo ver los errores de integración agregados

Para ver los errores agregados que generaron tus procesos de carga de datos y las solicitudes de predicción o búsqueda, usa la página Supervisión.

En esta página, se muestran todos los errores de la API de Vertex AI Search para venta minorista. Puedes ver los errores relacionados con el catálogo de productos, los eventos de usuario, las predicciones de recomendaciones, los resultados de la búsqueda y los modelos. El sistema también registra errores de las importaciones, como una línea con formato incorrecto en tu archivo de Cloud Storage. El sistema registra hasta 100 errores por archivo de importación. Puedes definir el período para el que se muestran los errores y filtrar según el tipo de error.

Puedes hacer clic en un error individual para ver los registros de ese error en Cloud Logging.

Puedes abrir registros de error individuales si expandes ese registro. Los registros de errores proporcionan más detalles sobre la solicitud, incluidas las cargas útiles de la solicitud y la respuesta, y los detalles del error. Esta información puede ayudarte a determinar dónde se encuentra la llamada de método errónea en tu sitio.

Para obtener errores de JSON no válidos, puedes obtener más información sobre el problema si expandes el campo status.

Consulta el estado de una operación de integración específica

Puedes ver el estado de una operación de integración específica en la ventana Estado de la actividad:

  1. Ve a la página Datos> en la consola de Search for Retail.

    Ir a la página Datos

  2. Haz clic en Estado de la actividad.

    En la ventana Estado de la actividad (Activity status), se muestra el estado de las operaciones de larga duración en tu catálogo de productos, los eventos de usuario y los controles.

    En esta ventana, puedes inspeccionar los errores de operaciones de integración específicas.

  3. Haz clic en Ver registros en la columna Detalles de cualquier operación con un error para inspeccionar sus archivos de registro en Cloud Logging.

Ver registros en Cloud Logging

Para abrir tus archivos de registro directamente en Cloud Logging, usa el siguiente procedimiento. Debes tener el rol Visor de registros (roles/logging.viewer) para ver los registros.

  1. Ve al Explorador de registros en la consola de Google Cloud. Ir al Explorador de registros

  2. Selecciona tu proyecto de Vertex AI Search para venta minorista en el selector de proyectos.

  3. Haz clic en el menú desplegable Recurso y selecciona API consumida > Cloud Retail.

Para obtener más información sobre el Explorador de registros, consulta Visualiza los registros con el Explorador de registros.

Por ejemplo, este vínculo abre los registros de todos los errores de Vertex AI Search para la venta minorista durante la última hora:

Abre Vertex AI Search para registros de venta minorista

Para configurar qué registros de API se escriben, consulta Configura Logging.

Configura el registro

Puedes configurar qué registros de servicio se escriben en Logging. La configuración de registros proporciona una forma de establecer los niveles de gravedad en los que escribir registros, activar o desactivar el registro y anular la configuración de registro predeterminada para servicios específicos.

Cada solicitud a la API que realiza un usuario final puede generar una entrada de registro. Una entrada contiene información como el método de la API, cuándo se invocó, el código de respuesta y los cuerpos de la solicitud y la respuesta. La configuración de registro de un proyecto especifica qué tipos de registros generados por la API se escriben en Logging, con la opción de especificar de forma detallada las configuraciones de registro para servicios de API específicos.

Para actualizar la configuración de registro, necesitas el rol de editor de Vertex AI Search para venta minorista.

Puedes usar la consola o la API de LoggingConfig para configurar Logging.

Console

Para actualizar la configuración de registro en la consola, sigue estos pasos:

  1. Ve a la página Monitoring en la consola de Search for Retail.

    Ir a la página Monitoring

  2. Haz clic en Configuración de Logging.

  3. Para establecer una configuración de registro global, selecciona un nivel de registro. Si seleccionas LOG_ALL, ingresa también una tasa de muestreo de registros exitosos.

  4. Para establecer una configuración a nivel de servicio, selecciona el servicio que deseas actualizar y selecciona su nivel de registro. Esta configuración anula la configuración de registro global.

curl

Para actualizar la configuración de registro con la API, usa el recurso LoggingConfig. Consulta la referencia de la API de LoggingConfig.

  1. Para ver la configuración de registro actual, usa 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: Es el ID del proyecto

  2. Para actualizar la configuración de registro, usa el método loggingConfig.Patch. Para obtener más información, consulta la referencia de la API de LoggingConfig.

    En este ejemplo, se usa loggingConfig.Patch para establecer la configuración de registro global en LOG_WARNINGS_AND_ABOVE. También establece dos configuraciones a nivel de servicio: CatalogService se establece en LOG_WARNINGS_AND_ABOVE y ControlService se establece en 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"
            }
        }
      ]
    }'

Niveles de registro

Solo los registros de algunos niveles de gravedad se escriben en Logging. La configuración del nivel de registro determina qué registros generados por un método de API se escriben en Logging.

Cuando no se establece una configuración de registro a nivel de servicio para un método de API, se usa la configuración de nivel de registro global.

El parámetro de configuración predeterminado del nivel de registro es LOG_WARNINGS_AND_ABOVE.

El campo logging_level acepta los siguientes valores:

  • LOGGING_DISABLED: No se escribió ningún registro.
  • LOG_ERRORS_AND_ABOVE: Solo errores de registro.
  • LOG_WARNINGS_AND_ABOVE: Solo registra errores y advertencias.
  • LOG_ALL: Registra todo, incluidos los registros correctos, como los registros de INFO.

Tasa de muestreo de registros correctos

Si estableces la configuración del nivel de registro en LOG_ALL, pero no deseas registrar todos los registros exitosos, puedes especificar una tasa de muestreo. Por ejemplo, puedes decidir supervisar de forma periódica los registros en busca de una confirmación de estado correcta o deseas ver un porcentaje de registros exitosos. Especificar una tasa de muestreo puede ayudarte a hacerlo sin escribir un volumen alto de entradas de registro INFO en Logging, lo que puede generar costos de Logging más altos.

Para especificar una tasa de muestreo, establece info_log_sample_rate en un valor flotante válido superior a 0 e inferior o igual a 1. La tasa de muestreo determina la probabilidad de que un registro INFO se escriba en Logging. El valor predeterminado es 1 (se escriben todos los registros de INFO).

Configuraciones de nivel de servicio

Puedes establecer configuraciones de registro para servicios específicos. Esto reemplaza la configuración de registro global de ese servicio. Por ejemplo, puedes tener el nivel de registro global configurado como LOG_WARNINGS_AND_ABOVE, pero establecer el nivel de registro del servicio UserEventService en LOG_ALL para que puedas verificar las integraciones de eventos de usuario correctas.

Usa el objeto ServiceLoggingLevel para establecer niveles de registro detallados.

El campo service_name acepta los siguientes valores:

  • CompletionService
  • ControlService
  • MerchantCenterStreaming
  • ModelService
  • PredictionService
  • ProductService
  • ServingConfigService
  • UserEventService

Tipos de errores

En esta sección, se proporcionan definiciones para los tipos de errores que pueden aparecer en tus registros:

  • MISSING_FIELD: No se configuró el valor de un campo obligatorio, por ejemplo, a un artículo del catálogo le falta el título.
  • INVALID_TIMESTAMP: La marca de tiempo no es válida, por ejemplo, demasiado lejana en el futuro o tiene un formato incorrecto.
  • FIELD_VALUE_TOO_SMALL: El valor del campo es menor que el mínimo requerido, por ejemplo, un precio negativo.
  • INCORRECT_JSON_FORMAT: El JSON de la solicitud tiene un formato incorrecto, como un prefijo { faltante.
  • INVALID_LANGUAGE_CODE: El código de idioma tiene un formato incorrecto.
  • FIELD_VALUE_EXCEEDED: El valor en el campo es mayor que el máximo permitido.
  • INVALID_RESOURCE_ID: El ID de recurso no es válido. por ejemplo, un catalog_id inexistente en el nombre del recurso.
  • FIELD_SIZE_EXCEEDED: La cantidad de entradas en el campo supera el límite máximo.
  • UNEXPECTED_FIELD: Un campo que debería estar vacío tiene un valor, por ejemplo, la transacción de un evento de visualización de página de detalles.
  • INVALID_FORMAT: El campo no tiene el formato correcto, como una string con formato incorrecto.
  • RESOURCE_ALREADY_EXISTS: Intentaste crear un recurso que ya existe, como un elemento de catálogo creado con anterioridad.
  • INVALID_API_KEY: La clave de API no coincide con el proyecto de tu solicitud.
  • INSUFFICIENT_PERMISSIONS: No tienes permiso para ejecutar la solicitud. Por lo general, este error se relaciona con la falta de permisos de IAM obligatorios.
  • UNJOINED_WITH_CATALOG: La solicitud incluye un ID de elemento de catálogo que no existe en el catálogo. Asegúrate de que el catálogo esté actualizado.
  • BATCH_ERROR: La solicitud tiene varios errore, por ejemplo, una importación intercalada con 10 artículos cuya validación falla por motivos distintos.
  • INACTIVE_RECOMMENDATION_MODEL: Consultaste un modelo que no está activo para la entrega.
  • ABUSIVE_ENTITY: El ID de visitante o ID de usuario asociado con la solicitud envió una cantidad anormal de eventos en un período corto.

  • FILTER_TOO_STRICT: El filtro de solicitud de predicción bloqueó todos los resultados de la predicción. Los elementos populares genéricos (no personalizados) se muestran, a menos que la llamada especificó strictFiltering como falso, en cuyo caso no se muestran elementos. A continuación, se indican algunas razones comunes por las que ocurre este problema:

    • Estás especificando una etiqueta de filtro que no existe en tu catálogo. La actualización de la etiqueta de filtro puede tardar hasta un día en aplicarse.
    • Tu filtro es demasiado reducido.

Consulta las métricas de carga de datos

Para supervisar la transferencia de datos de eventos de usuarios y catálogos en la consola de Google Cloud, sigue estos pasos:

  1. Consulta las métricas de errores de la transferencia de datos de eventos de usuarios y del catálogo en la página Monitoring.

    Ir a la página Monitoring

  2. Una vez que el sistema de carga de datos se ejecute correctamente, usa las pestañas Catálogo y Evento en la página Datos para ver información agregada sobre el catálogo, obtener una vista previa de los productos subidos y ver visualizaciones de las métricas de integración de eventos de usuarios.

    Ir a la página Datos

  3. Para crear alertas que te avisen si algo sale mal con tus cargas de datos, sigue los procedimientos que se indican en Configura alertas de Cloud Monitoring.

Resumen de datos de catálogos

Usa la pestaña Catálogo en la página Datos para ver las estadísticas de datos de alto nivel para cada rama del catálogo. En esta página, se muestra cuántos productos importaste, cuántos están en stock y cuándo importaste por última vez los productos para cada rama del catálogo de productos.

También puedes ver una vista previa de los elementos del catálogo que subiste y filtrarlos según los campos del producto.

Puedes importar datos a diferentes ramas para habilitar a etapa y obtener una vista previa de las recomendaciones o los resultados de la búsqueda. Por ejemplo, para prepararte para una temporada de festividades, puedes subir datos de catálogo nuevos a una rama no predeterminada y asegurarte de que Vertex AI Search para resultados de venta minorista se genere correctamente antes de publicarlo en tu sitio web.

Estadísticas de la grabación de eventos del usuario

Para cada tipo de evento de usuario, puedes ver en la pestaña Eventos cuántos registraste, cuántos de ellos no se pudieron asociar con un producto (eventos no unidos). y cómo difieren los números de los períodos anteriores. Puedes seleccionar un período predeterminado o ingresar un intervalo de tiempo personalizado.

En el gráfico de métricas, se muestran los eventos del usuario transferidos a lo largo del tiempo, que puedes filtrar por tipo de evento del usuario.

Métricas de calidad de los datos

En la página Calidad de los datos, puedes ver métricas que muestran los porcentajes de productos y eventos de usuarios que cumplen con los estándares recomendados de calidad de los datos para la búsqueda. Usa esta página para evaluar qué datos necesitas importar o actualizar para mejorar la calidad de los resultados de la búsqueda y desbloquear los niveles de rendimiento de la búsqueda.

Para obtener más información sobre los niveles de rendimiento de la Búsqueda y verificar la calidad de tus datos, consulta Cómo desbloquear los niveles de rendimiento de la Búsqueda.

Para obtener una lista de todas las métricas de calidad de los datos del catálogo, consulta Métricas de calidad de los datos de catálogo.

Para conocer todos los requisitos y las recomendaciones de eventos de usuarios relacionados con las recomendaciones y la búsqueda, consulta Requisitos y prácticas recomendadas para los eventos de usuarios.

Eventos no unidos

Cuando un evento de usuario o una solicitud a la API se refiere a un producto que no se subió a Vertex AI Search para la venta minorista, es un evento no unido. Los eventos de usuario no unidos aún se registran y se manejan las solicitudes no unidas, pero ninguna se puede usar para mejorar aún más el modelo a fin de realizar predicciones futuras. Por este motivo, debes asegurarte de que el porcentaje de eventos no registrados sea muy bajo para los eventos de usuario y las solicitudes de predicción.

Puedes ver el porcentaje de eventos de usuarios no unidos en la pestaña Evento de la página Datos.

Errores de la API

Para ver un gráfico de los errores de la API a lo largo del tiempo, que se muestra por nombre de método, haz clic en Ver métricas de la API en la barra de botones de la página Monitoring.

Supervisa la actividad del método de la API

Para ver las visualizaciones de tráfico, errores y latencia por método de API, ve a la página Monitoring. Puedes seleccionar un período predeterminado o ingresar un intervalo de tiempo personalizado.

Para ver más detalles sobre cada gráfico, sigue estos pasos:

  • Debajo de un gráfico, haz clic en el nombre de un método para aislarlo.
  • Desplaza el cursor sobre un gráfico para ver un texto destacado con cada método y sus valores en ese momento.
  • Haz clic y arrastra sobre cualquier sección del gráfico para acercar ese período.

¿Qué sigue?