Samla in telemetridata för söktrafikanalys

Söktrafikanalys är ett mönster för att samla in telemetri om användarinteraktioner med ditt Azure Cognitive Search program, till exempel användarinitierade klickhändelser och tangentbordsindata. Med hjälp av den här informationen kan du fastställa effektiviteten för din söklösning, inklusive populära söktermer, klickfrekvens och vilka frågeindata som ger noll resultat.

Det här mönstret är beroende av Application Insights (en funktion i Azure Monitor) för att samla in användardata. Du måste lägga till instrumentation i klientkoden enligt beskrivningen i den här artikeln. Slutligen behöver du en rapporteringsmekanism för att analysera data. Vi rekommenderar Power BI, men du kan använda programinstrumentpanelen eller alla verktyg som ansluter till Application Insights.

Anteckning

Mönstret som beskrivs i den här artikeln är för avancerade scenarier och clickstream-data som genereras av kod som du lägger till i klienten. Tjänstloggar är däremot enkla att konfigurera, tillhandahålla ett antal mått och kan göras i portalen utan någon kod som krävs. Aktivering av loggning rekommenderas för alla scenarier. Mer information finns i Samla in och analysera loggdata.

Identifiera relevanta sökdata

Om du vill ha användbara mått för söktrafikanalys är det nödvändigt att logga några signaler från användarna av sökprogrammet. Dessa signaler betyder innehåll som användarna är intresserade av och som de anser relevanta. För analys av söktrafik omfattar följande:

  • Användargenererade sökhändelser: Endast sökfrågor som initieras av en användare är intressanta. Andra sökbegäranden, till exempel de som används för att fylla i faser eller hämta intern information, är inte viktiga. Se till att endast instrumentera användarinitierade händelser för att undvika skevhet eller bias i dina resultat.

  • Användargenererade klickhändelser: På en sökresultatsida innebär en klickhändelse vanligtvis att ett dokument är ett relevant resultat för en specifik sökfråga.

Genom att länka sök- och klickhändelser med ett korrelations-ID får du en djupare förståelse för hur väl programmets sökfunktion fungerar.

Lägga till trafikanalys för sökning

portalsidan för din Azure Cognitive Search-tjänst öppnar du sidan Sök trafikanalys för att få åtkomst till ett fuskblad för att följa det här telemetrimönstret. På den här sidan kan du välja eller skapa en Application Insights-resurs, hämta instrumentationsnyckeln, kopiera kodfragment som du kan anpassa för din lösning och ladda ned en Power BI-rapport som är byggd över schemat som återspeglas i mönstret.

Sök på sidan Trafikanalys i portalen

1 – Konfigurera Application Insights

Välj en befintlig Application Insights-resurs eller skapa en om du inte redan har en. Om du använder sidan Sök trafikanalys kan du kopiera instrumentationsnyckeln som programmet behöver för att ansluta till Application Insights.

När du har en Application Insights-resurs kan du följa anvisningarna för språk och plattformar som stöds för att registrera din app. Registreringen lägger helt enkelt till instrumentationsnyckeln från Application Insights i koden, som konfigurerar associationen. Du hittar nyckeln i portalen eller på sidan Sök trafikanalys när du väljer en befintlig resurs.

En genväg som fungerar för vissa Visual Studio-projekttyper återspeglas i följande steg. Den skapar en resurs och registrerar din app med bara några få klick.

  1. För Visual Studio och ASP.NET utveckling öppnar du din lösning och väljer ProjectAdd Application Insights Telemetry (Project > Add Application Insights Telemetry).

  2. Klicka på Kom igång.

  3. Registrera din app genom att ange ett Microsoft konto, Azure-prenumeration och en Application Insights-resurs (en ny resurs är standard). Klicka på Registrera.

Nu är ditt program konfigurerat för programövervakning, vilket innebär att alla sidinläsningar spåras med standardmått. Mer information om föregående steg finns i Aktivera Application Insights-telemetri på serversidan.

2 – Lägg till instrumentation

I det här steget instrumenteras ditt eget sökprogram med hjälp av Application Insights-resursen som du skapade i steget ovan. Det finns fyra steg i den här processen, som börjar med att skapa en telemetriklient.

Steg 1: Skapa en telemetriklient

Skapa ett objekt som skickar händelser till Application Insights. Du kan lägga till instrumentation i programkoden på serversidan eller kod på klientsidan som körs i en webbläsare, uttryckt här som C# och JavaScript-varianter (för andra språk finns en fullständig lista över plattformar och ramverk som stöds. Välj den metod som ger dig önskat informationsdjup.

