Collecter les données de télémétrie pour l’analyse du trafic de recherche

Article
11/04/2024

L’analyse de trafic de recherche est un modèle pour la collecte des données de télémétrie sur les interactions de l’utilisateur avec votre application Recherche Azure AI, comme les événements de clic initiés par l’utilisateur et les saisies au clavier. À l’aide de ces informations, vous pouvez déterminer l’efficacité de votre solution de recherche, en vous intéressant notamment aux taux de clics et aux entrées de requête qui ne produisent aucun résultat.

L’instrumentation comprend les éléments suivants :

Ajouter un client de télémétrie
Modifier une requête de recherche pour inclure un ID de corrélation qui mapper les résultats de la recherche aux actions des utilisateurs
Créer et envoyer un événement personnalisé à Application Insights et utiliser la visualisation et les outils de création de rapports pour afficher les données d’un événement

Ce modèle dépend d’Application Insights (fonctionnalité d’Azure Monitor) pour collecter les données utilisateur. Vous devez également ajouter l’instrumentation à votre code d’application, comme le décrit cet article. Enfin, vous avez besoin d’un mécanisme de création de rapports pour analyser les données. Vous pouvez utiliser n’importe quel outil de visualisation qui se connecte à Application Insights.

Remarque

Le modèle décrit dans cet article est destiné aux scénarios avancés et aux données parcours générées par le code que vous ajoutez à votre client. En revanche, les journaux de service sont faciles à configurer. Ils fournissent toute une série de métriques, notamment pour les termes de recherche, et peuvent être configurés dans le portail Azure sans qu’il soit nécessaire d’écrire du code. Nous vous recommandons d’activer la journalisation pour tous les scénarios. Pour plus d’informations, consultez Collecter et analyser les données de journal.

Prérequis

Recherche Azure AI, toute région, niveau Essentiel et supérieur.
Application Insights.
Une application cliente enrichie fournissant une expérience de recherche interactive qui inclut les événements de clic et d’autres actions de l’utilisateur que vous souhaitez mettre en corrélation aux sélections du résultat de la recherche.

Identifier les données de recherche pertinentes

Si vous souhaitez collecter des mesures utiles pour l’analyse du trafic de recherche, il est nécessaire d’enregistrer certains signaux à partir des utilisateurs de votre application de recherche. Ces signaux indiquent le contenu qui intéresse les utilisateurs et qu’ils estiment pertinent. Pour l’analyse du trafic de recherche, il s’agit des éléments suivants :

Événements de recherche générés par l’utilisateur : ce signal se concentre uniquement sur les requêtes de recherche lancées par un utilisateur. Les autres requêtes de recherche, comme celles utilisées pour renseigner des facettes ou récupérer des informations internes, ne sont pas importantes. Veillez à n'instrumenter que les événements initiés par l'utilisateur afin d'éviter que vos résultats ne soient faussés ou biaisés.
Événements de clics générés par l’utilisateur : sur une page de résultats de la recherche, un événement de clic signifie généralement qu’un document est un résultat pertinent pour une requête de recherche spécifique.

Dans votre code d’application, vous devez mettre en corrélation ces événements avec les résultats de la recherche retournés d’une requête donnée. En liant les événements de recherche et de clic à un ID de corrélation, vous pouvez avoir une meilleure compréhension de la façon dont la fonctionnalité de recherche de votre application fonctionne.

Ajouter la fonctionnalité Analytique du trafic des recherches

Pour Recherche Azure AI, le Portail Azure fournit une page Rechercher l’analyse de trafic qui a des extraits de code C# et JavaScript afin d’ajouter un client de télémétrie, des en-têtes de requête et des propriétés nécessaires pour des événements de journal personnalisés.

Important

La page du portail Rechercher l’analyse de trafic est actuellement obsolète et fait référence à une bibliothèque de client. La solution de contournement consiste à utiliser des extraits de code du référentiel GitHub azure-search-traffic-analytics. Cet article inclut des extraits de code du référentiel GitHub.

Étape 1 : Configurer Application Insights

Créez un objet qui envoie des événements à Application Insights. Vous pouvez ajouter l’instrumentation à votre code d’application côté serveur ou au code côté client s’exécutant dans un navigateur, exprimé ici sous forme de variantes C# et JavaScript. Pour les autres langages, consultez Plateformes et infrastructures prises en charge.

