Coletar dados de telemetria para análise de tráfego de pesquisa

  • Artigo

A análise de tráfego de pesquisa é um padrão para coletar telemetria sobre interações do usuário com seu aplicativo Azure AI Search, como eventos de clique iniciados pelo usuário e entradas de teclado. Usando essas informações, você pode determinar a eficácia de sua solução de pesquisa, incluindo termos de pesquisa populares, taxa de cliques e quais entradas de consulta produzem resultados zero.

Esse padrão depende do Application Insights (um recurso do Azure Monitor) para coletar dados do usuário. Ele requer que você adicione instrumentação ao código do cliente, conforme descrito neste artigo. Finalmente, você precisa de um mecanismo de relatório para analisar os dados. Recomendamos o Power BI, mas você pode usar o Painel do Aplicativo ou qualquer ferramenta que se conecte ao Application Insights.

Nota

O padrão descrito neste artigo é para cenários avançados e dados de clickstream gerados pelo código que você adiciona ao seu cliente. Em contraste, os logs de serviço são fáceis de configurar, fornecem uma variedade de métricas e podem ser feitos no portal sem necessidade de código. A habilitação do registro em log é recomendada para todos os cenários. Para obter mais informações, consulte Coletar e analisar dados de log.

Identificar dados de pesquisa relevantes

Para ter métricas úteis para a análise de tráfego de pesquisa, é necessário registrar alguns sinais dos usuários do seu aplicativo de pesquisa. Esses sinais significam conteúdo que os usuários estão interessados e que eles consideram relevantes. Para análise de tráfego de pesquisa, estes incluem:

  • Eventos de pesquisa gerados pelo utilizador: apenas as consultas de pesquisa iniciadas por um utilizador são interessantes. Outras solicitações de pesquisa, como as usadas para preencher facetas ou recuperar informações internas, não são importantes. Certifique-se de instrumentar apenas eventos iniciados pelo usuário para evitar distorções ou distorções em seus resultados.

  • Eventos de clique gerados pelo usuário: em uma página de resultados de pesquisa, um evento de clique geralmente significa que um documento é um resultado relevante para uma consulta de pesquisa específica.

Ao vincular eventos de pesquisa e clique com uma ID de correlação, você pode obter uma compreensão mais profunda do desempenho da funcionalidade de pesquisa do seu aplicativo.

Adicionar análise de tráfego de pesquisa

Na página do portal do seu serviço Azure AI Search, abra a página Análise de Tráfego de Pesquisa para aceder a um cheat sheet para seguir este padrão de telemetria. Nesta página, você pode selecionar ou criar um recurso do Application Insights, obter a chave de instrumentação, copiar trechos que você pode adaptar para sua solução e baixar um relatório do Power BI criado sobre o esquema refletido no padrão.

Captura de tela do comando do portal e da página para configurar o Application Insights.

Etapa 1: Configurar o Application Insights

Selecione um recurso existente do Application Insights ou crie um se ainda não tiver um.

Um atalho que funciona para alguns tipos de projeto do Visual Studio é refletido nas etapas a seguir.

Para ilustração, estas etapas usam o cliente de Adicionar pesquisa a um aplicativo Web estático.

  1. Abra a sua solução no Visual Studio.

  2. No menu Projeto, selecione Serviços conectados Adicionar>Azure>Application Insights.

  3. Em Conectar à dependência, selecione Azure Application Insights e selecione Avançar.

  4. Selecione sua assinatura do Azure, seu recurso do Application Insights e selecione Concluir.

Neste ponto, seu aplicativo está configurado para monitoramento de aplicativos, o que significa que todas as cargas de página em seu aplicativo cliente são rastreadas com métricas padrão.

Se esse atalho não funcionou para você, consulte Habilitar telemetria do lado do servidor do Application Insights.

Etapa 2: adicionar instrumentação

Adicione código de instrumentação ao seu aplicativo cliente. A página Análise de Tráfego de Pesquisa no portal do Azure fornece trechos de código que você pode colar no código do aplicativo.

Criar um cliente de telemetria

Crie um objeto que envia eventos para o Application Insights. Você pode adicionar instrumentação ao código do aplicativo do lado do servidor ou ao código do lado do cliente em execução em um navegador, expresso aqui como variantes C# e JavaScript. Para outros idiomas, consulte plataformas e estruturas suportadas.

A telemetria do lado do servidor captura métricas na camada de aplicativo, por exemplo, em aplicativos executados como um serviço Web no Azure ou como um aplicativo local em uma rede corporativa. A telemetria do lado do servidor captura eventos de pesquisa e clique, a posição de um documento nos resultados e informações de consulta, mas sua coleta de dados terá como escopo qualquer informação disponível nessa camada.

No cliente, você pode ter outro código que manipula entradas de consulta, adiciona navegação ou inclui contexto (por exemplo, consultas iniciadas a partir de uma home page versus uma página de produto). Se isso descrever sua solução, você pode optar pela instrumentação do lado do cliente para que sua telemetria reflita os detalhes extras. A forma como esses detalhes adicionais são coletados vai além do escopo desse padrão, mas você pode revisar o Application Insights para páginas da Web para obter ajuda com essa decisão.

