Monitoramento e solução de problemas

Esta página descreve como receber informações sobre erros que ocorreram em importações de eventos do catálogo e do usuário e em outras operações da API no Vertex AI Search for Retail.

Se precisar de ajuda para configurar alertas, consulte Configurar alertas do Cloud Monitoring.

Introdução

É importante fornecer informações precisas do catálogo e eventos do usuário para a API. Assim, é importante conseguir os melhores resultados. Monitorar e entender a origem dos erros ajuda você a encontrar e corrigir erros no seu site.

Conferir erros de integração agregados

Para conferir os erros agregados gerados pelos processos de upload de dados e solicitações de previsão ou pesquisa, use a página Monitoramento.

Nesta página, você vai encontrar todos os erros da API Vertex AI Search for Retail. Você pode ver erros relacionados ao catálogo de produtos, eventos do usuário previsões de recomendações, resultados de pesquisa e de modelos de machine learning. O sistema também registra erros de importações, como uma linha malformada no arquivo do Cloud Storage. O sistema registra até 100 erros por arquivo de importação. Você pode definir o período em que os erros são exibidos e filtrar com base no tipo de erro.

É possível clicar em um erro individual para ver os registros desse erro no Cloud Logging.

É possível abrir registros de erro individuais expandindo esse registro. Os registros de erros fornecem mais detalhes sobre a solicitação, incluindo payloads de solicitações e respostas e detalhes dos erros. Essas informações podem ajudar você a determinar onde a chamada de método incorreto está localizada no seu site.

Para erros de JSON inválidos, é possível ver mais informações sobre o problema expandindo o campo status.

Ver o status de uma operação de integração específica

É possível conferir o status de uma operação de integração específica na janela Status da atividade:

  1. Acesse Dados> no console da Pesquisa para varejo.

    Acessar a página "Dados"

  2. Clique em Status da atividade.

    A janela Status da atividade mostra o status das operações de longa duração no catálogo de produtos, eventos do usuário e controles.

    Você pode inspecionar erros para operações de integração específicas nesta janela.

  3. Clique em Ver registros na coluna "Detalhes" de qualquer operação com um erro para inspecionar os arquivos de registros no Cloud Logging.

Ver registros no Cloud Logging

Para abrir os arquivos de registro diretamente no Cloud Logging, use o comando a seguir: ou o procedimento anterior. É necessário ter o papel Visualizador de registros (roles/logging.viewer) para acessar os registros.

  1. Acesse o Explorador de registros no console do Google Cloud. Acessar o Explorador de registros

  2. Selecione seu projeto da Vertex AI para Pesquisa para varejo no seletor de projetos.

  3. Clique no menu suspenso Recurso e selecione API utilizada > Cloud Retail.

Para mais informações sobre a Análise de registros, consulte Veja os registros usando a Análise de registros.

Por exemplo, este link abre registros de todos os erros da Vertex AI para Pesquisa no varejo na última hora:

Abrir os registros da Vertex AI para Pesquisa para Retail

Para configurar quais registros de API são gravados, consulte Configurar a geração de registros.

Configurar a geração de registros

É possível configurar quais registros de serviço são gravados no Logging. A configuração do Logging oferece uma maneira de definir os níveis de gravidade para gravar, ativar ou desativar a geração de registros e substituir as configurações padrão serviços específicos.

Cada solicitação de API feita por um usuário final pode gerar uma entrada de registro. Uma entrada contém informações como o método da API, quando ele foi invocado, o código de resposta e os corpos de solicitação e resposta. Configuração da geração de registros de um projeto especifica em que tipos de registros gerados pela API são gravados o Cloud Logging, com a opção de especificar a geração de registros configurações para serviços específicos da API.

Para atualizar as configurações de registro, você precisa da função de editor da Vertex AI para Pesquisa para varejo.

É possível usar o console ou a API LoggingConfig para configurar o Logging.

Console

Para atualizar as configurações de geração de registros no console, siga estas etapas:

  1. Acesse a página Monitoramento no console da Pesquisa para varejo.

    Acessar a página "Monitoramento"

  2. Clique em Configuração do Logging.

  3. Para definir uma configuração de geração de registros global, selecione um nível de geração de registros. Se você selecionar LOG_ALL, também insira uma taxa de amostragem para registros com êxito.

  4. Para definir uma configuração no nível do serviço, selecione um serviço para atualizar e escolha o nível de registro dele. Essa configuração substitui a configuração global de registro.

curl

