Monitorize e resolva problemas

Esta página descreve como obter informações sobre erros que ocorreram nas importações de catálogos e eventos do utilizador, bem como noutras operações da API na Vertex AI Search for commerce.

Para obter ajuda com a configuração de alertas, consulte o artigo Configure alertas do Cloud Monitoring.

Introdução

O fornecimento de informações precisas do catálogo e eventos do utilizador à API é importante para receber resultados da mais alta qualidade. A monitorização e a compreensão da origem dos erros ajudam a encontrar e corrigir erros no seu site.

Veja erros de integração agregados

Para ver os erros agregados gerados pelos seus processos de carregamento de dados e pedidos de previsão ou de pesquisa, use a página Monitorização.

Esta página apresenta todos os erros da API Vertex AI Search for commerce. Pode ver erros relacionados com o catálogo de produtos, eventos do utilizador, previsões de recomendações, resultados da pesquisa e modelos. O sistema também regista erros de importações, como uma linha com formato incorreto no ficheiro do Cloud Storage. O sistema regista até 100 erros por ficheiro de importação. Pode definir o período durante o qual os erros são apresentados e filtrar com base no tipo de erro.

Pode clicar num erro individual para ver os registos desse erro no Cloud Logging.

Pode abrir registos de erros individuais expandindo esse registo. Os registos de erros fornecem mais detalhes sobre o pedido, incluindo os payloads de pedidos e respostas e os detalhes dos erros. Estas informações podem ajudar a determinar onde a chamada de método errónea se encontra no seu site.

Para erros JSON inválidos, pode obter mais informações sobre o problema expandindo o campo status.

Veja o estado de uma operação de integração específica

Pode ver o estado de uma operação de integração específica na janela Estado da atividade:

1. Aceda à página Dados> na consola de pesquisa para comércio.
   
   Aceda à página Dados

2. Clique em Estado da atividade.

   A janela Estado da atividade mostra o estado das operações de longa duração no catálogo de produtos, nos eventos do utilizador e nos controlos.

   Pode inspecionar erros de operações de integração específicas nesta janela.

3. Clique em Ver registos na coluna Detalhes de qualquer operação com um erro para inspecionar os respetivos ficheiros de registo no Cloud Logging.

Veja registos no Cloud Logging

Para abrir os ficheiros de registo diretamente no Cloud Logging, use o seguinte procedimento. Tem de ter a função de visualizador de registos (roles/logging.viewer) para ver registos.

1. Aceda ao Explorador de registos na Google Cloud consola. Aceda ao Explorador de registos

2. Selecione o seu projeto do Vertex AI Search para comércio no seletor de projetos.

3. Clique no menu pendente Recurso e selecione API consumida > Cloud Retail.

Para mais informações sobre o Explorador de registos, consulte o artigo Veja registos através do Explorador de registos.

Por exemplo, este link abre os registos de todos os erros do Vertex AI Search for commerce na última hora:

Abra os registos do Vertex AI Search para comércio

Para configurar os registos de API que são escritos, consulte o artigo Configurar registo.

Configure o registo

Pode configurar os registos de serviço que são escritos no Logging. A configuração de registo oferece uma forma de definir os níveis de gravidade nos quais escrever registos, ativar ou desativar o registo e substituir as predefinições de registo para serviços específicos.

Cada pedido de API que um utilizador final faz pode gerar uma entrada de registo. Uma entrada contém informações como o método da API, quando foi invocado, o código de resposta e os corpos do pedido e da resposta. A configuração de registo de um projeto especifica os tipos de registos gerados pela API que são escritos no Logging, com a opção de especificar detalhadamente as configurações de registo para serviços de API específicos.

Para atualizar as configurações de registo, precisa da função de editor do Vertex AI Search for commerce.

Pode usar a consola ou a API LoggingConfig para configurar o registo.

Consola

Para atualizar as configurações de registo na consola, siga estes passos:

1. Aceda à página Monitorização na consola do Search for commerce.
   
   Aceda à página Monitorização

2. Clique em Configuração do registo.

3. Para definir uma configuração de registo global, selecione um nível de registo. Se selecionar LOG_ALL, também introduza uma taxa de amostragem para registos bem-sucedidos.

4. Para definir uma configuração ao nível do serviço, selecione um serviço para atualizar e selecione o respetivo nível de registo. Esta definição substitui a configuração de registo global.

curl

