Recopilación de datos de telemetría para análisis del tráfico de búsqueda

Artículo
11/03/2024

El análisis de tráfico de búsqueda es un patrón para recopilar telemetría sobre las interacciones del usuario con la aplicación Búsqueda de Azure AI, como eventos de secuencia de clic iniciados por el usuario y entradas de teclado. Con esta información, puede determinar la eficacia de la solución de búsqueda, incluidas la tasa de clics y las entradas de consulta que producen cero resultados.

La instrumentación tiene las siguientes partes:

Agregar un cliente de telemetría
Modificación de una solicitud de búsqueda para incluir un identificador de correlación que asigna los resultados de búsqueda a las acciones del usuario
Creación y envío de un evento personalizado a Application Insights y uso de las herramientas de visualización e informes para ver los datos de eventos

Este patrón depende de Application Insights (una característica de Azure monitor) para recopilar datos de usuario. Requiere que agregue instrumentación al código de la aplicación, como se describe en este artículo. Por último, necesita un mecanismo de informes para analizar los datos. Puede usar cualquier herramienta de visualización que se conecte a Application Insights.

Nota:

El patrón que se describe en este artículo es para escenarios avanzados y datos de la secuencia de clics generados por el código que agrega al cliente. En cambio, los registros de servicio son fáciles de configurar, proporcionan una variedad de métricas, incluidos los términos de búsqueda, y se pueden realizar en Azure Portal sin que se requiera código. Se recomienda habilitar el registro para todos los escenarios. Para obtener más información, consulte Recopilación y análisis de datos de registro.

Requisitos previos

Azure AI Search, cualquier región, nivel básico y superior.
Application Insights.
Una aplicación cliente enriquecida que proporciona una experiencia de búsqueda interactiva que incluye eventos de secuencia de clic u otras acciones de usuario que desea correlacionar con las selecciones de resultados de búsqueda.

Identificación de los datos de búsqueda pertinentes

Para recopilar métricas útiles para el análisis de tráfico de búsqueda, es necesario registrar algunas señales de los usuarios de la aplicación de búsqueda. Estas señales indican el contenido en el que los usuarios están interesados y que consideran relevantes. Para el análisis del tráfico de búsqueda, se incluyen:

Eventos de búsqueda generados por el usuario: solo son interesantes las consultas de búsqueda iniciadas por un usuario. Otras solicitudes de búsqueda, como las que se usan para rellenar facetas o recuperar información interna, no son importantes. Asegúrese de instrumentar solo eventos iniciados por el usuario para evitar la distorsión o el sesgo en los resultados.
Eventos de secuencia de clic generados por el usuario: en una página de resultados de búsqueda, un evento clickstream generalmente significa que un documento es un resultado relevante para una consulta de búsqueda específica.

En el código de la aplicación, debe correlacionar estos eventos con los resultados de búsqueda devueltos de una consulta determinada. Al vincular eventos de búsqueda y secuencia de clics con un identificador de correlación, puede comprender mejor el rendimiento de la funcionalidad de búsqueda de la aplicación.

Incorporación de los análisis del tráfico de búsqueda

Para la Búsqueda de Azure AI, el Azure Portal proporciona una página de Análisis de tráfico de búsqueda que tiene fragmentos de código de C# y JavaScript para agregar un cliente de telemetría, encabezados de solicitud y propiedades necesarios para eventos de registro personalizados.

Importante

La página del portal de análisis de tráfico de búsqueda está obsoleta actualmente y hace referencia a una biblioteca cliente obsoleta. La solución consiste en usar fragmentos de código del repositorio de GitHub de azure-search-traffic-analytics. En este artículo se incluyen fragmentos de código del repositorio de GitHub.

Paso 1: Configuración de Application Insights

Cree un objeto que envíe eventos a Application Insights. Puede agregar instrumentación al código de aplicación del lado servidor o al código del lado cliente que se ejecuta en un explorador, expresado aquí como variantes de C# y JavaScript. Para otros lenguajes, vea plataformas y marcos admitidos.

La telemetría del lado servidor captura las métricas en el nivel de aplicación, por ejemplo, en las aplicaciones que se ejecutan como un servicio web en Azure o como una aplicación local en una red corporativa. La telemetría del lado servidor captura los eventos de búsqueda y secuencia de clics, la posición de un documento en los resultados y la información de consulta, pero la recopilación de datos se limitará a cualquier información disponible en esa capa.

En el cliente, es posible que tenga otro código que manipule las entradas de consulta, agregue navegación o incluya contexto (por ejemplo, consultas iniciadas desde una página principal frente a una página de producto). Si describe la solución, puede optar por la instrumentación del lado cliente para que la telemetría refleje los detalles adicionales. Cómo se recopilan estos detalles adicionales va más allá del ámbito de este patrón, pero puede revisar Application Insights para páginas web para obtener ayuda con esa decisión.

En este paso, proporcione una cadena de conexión Application Insights.

En los pasos siguientes se refleja un acceso directo que funciona en algunos tipos de proyecto de Visual Studio.

Abra su solución en Visual Studio.
En el menú Proyecto, seleccione Servicios conectados>Agregar>Azure Application Insights.
En Conectarse a dependencias, seleccione Azure Application Insights, y después, seleccione Siguiente.
Seleccione la suscripción de Azure, el recurso de Application Insights y después, seleccione Finalizar.

En este momento, la aplicación está configurada para la supervisión de aplicaciones, lo que significa que se realiza un seguimiento de todas las cargas de página de la aplicación cliente con métricas predeterminadas.

Si este acceso directo no funciona, consulte Habilitación de la telemetría del lado servidor de Application Insights o consulte fragmentos de código en las pestañas adyacentes.

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();

Paso 2: Agregar instrumentación

Agregue código de instrumentación a la aplicación cliente.

Correlación de eventos clickstream con resultados de búsqueda

Para correlacionar las solicitudes de búsqueda con clics, es necesario tener un identificador de correlación que relacione estos dos eventos distintos. Azure AI Search proporciona un identificador de búsqueda cuando se solicita con un encabezado HTTP.

Disponer del Id. de búsqueda permite correlacionar las métricas emitidas por Azure AI Search para la solicitud en sí, con las métricas personalizadas que está registrando en 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

Cada vez que un usuario emite una solicitud de búsqueda, debe registrarla como un evento de búsqueda con el esquema siguiente en un Evento personalizado de Application Insights. Recuerde registrar solo las consultas de búsqueda generadas por el usuario.

SearchId: (guid) identificador único de la consulta de búsqueda (integrada en la respuesta de búsqueda)
SearchServiceName: (cadena) nombre del servicio de búsqueda
IndexName: (cadena) índice del servicio de búsqueda que se va a consultar
SearchText: (cadena) los términos de búsqueda especificados por el usuario
ResultCount: (int) número de documentos que se devolvieron (integrados en la respuesta de búsqueda)

Nota:

Solicite el recuento de consultas generadas por el usuario agregando $count=true a la consulta de búsqueda. Para más información, consulte Búsqueda de 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
};

Envío del evento personalizado a Application Insights

Agregue el personalizado incluso a la tabla eventos personalizadosen Application Insights. Para más información, consulte API de Application Insights para eventos y métricas personalizados.

.NET
JavaScript

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

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

Paso 3: Revisión de los registros

Use cualquiera de los enfoques admitidos por Application Insights para ver eventos personalizados.

Pasos siguientes

Puede encontrar más información en Application Insights y visitar la página de precios para conocer más sobre los distintos niveles de servicio.

Obtenga más información sobre la creación de informes. Consulte Introducción a Power BI Desktop para más información.

Compartir a través de