Para atualizar as configurações de geração de registros usando a API, use o recurso LoggingConfig. Consulte a referência da API LoggingConfig.

  1. Para conferir a configuração atual de geração de registros, use 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: o ID do seu projeto.

  2. Para atualizar a configuração de geração de registros, use o método loggingConfig.Patch. Para saber mais, consulte a referência da API LoggingConfig.

    Este exemplo usa loggingConfig.Patch para definir a geração de registros global para LOG_WARNINGS_AND_ABOVE. Ele também define dois níveis de serviço da configuração: CatalogService é definida como LOG_WARNINGS_AND_ABOVE e ControlService está definido como 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"
            }
        }
      ]
    }'

Níveis de registro

Apenas registros de alguns níveis de gravidade são gravados no Logging. As configurações de nível de registro determinam quais registros gerados por um método de API são gravados no registro.

Quando nenhuma configuração de geração de registros no nível de serviço é definida para um método de API, o é usada a configuração de nível de registro.

A configuração padrão do nível de registro é LOG_WARNINGS_AND_ABOVE.

O campo logging_level aceita os seguintes valores:

  • LOGGING_DISABLED: nenhum registro foi gravado.
  • LOG_ERRORS_AND_ABOVE: registra apenas erros.
  • LOG_WARNINGS_AND_ABOVE: registra apenas erros e avisos.
  • LOG_ALL: registra tudo, incluindo registros bem-sucedidos, como INFO.

Taxa de amostragem para registros bem-sucedidos

Se você definir a configuração de nível de geração de registros como LOG_ALL, mas não quiser registrar todos os um registro bem-sucedido, é possível especificar uma taxa de amostragem. Por exemplo, você pode decidir monitorar periodicamente os registros para confirmar o status ou conferir uma porcentagem de registros bem-sucedidos. Especificar uma taxa de amostragem pode ajudar sem gravar um alto volume de entradas de registro INFO Logging, o que pode aumentar os custos.

Para especificar uma taxa de amostragem, defina info_log_sample_rate como um valor flutuante válido maior que 0 e menor ou igual a 1. A taxa de amostragem determina a probabilidade de um registro INFO ser gravado no registro. O valor padrão é 1 (todos os registros INFO são gravados).

Configurações de nível de serviço

É possível definir configurações de registro para serviços específicos. Isso substitui a configuração global de geração de registros para esse serviço. Por exemplo, é possível ter o nível de geração de registros definido como LOG_WARNINGS_AND_ABOVE, Nível de geração de registros do serviço UserEventService para LOG_ALL, para que você possa verificar integrações bem-sucedidas de eventos do usuário.

Use o objeto ServiceLoggingLevel para definir níveis de geração de registros granulares.

O campo service_name aceita os seguintes valores:

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

Tipos de erro

