Skip to content

Commit 5d51750

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #1119 from HeidiSteen/heidist-fresh
[azure search] Update search traffic analytics to use the repo snippets
2 parents afee2a2 + 65227d3 commit 5d51750

File tree

2 files changed

+128
-91
lines changed

2 files changed

+128
-91
lines changed

‎articles/search/media/search-traffic-analytics/azuresearch-trafficanalytics.png

28.3 KB
Loading

‎articles/search/search-traffic-analytics.md

Lines changed: 128 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -8,41 +8,64 @@ ms.author: heidist
88

99
ms.service: azure-ai-search
1010
ms.topic: how-to
11-
ms.date: 10/23/2024
11+
ms.date: 10/29/2024
1212
---
1313

1414
# Collect telemetry data for search traffic analytics
1515

16-
Search traffic analytics is a pattern for collecting telemetry about user interactions with your Azure AI Search application, such as user-initiated click events and keyboard inputs. Using this information, you can determine the effectiveness of your search solution, including clickthrough rate and which query inputs yield zero results.
16+
Search traffic analytics is a pattern for collecting telemetry about user interactions with your Azure AI Search application, such as user-initiated clickstream events and keyboard inputs. Using this information, you can determine the effectiveness of your search solution, including clickthrough rate and which query inputs yield zero results.
1717

18-
This pattern takes a dependency on [Application Insights](/azure/azure-monitor/app/app-insights-overview) (a feature of [Azure Monitor](/azure/azure-monitor/)) to collect user data. It requires that you add instrumentation to your client code, as described in this article. Finally, you need a reporting mechanism to analyze the data. We recommend Power BI, but you can use any visualization tool that connects to Application Insights.
18+
Instrumentation has the following parts:
19+
20+
+ Add a telemetry client
21+
+ Modify a search request to include a correlation Id that maps search results to user actions
22+
+ Create and send a custom event to Application Insights and use the visualization and reporting tools to view event data
23+
24+
This pattern takes a dependency on [Application Insights](/azure/azure-monitor/app/app-insights-overview) (a feature of [Azure Monitor](/azure/azure-monitor/)) to collect user data. It requires that you add instrumentation to your application code, as described in this article. Finally, you need a reporting mechanism to analyze the data. You can use any visualization tool that connects to Application Insights.
1925

2026
> [!NOTE]
2127
> The pattern described in this article is for advanced scenarios and clickstream data generated by code you add to your client. In contrast, service logs are easy to set up, provide a range of metrics including search terms, and can be done in the portal with no code required. We recommend that you enable logging for all scenarios. For more information, see [Collect and analyze log data](monitor-azure-cognitive-search.md).
2228
29+
## Prerequisites
30+
31+
+ [Azure AI Search](search-create-service-portal.md), any region, basic tier and above.
32+
33+
+ [Application Insights](/azure/azure-monitor/app/create-workspace-resource).
34+
35+
+ A rich client application providing an interactive search experience that includes clickstream events or other user actions that you want to correlate to search result selections.
36+
2337
## Identify relevant search data
2438

25-
To have useful metrics for search traffic analytics, it's necessary to log some signals from the users of your search application. These signals signify content that users are interested in and that they consider relevant. For search traffic analytics, these include:
39+
To collect useful metrics for search traffic analytics, it's necessary to log some signals from the users of your search application. These signals signify content that users are interested in and that they consider relevant. For search traffic analytics, these include:
2640

2741
+ User-generated search events: Only search queries initiated by a user are interesting. Other search requests, such as those used to populate facets or retrieve internal information, aren't important. Be sure to only instrument user-initiated events to avoid skew or bias in your results.
2842

29-
+ User-generated click events: On a search results page, a click event generally means that a document is a relevant result for a specific search query.
43+
+ User-generated clickstream events: On a search results page, a clickstream event generally means that a document is a relevant result for a specific search query.
3044