Você pode obter a chave de instrumentação do portal do Azure, nas páginas do Application Insights ou na página de análise de tráfego de pesquisa do Azure AI Search.

// Application Insights SDK: https://www.nuget.org/packages/Microsoft.ApplicationInsights.Web 

var telemetryClient = new TelemetryClient();
telemetryClient.InstrumentationKey = "0000000000000000000000000000";

Registrar eventos de pesquisa

Sempre que uma solicitação de pesquisa é emitida por um usuário, você deve registrá-la como um evento de pesquisa com o esquema a seguir em um evento personalizado do Application Insights. Lembre-se de registrar apenas consultas de pesquisa geradas pelo usuário.

  • SearchServiceName: (string) nome do serviço de pesquisa
  • SearchId: (guid) identificador exclusivo da consulta de pesquisa (vem na resposta da pesquisa)
  • IndexName: índice do serviço de pesquisa (string) a ser consultado
  • QueryTerms: (string) termos de pesquisa inseridos pelo usuário
  • ResultCount: (int) número de documentos que foram devolvidos (vem na resposta da pesquisa)
  • ScoringProfile: (string) nome do perfil de pontuação usado, se houver

Nota

Solicite a contagem de consultas geradas pelo usuário adicionando $count=true à sua consulta de pesquisa. Para obter mais informações, consulte Pesquisar documentos (REST).

var properties = new Dictionary <string, string> {
	{"SearchServiceName", <SEARCH SERVICE NAME>},
	{"SearchId", <SEARCH ID>},
	{"IndexName", <INDEX NAME>},
	{"QueryTerms", <SEARCH TERMS>},
	{"ResultCount", <RESULTS COUNT>},
	{"ScoringProfile", <SCORING PROFILE USED>}
};

telemetryClient.TrackEvent("Search", properties);

Registrar eventos de clique

Toda vez que um usuário clica em um documento, esse é um sinal que deve ser registrado para fins de análise de pesquisa. Use eventos personalizados do Application Insights para registrar esses eventos com o seguinte esquema:

  • ServiceName: (string) nome do serviço de pesquisa
  • SearchId: identificador exclusivo (guid) da consulta de pesquisa relacionada
  • DocId: identificador de documento (string)
  • Posição: (int) classificação do documento na página de resultados da pesquisa

Nota

A posição refere-se à ordem cardinal na sua candidatura. Você é livre para definir esse número, desde que seja sempre o mesmo, para permitir a comparação.

var properties = new Dictionary <string, string> {
	{"SearchServiceName", <SEARCH SERVICE NAME>},
	{"SearchId", <SEARCH ID>},
	{"ClickedDocId", <CLICKED DOCUMENT ID>},
	{"Rank", <CLICKED DOCUMENT POSITION>}
};

telemetryClient.TrackEvent("Click", properties);

Etapa 3: Analisar no Power BI

Depois de instrumentar seu aplicativo e verificar se ele está conectado corretamente ao Application Insights, baixe um modelo de relatório predefinido para analisar dados no Power BI desktop. O relatório contém gráficos e tabelas predefinidos úteis para analisar os dados extras capturados para análise de tráfego de pesquisa.

  1. No portal do Azure nas páginas do serviço de pesquisa, em Configurações, selecione Análise de tráfego de pesquisa.

  2. Selecione Obter o Power BI Desktop para instalar o Power BI.

  3. Selecione Baixar relatório do Power BI para obter o relatório.

  4. O relatório é aberto no Power BI Desktop e você é solicitado a se conectar ao Application Insights e fornecer credenciais. Você pode encontrar informações de conexão nas páginas do portal do Azure para seu recurso do Application Insights. Para credenciais, forneça o mesmo nome de usuário e senha que você usa para entrar no portal.

    Captura de ecrã a mostrar como ligar ao Application Insights a partir do Power BI.

  5. Selecione Carregar.

O relatório contém gráficos e tabelas que o ajudam a tomar decisões mais informadas para melhorar o desempenho e a relevância da sua pesquisa.

As métricas incluíram os seguintes itens:

  • Volume de pesquisa e pares termo-documento mais populares: termos que resultam no mesmo documento clicado, ordenados por cliques.
  • Pesquisas sem cliques: termos para as principais consultas que não registam cliques

A captura de tela a seguir mostra a aparência de um relatório interno se você tiver usado todos os elementos do esquema.

Captura de tela mostrando o relatório interno usando todos os elementos de esquema disponíveis.

Próximos passos

Instrumente seu aplicativo de pesquisa para obter dados poderosos e perspicazes sobre seu serviço de pesquisa.

Você pode encontrar mais informações sobre o Application Insights e visitar a página de preços para saber mais sobre suas diferentes camadas de serviço.

Saiba mais sobre como criar relatórios. Consulte Introdução ao Power BI Desktop para obter detalhes.