Coletar dados telemétricos para análise de tráfego de pesquisa

A análise de tráfego de pesquisa é um padrão para coletar telemetria sobre interações do usuário com seu aplicativo IA do Azure Search, como eventos de clique iniciados pelo usuário e entradas de teclado. Com 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 geram zero resultados.

Esse padrão depende do Application Insights (um recurso do Azure Monitor) para coletar dados do usuário. É necessário adicionar instrumentação ao código do seu cliente, conforme descrito neste artigo. Por fim, você precisa de um mecanismo de relatório para analisar os dados. É recomendável usar o Power BI, mas você pode usar uma ferramenta de visualização que se conecte ao Application Insights.

Observação

O padrão descrito neste artigo é para cenários avançados e dados de fluxo de cliques gerados pelo código adicionado ao seu cliente. Por outro lado, os logs de serviço são fáceis de configurar, fornecem uma variedade de métricas e podem ser feitos no portal sem a necessidade de código. O registro em log é recomendado para todos os cenários. Para obter mais informações, consulte Coletar e analisar dados de logs.

Identificar dados de pesquisa relevantes

Para ter métricas úteis para análise de tráfego de pesquisa, é necessário registrar alguns sinais dos usuários do aplicativo de pesquisa. Esses sinais indicam o conteúdo no qual os usuários estão interessados e o que eles consideraram relevantes. Para análise do tráfego de pesquisa, estão incluídos:

• Eventos de pesquisa gerados pelo usuário: somente consultas de pesquisa iniciadas por um usuário são interessantes. Outras solicitações de pesquisa, como aquelas 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ção ou desvio nos resultados.

• Eventos de clique gerados pelo usuário: em uma página de resultados da 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 aplicativo.

Adicionar análise de tráfego de pesquisa

Na página do portal do serviço IA do Azure Search, abra a página Análise de Tráfego de Pesquisa para acessar uma folha de referência para seguir esse 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 de código que podem ser adaptados para sua solução e baixar um relatório de Power BI criado sobre o esquema refletido no padrão.

Etapa 1: Configurar o Application Insights

Selecione um recurso existente do Application Insights ou crie um caso você não tenha um.

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

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

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

2. No menu Project, selecione Serviços Conectados>Adicionar>Azure Application Insights.

3. Em Conectar-se à 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 controladas com métricas padrão.

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

Etapa 2: Adicionar instrumentação

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

Criar um cliente de telemetria

Crie um objeto que envie 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 com suporte.

A telemetria do lado do servidor captura as métricas na camada do aplicativo, por exemplo, em aplicativos em execução 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 de clique, a posição de um documento nos resultados e as informações de consulta, mas sua coleta de dados terá o escopo definido para 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 de uma home page versus uma página do produto). Se isso descrever sua solução, você poderá optar pela instrumentação do lado do cliente para que sua telemetria reflita os detalhes extras. Como esse detalhe extra é coletado vai além do escopo desse padrão, mas você pode examinar Application Insights para páginas da Web para obter ajuda com essa decisão.

Você pode obter a chave de instrumentação no portal do Azure, nas páginas do Application Insights ou na página 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";

Solicitar uma ID de pesquisa para correlação

Importante

No portal do Azure, os snippets de código para cabeçalhos de solicitação são feitos usando uma versão desatualizada do SDK do Azure. As atualizações estão pendentes.

Para correlacionar solicitações de pesquisa com cliques, é necessário ter uma ID de correlação que relacione esses dois eventos distintos. O IA do Azure Search fornece uma ID de pesquisa ao solicitá-la com um cabeçalho HTTP.

Ter a ID de pesquisa permite a correlação das métricas emitidas pela Pesquisa de IA do Azure para a solicitação em si, com as métricas personalizadas que você está registrando em log no Application Insights.

var client = new SearchClient(<SEARCH SERVICE NAME>, <INDEX NAME>, new AzureDefaultCredentials())
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
IEnumerable<string> headerValues;
string searchId = string.Empty;
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
	 searchId = headerValues.FirstOrDefault();
} 

Eventos de pesquisa de logs

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: (cadeia de caracteres) nome do serviço de pesquisa
• SearchId: (guid) identificador exclusivo da consulta de pesquisa (vem na resposta da pesquisa)
• IndexName: (cadeia de caracteres) índice do serviço de pesquisa a ser consultado
• QueryTerms: (cadeia de caracteres) termos de pesquisa inseridos pelo usuário
• ResultCount: (int) número de documentos retornados (vem na resposta da pesquisa)
• ScoringProfile: (cadeia de caracteres) nome do perfil de pontuação usado, se houver

Observação

Solicite a contagem de consultas geradas pelo usuário adicionando $count=true à 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);

Eventos de cliques de log

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

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

Observação

Position refere-se à ordem cardinal em seu aplicativo. Você tem a liberdade 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

Após instrumentar o aplicativo e verificar se o aplicativo está conectado corretamente ao Application Insights, você baixa um modelo de relatório predefinido para analisar os dados na área de trabalho do Power BI. O relatório contém gráficos predefinidos e tabelas ú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 o 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 as informações de conexão nas páginas do portal do Azure para o recurso do Application Insights. Para as credenciais, forneça o mesmo nome de usuário e senha que você usa para entrar no portal.

   

5. Selecione Carregar.

O relatório contém gráficos e tabelas que ajudam você a tomar decisões mais inteligentes a fim de melhorar o desempenho e a relevância da pesquisa.

As métricas incluem os seguintes itens:

• Volume de pesquisa e pares de documentos/termos mais populares: termos que resultam no mesmo documento clicado, ordenados por cliques.
• Pesquisa sem cliques: termos das principais consultas que não registraram nenhum clique

A captura de tela a seguir mostra os elementos de dados que seu relatório pode conter.

Próximas etapas

Instrumente seu aplicativo de pesquisa para obter dados informativos e avançados sobre o 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.