Skip to content

Commit 460b92d

Browse files
HeidiSteenHeidiSteen
committed
Formatting
1 parent 7678799 commit 460b92d

File tree

1 file changed

+110
-144
lines changed

1 file changed

+110
-144
lines changed

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

Lines changed: 110 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -41,233 +41,199 @@ In the [portal](https://portal.azure.com) page for your Azure Cognitive Search s
4141

4242
![Search Traffic Analytics page in the portal](media/search-traffic-analytics/azuresearch-trafficanalytics.png "Search Traffic Analytics page in the portal")
4343

44-
## 1 - Select a resource
44+
## 1 - Set up Application Insights
4545

4646
Select an existing Application Insights resource or [create one](https://docs.microsoft.com/azure/azure-monitor/app/create-new-resource) if you don't have one already.
4747

48-
After you create the resource on Azure, [add Application Insights](https://docs.microsoft.com/azure/azure-monitor/app/platforms) to your code.
48+
For various IDEs and languages, you can follow [instructions for adding Application Insights](https://docs.microsoft.com/azure/azure-monitor/app/platforms) to your code.
4949

50-
You need the instrumentation key for creating the telemetry client for your application. You can find it in the portal, or from the Search Traffic Analytics page when you select an existing resource.
50+
You'll need the instrumentation key for creating the telemetry client for your application, which you can find it in the portal, or from the Search Traffic Analytics page when you select an existing resource.
5151

52-
## 2 - Add instrumentation
52+
1. For Visual Studio and ASP.NET development, open your solution and select **Project** > **Add Application Insights Telemetry**.
5353

54-
This step is where you instrument your own search application, using the Application Insights resource your created in the step above. There are four steps to this process:
54+
1. Click **Get Started**.
5555

56-
**Step 1: Create a telemetry client**
56+
1. Register your app by providing a Microsoft account, Azure subscription, and an Application Insights resource (new is the default). Click **Register**.
5757

58-
Create an object that sends events to Application Insights.
58+
At this point, your application is set up for application monitoring, which means all page loads are tracked with default metrics. For more information about the previous steps, see [Enable Application Insights server-side telemetry](https://docs.microsoft.com/azure/azure-monitor/app/asp-net-core#enable-application-insights-server-side-telemetry-visual-studio).
5959

60-
*C#*
60+
## 2 - Add instrumentation
6161

62-
private TelemetryClient telemetryClient = new TelemetryClient();
63-
telemetryClient.InstrumentationKey = "<YOUR INSTRUMENTATION KEY>";
62+
This step is where you instrument your own search application, using the Application Insights resource your created in the step above. There are four steps to this process, starting with creating a telemetry client.
6463

65-
*JavaScript*
64+
### Step 1: Create a telemetry client
6665

67-
<script type="text/javascript">var appInsights=window.appInsights||function(config){function r(config){t[config]=function(){var i=arguments;t.queue.push(function(){t[config].apply(t,i)})}}var t={config:config},u=document,e=window,o="script",s=u.createElement(o),i,f;s.src=config.url||"//az416426.vo.msecnd.net/scripts/a/ai.0.js";u.getElementsByTagName(o)[0].parentNode.appendChild(s);try{t.cookie=u.cookie}catch(h){}for(t.queue=[],i=["Event","Exception","Metric","PageView","Trace","Dependency"];i.length;)r("track"+i.pop());return r("setAuthenticatedUserContext"),r("clearAuthenticatedUserContext"),config.disableExceptionTracking||(i="onerror",r("_"+i),f=e[i],e[i]=function(config,r,u,e,o){var s=f&&f(config,r,u,e,o);return s!==!0&&t["_"+i](config,r,u,e,o),s}),t}
68-
({
69-
instrumentationKey: "<YOUR INSTRUMENTATION KEY>"
70-
});
71-
window.appInsights=appInsights;
72-
</script>
66+
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 the complete list of [supported platforms and frameworks](https://docs.microsoft.com/azure/application-insights/app-insights-platforms). Choose the approach that gives you the desired depth of information.
7367

74-
For other languages, see the complete list of [supported platforms and frameworks](https://docs.microsoft.com/azure/application-insights/app-insights-platforms).
68+
Server-side telemetry captures metrics at the application layer, for example in applications running as a web service in the cloud, 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.
7569

76-
**Step 2: Request a Search ID for correlation**
70+
On the client, you might have additional 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 additional detail.
7771

78-
To correlate search requests with clicks, it's necessary to have a correlation ID that relates these two distinct events. Azure Cognitive Search provides you with a Search ID when you request it with a header:
72+
**Using C#**
7973

80-
*C#*
74+
Depending on the approach used to register your app, the **InstrumentationKey** is in appsettings.json if your project is ASP.NET. Refer back to the registration instruction if you want to double-check the key location.
8175

82-
// This sample uses the .NET SDK https://www.nuget.org/packages/Microsoft.Azure.Search
76+
```csharp
77+
private static TelemetryClient _telemetryClient;
8378

84-
var client = new SearchIndexClient(<SearchServiceName>, <IndexName>, new SearchCredentials(<QueryKey>)
85-
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
86-
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
87-
IEnumerable<string> headerValues;
88-
string searchId = string.Empty;
89-
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
90-
searchId = headerValues.FirstOrDefault();
79+
// Add a constructor that accepts a telemetry client:
80+
public HomeController(TelemetryClient telemetry)
81+
{
82+
_telemetryClient = telemetry;
9183
}
84+
```
85+
86+
**Using JavaScript**
87+
88+
```javascript
89+
<script type="text/javascript">var appInsights=window.appInsights||function(config){function r(config){t[config]=function(){var i=arguments;t.queue.push(function(){t[config].apply(t,i)})}}var t={config:config},u=document,e=window,o="script",s=u.createElement(o),i,f;s.src=config.url||"//az416426.vo.msecnd.net/scripts/a/ai.0.js";u.getElementsByTagName(o)[0].parentNode.appendChild(s);try{t.cookie=u.cookie}catch(h){}for(t.queue=[],i=["Event","Exception","Metric","PageView","Trace","Dependency"];i.length;)r("track"+i.pop());return r("setAuthenticatedUserContext"),r("clearAuthenticatedUserContext"),config.disableExceptionTracking||(i="onerror",r("_"+i),f=e[i],e[i]=function(config,r,u,e,o){var s=f&&f(config,r,u,e,o);return s!==!0&&t["_"+i](config,r,u,e,o),s}),t}
90+
({
91+
instrumentationKey: "<YOUR INSTRUMENTATION KEY>"
92+
});
93+
window.appInsights=appInsights;
94+
</script>
95+
```
96+
97+
### Step 2: Request a Search ID for correlation
98+
99+
To correlate search requests with clicks, it's necessary to have a correlation ID that relates these two distinct events. Azure Cognitive Search provides you with a Search ID when you request it with a header.
100+
101+
Having the search ID allows correlation of the metrics emitted by Azure Cognitive Search for the actual search request, with the custom metrics you are logging in Application Insights.
102+
103+
**Using C#**
92104

93-
*JavaScript (calling REST APIs)*
105+
```csharp
106+
// This sample uses the .NET SDK https://www.nuget.org/packages/Microsoft.Azure.Search
94107
95-
request.setRequestHeader("x-ms-azs-return-searchid", "true");
96-
request.setRequestHeader("Access-Control-Expose-Headers", "x-ms-azs-searchid");
97-
var searchId = request.getResponseHeader('x-ms-azs-searchid');
108+
var client = new SearchIndexClient(<SearchServiceName>, <IndexName>, new SearchCredentials(<QueryKey>)
109+
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
110+
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
111+
IEnumerable<string> headerValues;
112+
string searchId = string.Empty;
113+
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
114+
searchId = headerValues.FirstOrDefault();
115+
}
116+
```
98117

99-
**Step 3: Log Search events**
118+
**Using JavaScript (calling REST APIs)**
119+
120+
```javascript
121+
request.setRequestHeader("x-ms-azs-return-searchid", "true");
122+
request.setRequestHeader("Access-Control-Expose-Headers", "x-ms-azs-searchid");
123+
var searchId = request.getResponseHeader('x-ms-azs-searchid');
124+
```
125+
126+
### Step 3: Log Search events
100127

101128
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.
102129

103-
**SearchServiceName**: (string) search service name
104-
**SearchId**: (guid) unique identifier of the search query (comes in the search response)
105-
**IndexName**: (string) search service index to be queried
106-
**QueryTerms**: (string) search terms entered by the user
107-
**ResultCount**: (int) number of documents that were returned (comes in the search response)
108-
**ScoringProfile**: (string) name of the scoring profile used, if any
130+
+ **SearchServiceName**: (string) search service name
131+
+ **SearchId**: (guid) unique identifier of the search query (comes in the search response)
132+
+ **IndexName**: (string) search service index to be queried
133+
+ **QueryTerms**: (string) search terms entered by the user
134+
+ **ResultCount**: (int) number of documents that were returned (comes in the search response)
135+
+ **ScoringProfile**: (string) name of the scoring profile used, if any
109136

110137
> [!NOTE]
111138
> 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/search-documents#counttrue--false).
112139
>
113140

114-
*C#*
141+
**Using C#**
115142

116-
var properties = new Dictionary <string, string> {
143+
```csharp
144+
var properties = new Dictionary <string, string> {
117145
{"SearchServiceName", <service name>},
118146
{"SearchId", <search Id>},
119147
{"IndexName", <index name>},
120148
{"QueryTerms", <search terms>},
121149
{"ResultCount", <results count>},
122150
{"ScoringProfile", <scoring profile used>}
123151
};
124-
_telemetryClient.TrackEvent("Search", properties);
152+
_telemetryClient.TrackEvent("Search", properties);
153+
```
125154

126-
*JavaScript*
155+
**Using JavaScript**
127156

128-
appInsights.trackEvent("Search", {
129-
SearchServiceName: <service name>,
130-
SearchId: <search id>,
131-
IndexName: <index name>,
132-
QueryTerms: <search terms>,
133-
ResultCount: <results count>,
134-
ScoringProfile: <scoring profile used>
135-
});
157+
```javascript
158+
appInsights.trackEvent("Search", {
159+
SearchServiceName: <service name>,
160+
SearchId: <search id>,
161+
IndexName: <index name>,
162+
QueryTerms: <search terms>,
163+
ResultCount: <results count>,
164+
ScoringProfile: <scoring profile used>
165+
});
166+
```
136167

137-
**Step 4: Log Click events**
168+
### Step 4: Log Click events
138169

139170
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:
140171

141-
**ServiceName**: (string) search service name
142-
**SearchId**: (guid) unique identifier of the related search query
143-
**DocId**: (string) document identifier
144-
**Position**: (int) rank of the document in the search results page
172+
+ **ServiceName**: (string) search service name
173+
+ **SearchId**: (guid) unique identifier of the related search query
174+
+ **DocId**: (string) document identifier
175+
+ **Position**: (int) rank of the document in the search results page
145176

146177
> [!NOTE]
147178
> 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.
148179
>
149180

150-
*C#*
181+
**Using C#**
151182

152-
var properties = new Dictionary <string, string> {
183+
```csharp
184+
var properties = new Dictionary <string, string> {
153185
{"SearchServiceName", <service name>},
154186
{"SearchId", <search id>},
155187
{"ClickedDocId", <clicked document id>},
156188
{"Rank", <clicked document position>}
157189
};
158-
_telemetryClient.TrackEvent("Click", properties);
190+
_telemetryClient.TrackEvent("Click", properties);
191+
```
159192

160-
*JavaScript*
193+
**Using JavaScript**
161194

162-
appInsights.trackEvent("Click", {
163-
SearchServiceName: <service name>,
164-
SearchId: <search id>,
165-
ClickedDocId: <clicked document id>,
166-
Rank: <clicked document position>
167-
});
195+
```javascript
196+
appInsights.trackEvent("Click", {
197+
SearchServiceName: <service name>,
198+
SearchId: <search id>,
199+
ClickedDocId: <clicked document id>,
200+
Rank: <clicked document position>
201+
});
202+
```
168203

169204
## 3 - Analyze in Power BI
170205

171-
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 additional data captured for search traffic analytics.
206+
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 additional data captured for search traffic analytics.
172207

173208
1. In the Azure Cognitive Search dashboard left-navigation pane, under **Settings**, click **Search traffic analytics**.
174209

175-
2. On the **Search traffic analytics** page, in step 3, click **Get Power BI Desktop** to install Power BI.
210+
1. On the **Search traffic analytics** page, in step 3, click **Get Power BI Desktop** to install Power BI.
176211

177212
![Get Power BI reports](./media/search-traffic-analytics/get-use-power-bi.png "Get Power BI reports")
178213

179-
2. On the same page, click **Download Power BI report**.
214+
1. On the same page, click **Download Power BI report**.
180215

181-
3. The report opens in Power BI Desktop, and you are 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.
216+
1. The report opens in Power BI Desktop, and you are 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.
182217

183218
![Connect to Application Insights](./media/search-traffic-analytics/connect-to-app-insights.png "Connect to Application Insights")
184219

185-
4. Click **Load**.
220+
1. Click **Load**.
186221

187222
The report contains charts and tables that help you make more informed decisions to improve your search performance and relevance.
188223

189224
Metrics included the following items:
190225

191-
* Search volume and most popular term-document pairs: terms that result in the same document clicked, ordered by clicks.
192-
* Searches without clicks: terms for top queries that register no clicks
226+
+ Search volume and most popular term-document pairs: terms that result in the same document clicked, ordered by clicks.
227+
+ Searches without clicks: terms for top queries that register no clicks
193228

194229
The following screenshot shows the built-in reports and charts for analyzing search traffic analytics.
195230

196231
![Power BI dashboard for Azure Cognitive Search](./media/search-traffic-analytics/azuresearch-powerbi-dashboard.png "Power BI dashboard for Azure Cognitive Search")
197232

198-
## Example
199-
200-
**Create your first search app in C#** is an ASP.NET Core sample that you can use to practice adding instrumentation code.
201-
202-
We recommend using the sample code from [Lesson 5 - Order results](tutorial-csharp-orders.md). It adds search rank, providing a richer baseline for data collection. For this lesson, the [sample code](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/master/create-first-app/5-order-results) is located on GitHub.
203-
204-
1. Before adding Application Insights and instrumentation code, open **OrderResults.sln** in Visual Studio and run the program to make sure there are no build errors.
205-
206-
1. Select **Project** > **Add Application Insights Telemetry**.
207-
208-
1. Click **Get Started**.
209-
210-
1. Select your subscription, account, resource, and click **Register***.
211-
212-
At this point, your application is set up for application monitoring, which means all page loads are tracked with default metrics. For more information about the previous steps, see [Enable Application Insights server-side telemetry](https://docs.microsoft.com/azure/azure-monitor/app/asp-net-core#enable-application-insights-server-side-telemetry-visual-studio).
213-
214-
1. Open **HomeController.cs**.
215-
216-
1. On line 267, add `private static TelemetryClient _telemetryClient;` and when prompted, add `using Microsoft.ApplicationInsights;` as an assembly reference.
217-
218-
1. On line 44, add a constructor that accepts a telemetry client:
219-
220-
```csharp
221-
public HomeController(TelemetryClient telemetry)
222-
{
223-
_telemetryClient = telemetry;
224-
}
225-
```
226-
227-
1. Next, correlate search events and clicks events through the search ID. On line 191, add the following lines to your query logic.
228-
229-
```csharp
230-
// Search Traffic Analytics: Establish a search ID used to correlate events
231-
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
232-
233-
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
234-
235-
string searchId = string.Empty;
236-
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string>headerValues)){
237-
searchId = headerValues.FirstOrDefault();
238-
}
239-
```
240-
241-
1. Collect search events and click events. On line 202, add the following code.
242-
243-
```csharp
244-
// Search Traffic Analytics - Click events
245-
var clickProperties = new Dictionary<string, string> {
246-
{"SearchServiceName", "searchServiceName"},
247-
{"SearchId", "searchId"},
248-
{"ClickedDocId", "HotelId"}
249-
};
250-
_telemetryClient.TrackEvent("Click", clickProperties);
251-
252-
// Search Traffic Analytics - Query events
253-
var searchProperties = new Dictionary<string, string> {
254-
{"SearchServiceName", "searchServiceName"},
255-
{"SearchId", "searchId"},
256-
{"IndexName", "Hotel"},
257-
{"ScoringProfile", "profile"}
258-
};
259-
_telemetryClient.TrackEvent("Search", searchProperties);
260-
```
261-
262233
## Next steps
263234

264235
Instrument your search application to get powerful and insightful data about your search service.
265236

266237
You can find more information on [Application Insights](https://docs.microsoft.com/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.
267238
268-
Learn more about creating amazing reports. See [Getting started with Power BI Desktop](https://powerbi.microsoft.com/documentation/powerbi-desktop-getting-started/) for details.
269-
270-
<!--Image references-->
271-
[1]: ./media/search-traffic-analytics/azuresearch-trafficanalytics.png
272-
[2]: ./media/search-traffic-analytics/azuresearch-appinsightsdata.png
273-
[3]: ./media/search-traffic-analytics/azuresearch-pbitemplate.png
239+
Learn more about creating amazing reports. See [Getting started with Power BI Desktop](https://powerbi.microsoft.com/documentation/powerbi-desktop-getting-started/) for details.

0 commit comments

Comments
 (0)