Telemetri på serversidan samlar in mått på programnivån, till exempel i program som körs som en webbtjänst i molnet eller som en lokal app i ett företagsnätverk. Telemetri på serversidan samlar in sök- och klickhändelser, positionen för ett dokument i resultat och frågeinformation, men datainsamlingen begränsas till den information som är tillgänglig på det lagret.

På klienten kan du ha ytterligare kod som manipulerar frågeindata, lägger till navigering eller innehåller kontext (till exempel frågor som initierats från en startsida jämfört med en produktsida). Om det här beskriver din lösning kan du välja instrumentation på klientsidan så att telemetrin återspeglar den ytterligare informationen. Hur den här ytterligare informationen samlas in går utöver det här mönstrets omfattning, men du kan granska Application Insights för webbsidor för mer vägledning.

Använda C#

För C# ska InstrumentationKey definieras i programkonfigurationen, till exempel appsettings.json om projektet är ASP.NET. Gå tillbaka till registreringsanvisningarna om du är osäker på nyckelplatsen.

private static TelemetryClient _telemetryClient;

// Add a constructor that accepts a telemetry client:
public HomeController(TelemetryClient telemetry)
{
    _telemetryClient = telemetry;
}

Använda JavaScript

Det aktuella kodfragmentet (som anges nedan) är version "5", versionen kodas i kodfragmentet som sv:"#" och den aktuella versionen är också tillgänglig på GitHub.