Para atualizar as configurações de registo através da API, use o recurso LoggingConfig Consulte a LoggingConfig referência da API.

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

   Este exemplo usa loggingConfig.Patch para definir a configuração de registo global como LOG_WARNINGS_AND_ABOVE. Também define duas configurações ao nível do serviço: CatalogService está definido 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 registo

Apenas os registos de alguns níveis de gravidade são escritos no registo. As definições do nível de registo determinam que registos gerados por um método de API são escritos no registo.

Quando não é definida nenhuma configuração de registo ao nível do serviço para um método da API, é usada a definição de nível de registo global.

A predefinição do nível de registo é LOG_WARNINGS_AND_ABOVE.

O campo logging_level aceita os seguintes valores:

• LOGGING_DISABLED: nenhum registo escrito.
• LOG_ERRORS_AND_ABOVE: regista apenas erros.
• LOG_WARNINGS_AND_ABOVE: regista apenas erros e avisos.
• LOG_ALL: regista tudo, incluindo registos bem-sucedidos, como registos INFO.

Taxa de amostragem para registos bem-sucedidos

Se definir a definição do nível de registo como LOG_ALL, mas não quiser registar todos os registos bem-sucedidos, pode especificar uma taxa de amostragem. Por exemplo, pode decidir monitorizar periodicamente os registos para confirmação do estado de êxito ou querer ver uma percentagem de registos bem-sucedidos. A especificação de uma taxa de amostragem pode ajudar a fazê-lo sem escrever um volume elevado de entradas de registo no Logging, o que pode incorrer em custos de registo mais elevados.INFO

Para especificar uma taxa de amostragem, defina info_log_sample_rate como um valor flutuante válido superior a 0 e igual ou inferior a 1. A taxa de amostragem determina a probabilidade de um registo INFO ser escrito no Registo. O valor predefinido é 1 (todos os registos INFO são escritos).

Aviso: se o nível de registo não estiver definido como LOG_ALL, o campo info_log_sample_rate tem de permanecer não especificado.

Configurações ao nível do serviço

Pode definir configurações de registo para serviços específicos. Isto substitui a definição de registo global para esse serviço. Por exemplo, pode ter o nível de registo global definido como LOG_WARNINGS_AND_ABOVE, mas definir o nível de registo do serviço UserEventService como LOG_ALL para poder verificar as integrações de eventos de utilizadores bem-sucedidas.

Use o objeto ServiceLoggingLevel para definir níveis de registo detalhados.

O campo service_name aceita os seguintes valores:

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

Tipos de erros

Esta secção fornece definições para os tipos de erros que podem aparecer nos seus registos:

