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

Artigo
11/05/2024

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 sequência de cliques 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 a taxa de cliques e quais entradas de consulta geram zero resultados.

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 mapeie os resultados da pesquisa para ações do usuário
Criar e enviar um evento personalizado para o Application Insights e usar 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. É necessário adicionar instrumentação ao código de aplicativo, conforme descrito neste artigo. Por fim, você precisa de um mecanismo de relatório para analisar os dados. 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, inclusive termos de busca, e isso pode ser feito no portal do Azure sem necessidade de código. É recomendável habilitar o registro em log para todos os cenários. Para obter mais informações, consulte Coletar e analisar dados de logs.

Pré-requisitos

Pesquisa de IA do Azure, 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 sequência de cliques ou outras ações de 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 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 sequência de cliques gerados pelo usuário: em uma página de resultados da pesquisa, um evento de sequência de cliques 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 sequência de cliques 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

Para a Pesquisa de IA do Azure, o portal do Azure fornece uma página de Análise de Tráfego de Pesquisa que tem snippets 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á desatualizada no momento e faz referência a uma biblioteca de clientes obsoleta. A solução alternativa é usar snippets de código do repositório do GitHub azure-search-traffic-analytics. Este artigo inclui snippets de código do repositório GitHub.

Etapa 1: Configurar o Application Insights

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 sequência de cliques, 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.

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 sua solução no Visual Studio.
No menu Project, selecione Serviços Conectados>Adicionar>Azure Application Insights.
Em Conectar-se à 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 controladas com métricas padrão.

Se esse atalho não funcionar para você, consulte Habilitar telemetria do lado do servidor do Application Insights ou consulte os snippets 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 aplicativo cliente.

Correlacionar eventos de sequência de cliques com os resultados da pesquisa

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.

.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: (guid) identificador exclusivo da consulta de pesquisa (incluído na resposta da pesquisa)
SearchServiceName: (cadeia de caracteres) nome do serviço de pesquisa
IndexName: (cadeia de caracteres) índice do serviço de pesquisa a ser consultado
SearchText: (cadeia de caracteres) termos de pesquisa inseridos pelo usuário
ResultCount: (int) número de documentos retornados (incluído na resposta da pesquisa)

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

.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 evento personalizado ao Application Insights.

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

.NET
JavaScript

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

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

Etapa 3: examinar logs

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

Próximas etapas

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.

Compartilhar via