<script type="text/javascript">
!function(T,l,y){var S=T.location,k="script",D="instrumentationKey",C="ingestionendpoint",I="disableExceptionTracking",E="ai.device.",b="toLowerCase",w="crossOrigin",N="POST",e="appInsightsSDK",t=y.name||"appInsights";(y.name||T[e])&&(T[e]=t);var n=T[t]||function(d){var g=!1,f=!1,m={initialize:!0,queue:[],sv:"5",version:2,config:d};function v(e,t){var n={},a="Browser";return n[E+"id"]=a[b](),n[E+"type"]=a,n["ai.operation.name"]=S&&S.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(m.sv||m.version),{time:function(){var e=new Date;function t(e){var t=""+e;return 1===t.length&&(t="0"+t),t}return e.getUTCFullYear()+"-"+t(1+e.getUTCMonth())+"-"+t(e.getUTCDate())+"T"+t(e.getUTCHours())+":"+t(e.getUTCMinutes())+":"+t(e.getUTCSeconds())+"."+((e.getUTCMilliseconds()/1e3).toFixed(3)+"").slice(2,5)+"Z"}(),iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}}}}var h=d.url||y.src;if(h){function a(e){var t,n,a,i,r,o,s,c,u,p,l;g=!0,m.queue=[],f||(f=!0,t=h,s=function(){var e={},t=d.connectionString;if(t)for(var n=t.split(";"),a=0;a<n.length;a++){var i=n[a].split("=");2===i.length&&(e[i[0][b]()]=i[1])}if(!e[C]){var r=e.endpointsuffix,o=r?e.location:null;e[C]="https://"+(o?o+".":"")+"dc."+(r||"services.visualstudio.com")}return e}(),c=s[D]||d[D]||"",u=s[C],p=u?u+"/v2/track":d.endpointUrl,(l=[]).push((n="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",a=t,i=p,(o=(r=v(c,"Exception")).data).baseType="ExceptionData",o.baseData.exceptions=[{typeName:"SDKLoadFailed",message:n.replace(/\./g,"-"),hasFullStack:!1,stack:n+"\nSnippet failed to load ["+a+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(S&&S.pathname||"_unknown_")+"\nEndpoint: "+i,parsedStack:[]}],r)),l.push(function(e,t,n,a){var i=v(c,"Message"),r=i.data;r.baseType="MessageData";var o=r.baseData;return o.message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+n+")").replace(/\"/g,"")+'"',o.properties={endpoint:a},i}(0,0,t,p)),function(e,t){if(JSON){var n=T.fetch;if(n&&!y.useXhr)n(t,{method:N,body:JSON.stringify(e),mode:"cors"});else if(XMLHttpRequest){var a=new XMLHttpRequest;a.open(N,t),a.setRequestHeader("Content-type","application/json"),a.send(JSON.stringify(e))}}}(l,p))}function i(e,t){f||setTimeout(function(){!t&&m.core||a()},500)}var e=function(){var n=l.createElement(k);n.src=h;var e=y[w];return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=i,n.onerror=a,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||i(0,t)},n}();y.ld<0?l.getElementsByTagName("head")[0].appendChild(e):setTimeout(function(){l.getElementsByTagName(k)[0].parentNode.appendChild(e)},y.ld||0)}try{m.cookie=l.cookie}catch(p){}function t(e){for(;e.length;)!function(t){m[t]=function(){var e=arguments;g||m.queue.push(function(){m[t].apply(m,e)})}}(e.pop())}var n="track",r="TrackPage",o="TrackEvent";t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+r,"stop"+r,"start"+o,"stop"+o,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),m.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4};var s=(d.extensionConfig||{}).ApplicationInsightsAnalytics||{};if(!0!==d[I]&&!0!==s[I]){var c="onerror";t(["_"+c]);var u=T[c];T[c]=function(e,t,n,a,i){var r=u&&u(e,t,n,a,i);return!0!==r&&m["_"+c]({message:e,url:t,lineNumber:n,columnNumber:a,error:i}),r},d.autoExceptionInstrumented=!0}return m}(y.cfg);function a(){y.onInit&&y.onInit(n)}(T[t]=n).queue&&0===n.queue.length?(n.queue.push(a),n.trackPageView({})):a()}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
// name: "appInsights", // Global SDK Instance name defaults to "appInsights" when not supplied
// ld: 0, // Defines the load delay (in ms) before attempting to load the sdk. -1 = block page load and add to head. (default) = 0ms load after timeout,
// useXhr: 1, // Use XHR instead of fetch to report failures (if available),
crossOrigin: "anonymous", // When supplied this will add the provided value as the cross origin attribute on the script tag
// onInit: null, // Once the application insights instance has loaded and initialized this callback function will be called with 1 argument -- the sdk instance (DO NOT ADD anything to the sdk.queue -- As they won't get called)
cfg: { // Application Insights Configuration
    instrumentationKey: "<YOUR INSTRUMENTATION KEY>"
}});
</script>

Anteckning

För läsbarhet och för att minska möjliga JavaScript-fel visas alla möjliga konfigurationsalternativ på en ny rad i kodfragmentkoden ovan, om du inte vill ändra värdet för en kommenterad rad kan den tas bort.

Steg 2: Begär ett sök-ID för korrelation

Om du vill korrelera sökbegäranden med klick måste du ha ett korrelations-ID som relaterar dessa två distinkta händelser. Azure Cognitive Search ger dig ett sök-ID när du begär det med ett HTTP-huvud.

Om du har sök-ID:t kan du korrelation mellan de mått som genereras av Azure Cognitive Search för själva begäran, med de anpassade mått som du loggar i Application Insights.

Använda C# (nyare v11 SDK)

Den senaste SDK:t kräver att en Http-pipeline används för att ange rubriken enligt beskrivningen i det här exemplet.

// Create a custom policy to add the correct headers
public class SearchIdPipelinePolicy : HttpPipelineSynchronousPolicy
{
    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Headers.SetValue("x-ms-azs-return-searchid", "true");
    }
}
// This sample uses the .NET SDK https://www.nuget.org/packages/Azure.Search.Documents

SearchClientOptions clientOptions = new SearchClientOptions();
clientOptions.AddPolicy(new SearchIdPipelinePolicy(), HttpPipelinePosition.PerCall);

var client = new SearchClient("<SearchServiceName>", "<IndexName>", new AzureKeyCredential("<QueryKey>"), options: clientOptions);

Response<SearchResults<SearchDocument>> response = await client.SearchAsync<SearchDocument>(searchText: searchText, searchOptions: options);
string searchId = string.Empty;
if (response.GetRawResponse().Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues))
{
    searchId = headerValues.FirstOrDefault();
}

Använda C# (äldre v10 SDK)

// This sample uses the .NET SDK https://www.nuget.org/packages/Microsoft.Azure.Search

var client = new SearchIndexClient(<SearchServiceName>, <IndexName>, new SearchCredentials(<QueryKey>));

// Use HTTP headers so that you can get the search ID from the response
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
string searchId = string.Empty;
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues))
{
    searchId = headerValues.FirstOrDefault();
}

Använda JavaScript (anropa REST-API:er)

request.setRequestHeader("x-ms-azs-return-searchid", "true");
request.setRequestHeader("Access-Control-Expose-Headers", "x-ms-azs-searchid");
var searchId = request.getResponseHeader('x-ms-azs-searchid');

Steg 3: Loggsökningshändelser