• MISSING_FIELD: O valor de um campo obrigatório não está definido. Por exemplo, um item do catálogo não tem título.
• INVALID_TIMESTAMP: a indicação de tempo é inválida, por exemplo, está demasiado no futuro ou tem uma formatação incorreta.
• FIELD_VALUE_TOO_SMALL: o valor no campo é inferior ao mínimo obrigatório; por exemplo, um preço negativo.
• INCORRECT_JSON_FORMAT: o JSON no pedido está formatado incorretamente, como um { parênteses em falta.
• INVALID_LANGUAGE_CODE: o código do idioma tem um formato incorreto.
• FIELD_VALUE_EXCEEDED: o valor no campo é superior ao 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 se esperava estar vazio tem um valor; por exemplo, uma transação para um evento de visualização de página de detalhes.
• INVALID_FORMAT: o campo não está formatado corretamente, como uma string com formato incorreto
• RESOURCE_ALREADY_EXISTS: tentou criar um recurso que já existe, como um artigo do catálogo criado anteriormente.
• INVALID_API_KEY: a chave da API não corresponde ao projeto no seu pedido.
• INSUFFICIENT_PERMISSIONS: Não tem autorização para executar o pedido; normalmente, este erro está relacionado com a falta de uma autorização de IAM necessária.
• UNJOINED_WITH_CATALOG: o pedido inclui um ID de item do catálogo que não existe no catálogo. Certifique-se de que o catálogo está atualizado.
• BATCH_ERROR: O pedido tem vários erros; por exemplo, uma importação inline com 10 artigos que falham a validação por motivos diferentes.
• INACTIVE_RECOMMENDATION_MODEL: consultou um modelo que não está ativo para serviço.
• ABUSIVE_ENTITY: O ID do visitante ou o ID do utilizador associado ao pedido enviou um número anormal de eventos num curto período de tempo.

• FILTER_TOO_STRICT: o filtro de pedido de previsão bloqueou todos os resultados da previsão. São devolvidos artigos populares genéricos (não personalizados), a menos que a chamada tenha especificado strictFiltering como falso, caso em que não são devolvidos artigos. Alguns motivos comuns pelos quais este problema ocorre:

  • Está a especificar uma etiqueta de filtro que não existe no seu catálogo. A aplicação de uma atualização de etiqueta de filtro pode demorar até um dia.
  • O filtro é demasiado restrito.

Veja as métricas de carregamento de dados

Para monitorizar o carregamento dos dados do catálogo e dos eventos do utilizador na Google Cloud consola, siga estes passos:

1. Veja as métricas de erro para a ingestão de dados de eventos do utilizador e do catálogo na página Monitorização.

   Aceda à página Monitorização

2. Depois de o sistema de carregamento de dados estar a ser executado com êxito, use os separadores Catálogo e Evento na página Dados para ver informações agregadas sobre o catálogo, pré-visualizar os produtos carregados e ver visualizações das métricas de integração de eventos do utilizador.

   Aceda à página Dados

3. Para criar alertas que lhe permitem saber se algo correu mal com os carregamentos de dados, siga os procedimentos em Configure alertas do Cloud Monitoring.

Resumo dos dados do catálogo

Use o separador Catálogo na página Dados para ver estatísticas de dados de alto nível para cada ramificação do catálogo. Esta página apresenta quantos produtos importou, quantos estão em stock e quando importou produtos pela última vez para cada ramo do catálogo de produtos.

Também pode ver uma pré-visualização dos itens do catálogo que carregou e filtrar com base nos campos dos produtos.

Pode importar dados para diferentes ramificações como forma de preparar e pré-visualizar recomendações ou resultados da pesquisa. Por exemplo, para se preparar para a época festiva, pode carregar novos dados do catálogo para uma ramificação não predefinida e certificar-se de que os resultados do Vertex AI Search for commerce são gerados corretamente antes de os disponibilizar no seu Website.

Estatísticas de gravação de eventos do utilizador

Para cada tipo de evento do utilizador, pode ver no separador Evento quantos registou, quantos desses eventos não foi possível associar a um produto (eventos não associados) e como os números diferiram dos períodos anteriores. Pode selecionar um período predefinido ou introduzir um intervalo de tempo personalizado.

O gráfico de métricas apresenta os eventos de utilizadores carregados ao longo do tempo, que pode filtrar por tipo de evento de utilizador.

Nota: os períodos das estatísticas estão no fuso horário do Pacífico. Por exemplo, as estatísticas diárias representam os dados de ontem à meia-noite, hora do Pacífico, até hoje à meia-noite, hora do Pacífico.

Métricas de qualidade de dados

Na página Qualidade dos dados, pode ver métricas que mostram as percentagens de produtos e eventos de utilizadores que cumprem as normas recomendadas de qualidade dos dados para a pesquisa. Use esta página para avaliar que dados tem de 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 o artigo Desbloqueie os níveis de desempenho da pesquisa.

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

Para ver todos os requisitos e recomendações de eventos do utilizador para recomendações e pesquisas, consulte o artigo Requisitos e práticas recomendadas de eventos do utilizador.

Eventos não associados

Quando um evento de utilizador ou um pedido de API se refere a um produto que não foi carregado na Vertex AI Search para comércio, trata-se de um evento não associado. Os eventos de utilizadores não associados continuam a ser registados e os pedidos não associados são processados, mas nenhum deles pode ser usado para melhorar ainda mais o modelo para previsões futuras. Por este motivo, deve certificar-se de que a percentagem de eventos não registados é muito baixa para eventos do utilizador e pedidos de previsão.

Pode ver a percentagem de eventos de utilizadores não associados no separador Evento na página Dados.

Erros da API

Pode ver um gráfico de erros da API ao longo do tempo, apresentado por nome do método, clicando em Ver métricas da API na barra de botões da página Monitorização.

Monitorize a atividade do método da API

Para ver visualizações do tráfego, dos erros e da latência por método da API, aceda à página Monitorização. Pode selecionar um período predefinido ou introduzir um intervalo de tempo personalizado.

Para ver mais detalhes sobre cada gráfico:

• Abaixo de um gráfico, clique no nome de um método para o isolar no gráfico.
• Passe o cursor do rato sobre um gráfico para ver uma legenda com cada método e os respetivos valores nesse momento.
• Clique e arraste o cursor sobre qualquer secção do gráfico para aumentar o zoom nesse período.

O que se segue?

• Saiba como configurar alertas de erro para os seus feeds de dados.
• Saiba mais acerca dos relatórios de erros.
• Saiba mais sobre como ver registos no Logging.