Monitoramento e solução de problemas

Nesta página, descrevemos como conseguir informações sobre erros que ocorreram nas importações de catálogos e eventos do usuário e em outras operações de API na Vertex AI para Pesquisa para varejo.

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

Introdução

Fornecer informações de catálogo e eventos do usuário precisos à API é importante para conseguir resultados da mais alta qualidade. Monitorar e entender a origem dos erros ajuda você a encontrar e corrigir erros no seu site.

Conferir erros de integração agregados

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

Nesta página, mostramos todos os erros da API Vertex AI para Pesquisa para varejo. É possível visualizar erros relacionados ao catálogo de produtos, eventos do usuário, previsões de recomendações, resultados da pesquisa e modelos. 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.

Conferir 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 Activity status:

  1. Acesse a página Dados> no console da Pesquisa for Retail.

    Acessar a página "Dados"

  2. Clique em Status da atividade.

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

    Nessa janela, é possível inspecionar erros de operações de integração específicas.

  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 registros diretamente no Cloud Logging, use o procedimento a seguir. Você precisa ter o papel Visualizador de registros (roles/logging.viewer) para acessar os registros.

  1. Acesse a Análise 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, acesse Visualizar registros usando a Análise de registros.

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

Abrir os registros da Vertex AI para Pesquisa para varejo

Para configurar quais registros da API são gravados, consulte Configurar o Logging.

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 registros, ativar ou desativar a geração de registros e substituir as configurações padrão de geração de registros para serviços específicos.

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

Para atualizar as configurações de geração de registros, você precisa do papel de editor da Vertex AI para Pesquisa para varejo.

Use 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 do Search for Retail.

    Acessar a página "Monitoramento"

  2. Clique em Configuração de geração de registros.

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

  4. Para definir uma configuração no nível de serviço, selecione o serviço a ser atualizado e escolha o nível de geração de registros. Essa configuração modifica a configuração de geração de registros global.

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 ver a configuração de geração de registros atual, 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 da geração de registros, use o método loggingConfig.Patch. Para mais informações, consulte a referência da API LoggingConfig.

    Neste exemplo, loggingConfig.Patch é usado para definir a configuração global de geração de registros como LOG_WARNINGS_AND_ABOVE. Ele também define duas configurações de nível de serviço: CatalogService é definido como LOG_WARNINGS_AND_ABOVE e ControlService é 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 geração de registros

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

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

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

O campo logging_level aceita os seguintes valores:

  • LOGGING_DISABLED: nenhum registro 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 dos registros bem-sucedidos

Se você definir a configuração do nível de geração de registros como LOG_ALL, mas não quiser registrar todos os registros bem-sucedidos, especifique uma taxa de amostragem. Por exemplo, você pode decidir monitorar periodicamente os registros para confirmar o status bem-sucedido ou ver uma porcentagem de registros bem-sucedidos. Especificar uma taxa de amostragem pode ajudar você a fazer isso sem gravar um grande volume de entradas de registro INFO no Logging, o que pode gerar custos mais altos.

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 Logging. O valor padrão é 1 (todos os registros INFO são gravados).

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

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

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 de tipos de erros que podem aparecer nos seus 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.

Conferir 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, siga estas etapas:

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

    Acessar a página "Monitoramento"

  2. Depois que o sistema de upload de dados estiver em execução, use as guias Catálogo e Evento na página Dados para conferir informações agregadas sobre o catálogo, os produtos enviados e as visualizações das 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 os 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 maneira de organizar e visualizar recomendações ou resultados de pesquisa. Por exemplo, para se preparar para as festas de fim de ano, é possível fazer upload de novos dados de catálogo para uma ramificação não padrão e garantir que os resultados da Vertex AI para Pesquisa para varejo sejam gerados corretamente antes de ativá-los no seu 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 de dados, é possível conferir 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 de 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 de 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 de eventos do usuário.

Eventos cancelados

Quando um evento do usuário ou uma solicitação de API se refere a um produto que não foi enviado por upload à Vertex AI para Pesquisa para varejo, trata-se de um evento não vinculado. 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 ver um gráfico de erros da API ao longo do tempo, exibido pelo nome do método, clique em Ver métricas da API na barra de botões da página Monitoramento.

Monitorar a atividade do método da API

Para acessar informações sobre tráfego, erros e latência por método da API, acesse a 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