31-
By linking search and click events with a correlation ID, you can gain a deeper understanding of how well your application's search functionality is performing.
45+
In your application code, you should correlate these events with the search results returned from a given query. By linking search and clickstream events with a correlation ID, you can gain a deeper understanding of how well your application's search functionality is performing.
3246

3347
## Add search traffic analytics
3448

35-
In the [portal](https://portal.azure.com) page for your Azure AI Search service, open the Search Traffic Analytics page to access a cheat sheet for following this telemetry pattern. From this page, you can select or create an Application Insights resource, get the instrumentation key, copy snippets that you can adapt for your solution, and download a Power BI report that's built over the schema reflected in the pattern.
49+
For Azure AI Search, the Azure [portal](https://portal.azure.com) provides a Search Traffic Analytics page that has C# and JavaScript code snippets for adding a telemetry client, request headers, and properties necessary for custom log events.
50+
51+
> [!IMPORTANT]
52+
> The Search traffic analytics portal page is currently outdated and references an obsolete client libary. The workaround is to use code snippets from the [azure-search-traffic-analytics](https://github.com/Azure-Samples/azure-search-traffic-analytics) GitHub repository. This article includes code snippets from the GitHub repository.
3653
3754
:::image type="content" source="media/search-traffic-analytics/azuresearch-trafficanalytics.png" alt-text="Screenshot of the portal command and page for setting up Application Insights.":::
3855

3956
## Step 1: Set up Application Insights
4057

41-
Select an existing Application Insights resource or [create one](/previous-versions/azure/azure-monitor/app/create-new-resource) if you don't have one already.
58+
Create an object that sends events to Application Insights. You can add instrumentation to your server-side application code or client-side code running in a browser, expressed here as C# and JavaScript variants. For other languages, see [supported platforms and frameworks](/azure/azure-monitor/app/app-insights-overview#supported-languages).
4259

43-
A shortcut that works for some Visual Studio project types is reflected in the following steps.
60+
Server-side telemetry captures metrics at the application layer, for example in applications running as a web service on Azure, or as an on-premises app on a corporate network. Server-side telemetry captures search and clickstream events, the position of a document in results, and query information, but your data collection will be scoped to whatever information is available at that layer.
4461

45-
For illustration, these steps use the client from [Add search to a static web app](tutorial-csharp-overview.md).
62+
On the client, you might have other code that manipulates query inputs, adds navigation, or includes context (for example, queries initiated from a home page versus a product page). If this describes your solution, you might opt for client-side instrumentation so that your telemetry reflects the extra detail. How this extra detail is collected goes beyond the scope of this pattern, but you can review [Application Insights for web pages](/azure/azure-monitor/app/javascript#explore-browserclient-side-data) for help with that decision.
63+
64+
In this step, provide a [connection string to Application Insights](/azure/azure-monitor/app/migrate-from-instrumentation-keys-to-connection-strings).
65+
66+
### [**Visual Studio**](#tab/visual-studio-telemetry-client)
67+
68+
A shortcut that works for some Visual Studio project types is reflected in the following steps.
4669

4770
1. Open your solution in Visual Studio.
4871

@@ -54,132 +77,146 @@ For illustration, these steps use the client from [Add search to a static web ap
5477

5578
At this point, your application is set up for application monitoring, which means all page loads in your client app are tracked with default metrics.
5679

57-
If this shortcut didn't work for you, see [Enable Application Insights server-side telemetry](/azure/azure-monitor/app/asp-net-core#enable-application-insights-server-side-telemetry-visual-studio).
58-
59-
## Step 2: Add instrumentation
60-
61-
Add instrumentation code to your client application. The Search Traffic Analytics page in the Azure portal provides code snippets that you can paste into your application code.
80+
If this shortcut didn't work for you, see [Enable Application Insights server-side telemetry](/azure/azure-monitor/app/asp-net-core#enable-application-insights-server-side-telemetry-visual-studio) or refer to code snippets in the adjacent tabs.
6281

63-
### Create a telemetry client
82+
### [**.NET**](#tab/dotnet-telemetry-client)
6483

65-
Create an object that sends events to Application Insights. You can add instrumentation to your server-side application code or client-side code running in a browser, expressed here as C# and JavaScript variants. For other languages, see [supported platforms and frameworks](/azure/azure-monitor/app/app-insights-overview#supported-languages).
66-
67-
Server-side telemetry captures metrics at the application layer, for example in applications running as a web service on Azure, or as an on-premises app on a corporate network. Server-side telemetry captures search and click events, the position of a document in results, and query information, but your data collection will be scoped to whatever information is available at that layer.
84+
```csharp
85+
var telemetryConfiguration = new TelemetryConfiguration
86+
{
87+
ConnectionString = "<PUT YOUR CONNECTION STRING HERE>"
88+
};
89+
var telemetryClient = new TelemetryClient(telemetryConfiguration);
90+
```
6891

69-
On the client, you might have other code that manipulates query inputs, adds navigation, or includes context (for example, queries initiated from a home page versus a product page). If this describes your solution, you might opt for client-side instrumentation so that your telemetry reflects the extra detail. How this extra detail is collected goes beyond the scope of this pattern, but you can review [Application Insights for web pages](/azure/azure-monitor/app/javascript#explore-browserclient-side-data) for help with that decision.
92+
### [**JavaScript**](#tab/javascript-telemetry-client)
7093

71-
You can get the instrumentation key from Azure portal, either in the pages for Application Insights or in the Search traffic analytics page for Azure AI Search.
94+
```javascript
95+
const appInsights = new ApplicationInsights({ config: {
96+
connectionString: '<PUT YOUR CONNECTION STRING HERE>'
97+
/* ...Other Configuration Options... */
98+
} });
99+
appInsights.loadAppInsights();
100+
```
72101

73-
```csharp
74-
// Application Insights SDK: https://www.nuget.org/packages/Microsoft.ApplicationInsights.Web
102+
---
75103

76-
var telemetryClient = new TelemetryClient();
77-
telemetryClient.InstrumentationKey = "0000000000000000000000000000";
78-
```
104+
## Step 2: Add instrumentation
79105

80-
### Request a Search ID for correlation
106+
Add instrumentation code to your client application.
81107

82-
> [!IMPORTANT]
83-
> In the Azure portal, the snippets for request headers are made using an outdated version of the Azure SDK. Updates are pending.
108+
### Correlate clickstream events with search results
84109

85110
To correlate search requests with clicks, it's necessary to have a correlation ID that relates these two distinct events. Azure AI Search provides you with a search ID when you request it with an HTTP header.
86111

87112
Having the search ID allows correlation of the metrics emitted by Azure AI Search for the request itself, with the custom metrics you're logging in Application Insights.
88113

114+
### [**.NET**](#tab/dotnet-correlation)
115+
89116
```csharp
90-
var client = new SearchClient(<SEARCH SERVICE NAME>, <INDEX NAME>, new AzureDefaultCredentials())
91-
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
92-
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
93-
IEnumerable<string> headerValues;
94-
string searchId = string.Empty;
95-
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
96-
searchId = headerValues.FirstOrDefault();
97-
}
117+
var client = new SearchClient(new Uri("https://contoso.search.windows.net"), "hotels-sample-index", new DefaultAzureCredential());
118+
119+
// Generate a new correlation id for logs
120+
string searchId = Guid.NewGuid().ToString();
121+
string searchText = "*";
122+
SearchResults<SearchDocument> searchResults;
123+
124+
// Set correlation id for search request
125+
using (HttpPipeline.CreateClientRequestIdScope(clientRequestId: searchId))
126+
{
127+
searchResults = client.Search<SearchDocument>(searchText, options: new SearchOptions { IncludeTotalCount = true } );
128+
}
98129
```
99130

100-
### Log search events
131+
### [**JavaScript**](#tab/javascript-correlation)
132+
133+
```javascript
134+
const searchId = uuidv4();
135+
const searchText = "*";
136+
const searchResults = await searchClient.search(searchText, { includeTotalCount: true, customHeaders: { "x-ms-client-request-id": searchId }});
137+
const properties = {
138+
searchId: searchId,
139+
serviceName: "<PUT YOUR SEARCH SERVICE NAME HERE, example contoso-search>",
140+
indexName: "<PUT YOUR INDEX NAME HERE>",
141+
searchText: searchText,
142+
resultsCount: searchResults.count
143+
};
144+
appInsights.trackEvent({ name: "search" }, properties);
145+
```
101146

102-
Every time that a search request is issued by a user, you should log that as a search event with the following schema on an Application Insights custom event. Remember to log only user-generated search queries.
147+
---
103148

149+
### Log custom events
150+
151+
Every time that a search request is issued by a user, you should log that as a search event with the following schema on an [Application Insights custom event](/azure/azure-monitor/app/api-custom-events-metrics). Remember to log only user-generated search queries.
152+
153+
+ **SearchId**: (guid) unique identifier of the search query (built into the search response)
104154
+ **SearchServiceName**: (string) search service name
105-
+ **SearchId**: (guid) unique identifier of the search query (comes in the search response)
106155
+ **IndexName**: (string) search service index to be queried
107-
+ **QueryTerms**: (string) search terms entered by the user
108-
+ **ResultCount**: (int) number of documents that were returned (comes in the search response)
109-
+ **ScoringProfile**: (string) name of the scoring profile used, if any
156+
+ **SearchText**: (string) search terms entered by the user
157+
+ **ResultCount**: (int) number of documents that were returned (built into the search response)
110158

111159
> [!NOTE]
112-
> Request the count of user generated queries by adding $count=true to your search query. For more information, see [Search Documents (REST)](/rest/api/searchservice/documents/search-post#searchrequest).
160+
> Request the count of user generated queries by adding `$count=true` to your search query. For more information, see [Search Documents (REST)](/rest/api/searchservice/documents/search-post#searchrequest).
113161
>
114162
163+
### [**.NET**](#tab/dotnet-properties)
164+
115165
```csharp
116-
var properties = new Dictionary <string, string> {
117-
{"SearchServiceName", <SEARCH SERVICE NAME>},
118-
{"SearchId", <SEARCH ID>},
119-
{"IndexName", <INDEX NAME>},
120-
{"QueryTerms", <SEARCH TERMS>},
121-
{"ResultCount", <RESULTS COUNT>},
122-
{"ScoringProfile", <SCORING PROFILE USED>}
166+
// Create properties for telemetry
167+
var properties = new Dictionary<string, string>
168+
{
169+
["searchId"] = searchId,
170+
["serviceName"] = "<PUT YOUR SEARCH SERVICE NAME HERE, example: contoso-search>",
171+
["indexName"] = "<PUT YOUR INDEX NAME HERE>",
172+
["searchText"] = searchText,
173+
["resultsCount"] = searchResults.TotalCount?.ToString()
123174
};
124-
125-
telemetryClient.TrackEvent("Search", properties);
126175
```
127176

128-
### Log click events
129-
130-
Every time that a user clicks on a document, that's a signal that must be logged for search analysis purposes. Use Application Insights custom events to log these events with the following schema:
131-
132-
+ **ServiceName**: (string) search service name
133-
+ **SearchId**: (guid) unique identifier of the related search query
134-
+ **DocId**: (string) document identifier
135-
+ **Position**: (int) rank of the document in the search results page
177+
### [**JavaScript**](#tab/javascript-properties)
136178

137-
> [!NOTE]
138-
> Position refers to the cardinal order in your application. You are free to set this number, as long as it's always the same, to allow for comparison.
139-
>
140-
141-
```csharp
142-
var properties = new Dictionary <string, string> {
143-
{"SearchServiceName", <SEARCH SERVICE NAME>},
144-
{"SearchId", <SEARCH ID>},
145-
{"ClickedDocId", <CLICKED DOCUMENT ID>},
146-
{"Rank", <CLICKED DOCUMENT POSITION>}
179+
```javascript
180+
const properties = {
181+
searchId: searchId,
182+
serviceName: "<PUT YOUR SEARCH SERVICE NAME HERE, example contoso-search>",
183+
indexName: "<PUT YOUR INDEX NAME HERE>",
184+
searchText: searchText,
185+
resultsCount: searchResults.count
147186
};
148-
149-
telemetryClient.TrackEvent("Click", properties);
150187
```
151188

152-
## Step 3: Analyze in Power BI
153-
154-
After you have instrumented your app and verified your application is correctly connected to Application Insights, you download a predefined report template to analyze data in Power BI desktop. The report contains predefined charts and tables useful for analyzing the extra data captured for search traffic analytics.
155-
156-
1. In the Azure portal on the search service pages, under **Settings**, select **Search traffic analytics**.
189+
---
157190

158-
1. Select **Get Power BI Desktop** to install Power BI.
191+
### Send the custom event to Application Insights
159192

160-
1. Select **Download Power BI report** to get the report.
193+
Add the custom even to the *custom events* table in Application Insights. For more information, see [Application Insights API for custom events and metrics](/azure/azure-monitor/app/api-custom-events-metrics).
161194

162-
1. The report opens in Power BI Desktop, and you're prompted to connect to Application Insights and provide credentials. You can find connection information in the Azure portal pages for your Application Insights resource. For credentials, provide the same user name and password that you use for portal sign-in.
195+
### [**.NET**](#tab/dotnet-custom-events)
163196

164-
:::image type="content" source="media/search-traffic-analytics/connect-to-app-insights.png" alt-text="Screenshot showing how to connect to Application Insights from Power BI.":::
197+
```csharp
198+
telemetryClient.TrackEvent("search", properties);
199+
telemetryClient.Flush();
200+
```
165201

166-
1. Select **Load**.
202+
### [**JavaScript**](#tab/javascript-custom-events)
167203

168-
The report contains charts and tables that help you make more informed decisions to improve your search performance and relevance.
204+
```javascript
205+
appInsights.trackEvent({ name: "search" }, properties);
206+
```
169207

170-
Metrics included the following items:
208+
---
171209

172-
+ Search volume and most popular term-document pairs: terms that result in the same document clicked, ordered by clicks.
173-
+ Searches without clicks: terms for top queries that register no clicks
210+
## Step 3: Review logs
174211

175-
The following screenshot shows the data elements that your report might contain.
212+
Use any of the approaches supported by Application Insights for viewing custom events.
176213

177-
:::image type="content" source="media/search-traffic-analytics/azuresearch-powerbi-dashboard.png" alt-text="Screenshot showing the available schema elements in the data catalog. ":::
214+
+ [Create or edit an Azure Workbook](/azure/azure-monitor/visualize/workbooks-create-workbook)
215+
+ [Create and share dashboards of Log Analytics data](/azure/azure-monitor/visualize/tutorial-logs-dashboards)
216+
+ [Integrate Log Analytics with Power BI](/azure/azure-monitor/logs/log-powerbi)
178217

179218
## Next steps
180219

181-
Instrument your search application to get powerful and insightful data about your search service.
182-
183220
You can find more information on [Application Insights](/azure/azure-monitor/app/app-insights-overview) and visit the [pricing page](https://azure.microsoft.com/pricing/details/application-insights/) to learn more about their different service tiers.
184221

185222
Learn more about creating reports. See [Getting started with Power BI Desktop](/power-bi/fundamentals/desktop-getting-started) for details.

0 commit comments

Comments
 (0)