Varje gång en sökbegäran utfärdas av en användare bör du logga den som en sökhändelse med följande schema på en anpassad Application Insights-händelse. Kom ihåg att endast logga användargenererade sökfrågor.

  • SearchServiceName: (sträng) söktjänstnamn
  • SearchId: (guid) unik identifierare för sökfrågan (finns i söksvaret)
  • IndexName: (sträng) söktjänstindex som ska frågas
  • QueryTerms: (sträng) söktermer som angetts av användaren
  • ResultCount: (int) antal dokument som returnerades (kommer i söksvaret)
  • ScoringProfile: (sträng) namn på den bedömningsprofil som används, om någon

Anteckning

Begär antalet användargenererade frågor genom att lägga till $count=true i sökfrågan. Mer information finns i Sök dokument (REST).

Använda C#

var properties = new Dictionary <string, string> 
{
    {"SearchServiceName", <service name>},
    {"SearchId", <search Id>},
    {"IndexName", <index name>},
    {"QueryTerms", <search terms>},
    {"ResultCount", <results count>},
    {"ScoringProfile", <scoring profile used>}
};
_telemetryClient.TrackEvent("Search", properties);

Använda JavaScript

appInsights.trackEvent("Search", {
  SearchServiceName: <service name>,
  SearchId: <search id>,
  IndexName: <index name>,
  QueryTerms: <search terms>,
  ResultCount: <results count>,
  ScoringProfile: <scoring profile used>
});

Steg 4: Logga klicka på händelser

Varje gång en användare klickar på ett dokument är det en signal som måste loggas i sökanalyssyfte. Använd anpassade Application Insights-händelser för att logga dessa händelser med följande schema:

  • ServiceName: (sträng) söktjänstnamn
  • SearchId: (guid) unik identifierare för den relaterade sökfrågan
  • DocId: (sträng) dokumentidentifierare
  • Position: (int) rangordning för dokumentet på sökresultatsidan

Anteckning

Position refererar till kardinalordningen i ditt program. Du kan ange det här talet, så länge det alltid är samma, för att tillåta jämförelse.

Använda C#

var properties = new Dictionary <string, string> 
{
    {"SearchServiceName", <service name>},
    {"SearchId", <search id>},
    {"ClickedDocId", <clicked document id>},
    {"Rank", <clicked document position>}
};
_telemetryClient.TrackEvent("Click", properties);

Använda JavaScript

appInsights.trackEvent("Click", {
    SearchServiceName: <service name>,
    SearchId: <search id>,
    ClickedDocId: <clicked document id>,
    Rank: <clicked document position>
});

3 – Analysera i Power BI

När du har instrumenterat appen och verifierat att programmet är korrekt anslutet till Application Insights laddar du ned en fördefinierad rapportmall för att analysera data i Power BI Desktop. Rapporten innehåller fördefinierade diagram och tabeller som är användbara för att analysera ytterligare data som samlas in för analys av söktrafik.

  1. I det vänstra navigeringsfönstret för Azure Cognitive Search instrumentpanel klickar du på Sök trafikanalys under Inställningar.

  2. På sidan Sök trafikanalys i steg 3 klickar du på Hämta Power BI Desktop för att installera Power BI.

    Hämta Power BI-rapporter

  3. På samma sida klickar du på Ladda ned Power BI-rapport.

  4. Rapporten öppnas i Power BI Desktop och du uppmanas att ansluta till Application Insights och ange autentiseringsuppgifter. Du hittar anslutningsinformation på Azure-Portal sidor för Application Insights-resursen. Ange samma användarnamn och lösenord som du använder för portalinloggning för autentiseringsuppgifter.

    Ansluta till Application Insights

  5. Klicka på Läs in.

Rapporten innehåller diagram och tabeller som hjälper dig att fatta mer välgrundade beslut för att förbättra sökprestanda och relevans.

Måtten innehöll följande:

  • Sökvolym och populäraste termdokumentpar: termer som resulterar i att samma dokument klickas, sorteras efter klick.
  • Söker utan klick: villkor för de vanligaste frågorna som registrerar inga klick

Följande skärmbild visar hur en inbyggd rapport kan se ut om du har använt alla schemaelement.

Power BI-instrumentpanel för Azure Cognitive Search

Nästa steg

Instrumentera sökprogrammet för att få kraftfulla och insiktsfulla data om din söktjänst.

Mer information om Application Insights finns på prissättningssidan om du vill veta mer om deras olika tjänstnivåer.

Mer informasjon om att skapa fantastiska rapporter. Mer information finns i Komma igång med Power BI Desktop.