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

Artigo
10/31/2024

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 clickstream 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 a taxa de cliques e quais entradas de consulta produzem resultados zero.

A instrumentação tem as seguintes partes:

Adicionar um cliente de telemetria
Modificar uma solicitação de pesquisa para incluir uma Id de correlação que mapeia os resultados da pesquisa para as ações do usuário
Crie e envie um evento personalizado para o Application Insights e use as ferramentas de visualização e relatório para exibir dados de eventos

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 aplicativo, conforme descrito neste artigo. Finalmente, você precisa de um mecanismo de relatório para analisar os dados. Você pode usar qualquer ferramenta de visualização 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. Por outro lado, os logs de serviço são fáceis de configurar, fornecem uma variedade de métricas, incluindo termos de pesquisa, e podem ser feitos no portal do Azure sem necessidade de código. Recomendamos que você habilite o registro em log para todos os cenários. Para obter mais informações, consulte Coletar e analisar dados de log.

Pré-requisitos

Azure AI Search, qualquer região, camada básica e superior.
Application Insights.
Um aplicativo cliente avançado que fornece uma experiência de pesquisa interativa que inclui eventos de fluxo de cliques ou outras ações do usuário que você deseja correlacionar às seleções de resultados de pesquisa.

Identificar dados de pesquisa relevantes

Para coletar métricas úteis para 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 clickstream gerados pelo usuário: em uma página de resultados de pesquisa, um evento de clickstream geralmente significa que um documento é um resultado relevante para uma consulta de pesquisa específica.

No código do aplicativo, você deve correlacionar esses eventos com os resultados da pesquisa retornados de uma determinada consulta. Ao vincular eventos de pesquisa e fluxo de cliques a 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

Para o Azure AI Search, o portal do Azure fornece uma página de Análise de Tráfego de Pesquisa que tem trechos de código C# e JavaScript para adicionar um cliente de telemetria, cabeçalhos de solicitação e propriedades necessárias para eventos de log personalizados.

Importante

A página do portal de análise de tráfego de pesquisa está atualmente desatualizada e faz referência a uma biblioteca de cliente obsoleta. A solução alternativa é usar trechos de código do repositório do GitHub azure-search-traffic-analytics . Este artigo inclui trechos de código do repositório GitHub.

Etapa 1: Configurar o Application Insights

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 clickstream, 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.

Nesta etapa, forneça uma cadeia de conexão para o Application Insights.

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

Abra a sua solução no Visual Studio.
No menu Projeto, selecione Serviços conectados Adicionar>Azure>Application Insights.
Em Conectar à dependência, selecione Azure Application Insights e selecione Avançar.
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 ou consulte trechos de código nas guias adjacentes.

var telemetryConfiguration = new TelemetryConfiguration
{
    ConnectionString = "<PUT YOUR CONNECTION STRING HERE>"
};
var telemetryClient = new TelemetryClient(telemetryConfiguration);

const appInsights = new ApplicationInsights({ config: {
  connectionString: '<PUT YOUR CONNECTION STRING HERE>'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();

Etapa 2: adicionar instrumentação

Adicione código de instrumentação ao seu aplicativo cliente.

Correlacione eventos de clickstream com resultados de pesquisa

Para correlacionar solicitações de pesquisa com cliques, é necessário ter um ID de correlação que relacione esses dois eventos distintos. O Azure AI Search fornece uma ID de pesquisa quando você a solicita com um cabeçalho HTTP.

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

.NET
JavaScript

var client = new SearchClient(new Uri("https://contoso.search.windows.net"), "hotels-sample-index", new DefaultAzureCredential());

// Generate a new correlation id for logs
string searchId = Guid.NewGuid().ToString();
string searchText = "*";
SearchResults<SearchDocument> searchResults;

// Set correlation id for search request
using (HttpPipeline.CreateClientRequestIdScope(clientRequestId: searchId))
{
    searchResults = client.Search<SearchDocument>(searchText, options: new SearchOptions { IncludeTotalCount = true } );
}

const searchId = uuidv4();
const searchText = "*";
const searchResults = await searchClient.search(searchText, { includeTotalCount: true, customHeaders: { "x-ms-client-request-id": searchId }});
const properties = {
    searchId: searchId,
    serviceName: "<PUT YOUR SEARCH SERVICE NAME HERE, example contoso-search>",
    indexName: "<PUT YOUR INDEX NAME HERE>",
    searchText: searchText,
    resultsCount: searchResults.count
};
appInsights.trackEvent({ name: "search" }, properties);

Registrar eventos personalizados

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.

SearchId: identificador exclusivo (guid) da consulta de pesquisa (incorporado na resposta da pesquisa)
SearchServiceName: (string) nome do serviço de pesquisa
IndexName: índice do serviço de pesquisa (string) a ser consultado
SearchText: (string) termos de pesquisa inseridos pelo usuário
ResultCount: (int) número de documentos que foram devolvidos (incorporados na resposta da pesquisa)

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).

.NET
JavaScript

// Create properties for telemetry
var properties = new Dictionary<string, string>
{
    ["searchId"] = searchId,
    ["serviceName"] = "<PUT YOUR SEARCH SERVICE NAME HERE, example: contoso-search>",
    ["indexName"] = "<PUT YOUR INDEX NAME HERE>",
    ["searchText"] = searchText,
    ["resultsCount"] = searchResults.TotalCount?.ToString()
};

const properties = {
    searchId: searchId,
    serviceName: "<PUT YOUR SEARCH SERVICE NAME HERE, example contoso-search>",
    indexName: "<PUT YOUR INDEX NAME HERE>",
    searchText: searchText,
    resultsCount: searchResults.count
};

Enviar o evento personalizado para o Application Insights

Adicione o personalizado mesmo à tabela de eventos personalizados no Application Insights. Para obter mais informações, consulte API do Application Insights para eventos e métricas personalizados.

.NET
JavaScript

telemetryClient.TrackEvent("search", properties);
telemetryClient.Flush();

appInsights.trackEvent({ name: "search" }, properties);

Etapa 3: Revisar os logs

Use qualquer uma das abordagens suportadas pelo Application Insights para exibir eventos personalizados.

Próximos passos

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.

Partilhar via