Esta seção fornece definições para os tipos de erro que podem aparecer nas registros:

  • MISSING_FIELD: um valor de campo obrigatório não foi definido. por exemplo, um item de catálogo não tem o título.
  • INVALID_TIMESTAMP: o carimbo de data/hora é inválido, por exemplo, estar muito distante no futuro ou formatado incorretamente.
  • FIELD_VALUE_TOO_SMALL: o valor no campo é menor que o mínimo necessário; por exemplo, um preço negativo.
  • INCORRECT_JSON_FORMAT: o JSON na solicitação está formatado incorretamente, como um colchete { ausente.
  • INVALID_LANGUAGE_CODE: o código do idioma está formatado incorretamente.
  • FIELD_VALUE_EXCEEDED: o valor no campo é maior que o máximo permitido.
  • INVALID_RESOURCE_ID: o ID do recurso é inválido; por exemplo, um catalog_id inexistente no nome do recurso.
  • FIELD_SIZE_EXCEEDED: o número de entradas no campo excede o limite máximo.
  • UNEXPECTED_FIELD: um campo que deveria estar vazio foi preenchido. Por exemplo, a transação para um evento de visualização da página de detalhes.
  • INVALID_FORMAT: o campo não está formatado corretamente, como uma string malformada.
  • RESOURCE_ALREADY_EXISTS: você tentou criar um recurso que já existe, como um item de catálogo criado anteriormente.
  • INVALID_API_KEY: a chave de API não corresponde ao projeto na sua solicitação.
  • INSUFFICIENT_PERMISSIONS: você não tem permissão para executar a solicitação. Esse erro geralmente está relacionado à falta de permissão do IAM necessária.
  • UNJOINED_WITH_CATALOG: a solicitação inclui um código de item de catálogo que não existe no catálogo. Verifique se o seu catálogo está atualizado.
  • BATCH_ERROR: a solicitação tem vários erros. Por exemplo, uma importação in-line com 10 itens que falharam na validação por motivos diferentes.
  • INACTIVE_RECOMMENDATION_MODEL: você consultou um modelo que não está ativo para exibição.
  • ABUSIVE_ENTITY: o ID do visitante ou do usuário associado à solicitação enviou um número anormal de eventos em um curto período.

  • FILTER_TOO_STRICT: o filtro de solicitação de previsão bloqueou todos os resultados da previsão. Os itens genéricos (não personalizados) conhecidos são retornados, a menos que a chamada especifique strictFiltering como falso. Nesse caso, nenhum item é retornado. Veja alguns motivos comuns que podem causar esse problema:

    • Você está especificando uma tag de filtro que não existe no seu catálogo. Pode levar até um dia para que uma atualização de tag de filtro entre em vigor.
    • Seu filtro é muito limitado.

Exibir métricas de carregamento de dados

Para monitorar seu catálogo e a ingestão de dados de eventos do usuário no console do Google Cloud, faça o seguinte: siga estas etapas:

  1. Confira as métricas de erro da ingestão de dados de eventos de catálogo e do usuário na página Monitoramento.

    Acessar a página "Monitoramento"

  2. Depois que seu sistema de upload de dados estiver em execução, use o Catálogo e Evento na página Dados para visualizar informações sobre seu catálogo, visualizar os produtos enviados e acessar visualizações das suas métricas de integração de eventos do usuário.

    Acessar a página "Dados"

  3. Para criar alertas que informam se algo der errado com seus uploads de dados, siga os procedimentos em Configurar alertas do Cloud Monitoring.

Resumo dos dados do catálogo

Use a guia Catálogo na página Dados para ver estatísticas de dados de alto nível para cada ramificação de catálogo. Nesta página, você verá quantos produtos foram importados, quantos estão em estoque e quando foi a última importação de cada ramificação de catálogo de produtos.

Também é possível visualizar os itens do catálogo que você enviou e filtrar com base nos campos dos produtos.

É possível importar dados para diferentes ramificações como uma forma de organizar e visualizar recomendações ou resultados de pesquisa. Por exemplo, para se preparar para um período de festas de fim de ano, faça o upload de novos dados de catálogo para uma ramificação não padrão e verifique se os resultados da Vertex AI para Pesquisa de varejo são gerados corretamente antes de publicar no site.

Estatísticas de gravação de eventos do usuário

Para cada tipo de evento do usuário, é possível ver na guia Evento quantos você gravou, quantos não foram associados a um produto (eventos não incluídos) e as diferenças entre os números e os períodos anteriores. É possível selecionar um período predefinido ou inserir um intervalo personalizado.

O gráfico de métricas exibe os eventos do usuário ingeridos ao longo do tempo, que podem ser filtrados por tipo de evento.

Métricas de qualidade de dados

Na página Qualidade dos dados, você encontra métricas que mostram as porcentagens de produtos e eventos do usuário que atendem aos padrões recomendados de qualidade de dados para pesquisa. Use esta página para avaliar quais dados você precisa importar ou atualizar para melhorar a qualidade dos resultados da pesquisa e desbloquear níveis de desempenho da pesquisa.

Para mais informações sobre os níveis de desempenho da pesquisa e como verificar a qualidade dos seus dados, consulte Desbloquear níveis de desempenho da pesquisa.

Para uma lista de todas as métricas de qualidade de dados do catálogo, consulte Métricas de qualidade de dados do catálogo.

Para todos os requisitos e recomendações de eventos do usuário para recomendações e pesquisa, consulte Requisitos e práticas recomendadas para eventos do usuário.

Eventos cancelados

Quando um evento do usuário ou solicitação de API se refere a um produto que não foi enviado para a Vertex AI para Pesquisa para Retail, é um evento não associado. Os eventos de usuários não associados ainda são registrados, e as solicitações separadas são processadas, mas nenhum deles pode ser usado para melhorar ainda mais o modelo para previsões futuras. Por esse motivo, verifique se a porcentagem de evento não registrado é muito baixa para eventos de usuário e solicitações de previsão.

Veja a porcentagem de evento de usuário desconectado na guia Evento da página Dados.

Erros da API

Para conferir um gráfico de erros da API ao longo do tempo, exibido pelo nome do método, clique em Visualizar métricas da API na barra de botões da página Monitoramento.

Monitorar a atividade do método da API

Para visualizações de tráfego, erros e latência por método de API, acesse Página Monitoramento. Você pode selecionar um período predefinido ou inserir um intervalo personalizado.

Para ver mais detalhes sobre cada gráfico:

  • Abaixo de um gráfico, clique no nome de um método para isolá-lo.
  • Passe o cursor sobre um gráfico para ver uma chamada com cada método e os valores deles nesse momento.
  • Clique e arraste sobre qualquer seção do gráfico para aumentar o zoom nesse período.

A seguir