Coletar dados de telemetria 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 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.

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.

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.

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.

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)

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

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.

• Criar ou editar uma pasta de trabalho do Azure
• Criar e partilhar dashboards dos dados do Log Analytics
• Integrar o Log Analytics com o Power BI

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.