La télémétrie côté serveur capture les métriques au niveau de la couche application, par exemple dans les applications s’exécutant en tant que service web sur Azure ou en tant qu’application locale sur un réseau d’entreprise. La télémétrie côté serveur capture les événements de recherche et de clic, la position d’un document dans les résultats et les informations sur une requête, mais votre collecte de données est limitée aux informations disponibles au niveau de cette couche.

Sur le client, il peut exister un autre code qui manipule les entrées de requête, ajoute la navigation ou inclut le contexte (par exemple, les requêtes lancées à partir d’une page d’accueil par rapport à celles lancées depuis une page de produit). Si cela décrit votre solution, vous pouvez opter pour l’instrumentation côté client de sorte que vos données de télémétrie reflètent ces détails supplémentaires. La façon dont ces détails supplémentaires sont collectés sort du cadre de ce modèle, mais vous pouvez consulter Application Insights pour les pages web pour vous aider à prendre une décision à ce propos.

Lors de cette étape, fournissez une chaîne de connexion à Application Insights.

Un raccourci qui fonctionne pour certains types de projets Visual Studio est reflété dans les étapes suivantes.

Ouvrez votre solution dans Visual Studio.
Dans le menu Projet, sélectionnez Services connectés>Ajouter>Azure Application Insights.
Dans Se connecter à la dépendance, sélectionnez Azure Application Insights, puis Suivant.
Sélectionnez votre abonnement Azure, votre ressource Application Insights, puis Terminer.

À ce stade, votre application est configurée pour le monitoring d’application, ce qui signifie que tous les chargements de page dans votre application cliente sont suivis avec les métriques par défaut.

Si ce raccourci n’a pas fonctionné pour vous, consultez Activer la télémétrie côté serveur Application Insights ou consultez les extraits de code dans les onglets adjacent.

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

Étape 2 : Ajouter l’instrumentation

Ajoutez le code d’instrumentation à votre application cliente.

Mettre en corrélation les événements de clic avec les résultats de la recherche

Pour mettre en corrélation les requêtes de recherche avec les clics, il est nécessaire de disposer d’un ID de corrélation qui lie ces deux événements distincts. La recherche Azure AI vous fournit un ID de recherche avec un en-tête HTTP.

Le fait de disposer de l’ID de recherche permet d’établir une corrélation entre les métriques émises par la Recherche Azure AI pour la requête elle-même et les métriques personnalisées que vous journalisez dans 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);

Consigner des événements personnalisés

Chaque fois qu’une requête de recherche est émise par un utilisateur, vous devez la consigner en tant qu’événement de recherche avec le schéma suivant sur un événement personnalisé Application Insights. N’oubliez pas de consigner uniquement les requêtes de recherche générées par l’utilisateur.

SearchId : (guid) identificateur unique de la requête de recherche (intégré à la réponse de recherche)
SearchServiceName : (string) nom du service de recherche
IndexName : (string) index du service de recherche à interroger
SearchText : (chaîne) termes de recherche saisis par l’utilisateur
ResultCount : (int) nombre de documents qui ont été retournés (intégré dans la réponse de recherche)

Remarque

Demandez le nombre de requêtes générées par l’utilisateur en ajoutant $count=true à votre requête de recherche. Pour en savoir plus, consultez la section relative à la recherche de documents (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
};

Envoyer l’événement personnalisé à Application Insights

Ajoutez l’événement personnalisé à la table événements personnalisés dans Application Insights. Pour découvrir plus d’informations, consultez API Application Insights pour les événements et les métriques personnalisés.

.NET
JavaScript

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

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

Étape 3 : passer en revue les journaux

Utilisez l’une des approches prises en charge par Application Insights pour afficher les événements personnalisés.

Étapes suivantes

Des informations supplémentaires sur Application Insights sont disponibles. Vous pouvez également visiter la page des tarifs pour en savoir plus sur les différents niveaux de service.

Apprenez-en davantage sur la création de rapports. Pour plus d’informations, consultez Bien démarrer avec Power BI Desktop.

Partager via