More steps

HeidiSteen · HeidiSteen · commit 9c985ddf9a39 · 2020-03-19T09:55:49.000-07:00
diff --git a/articles/search/search-traffic-analytics.md b/articles/search/search-traffic-analytics.md
@@ -19,44 +19,43 @@ Search traffic analytics is a pattern for implementing a feedback loop for your
 This pattern takes a dependency on [Application Insights](https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview) (a feature of [Azure Monitor](https://docs.microsoft.com/azure/azure-monitor/)) to collect user data. You will also need to add instrumentation to your client code, as described in this article. Finally, you will need a reporting mechanism to analyze the data. We recommend Power BI but you can use any tool that connects to Application Insights.
 
 > [!NOTE]
-> The pattern described in this article is for advanced scenarios and clickstream data generated by your client. Alternatively, you can report on log information generated by your search service. For more information about service log reports, see [Collect and analyze log data](search-monitor-logs.md).
+> The pattern described in this article is for advanced scenarios and clickstream data generated by your client. Alternatively, you can report on log information generated by your search service. For more information, see [Collect and analyze log data](search-monitor-logs.md).
 
 ## Identify relevant search data
 
 To have useful search metrics, it's necessary to log some signals from the users of the search application. These signals signify content that users are interested in and that they consider relevant.
 
 Two signals are needed for search traffic analytics:
 
-+ User-generated search events: only search queries initiated by a user are interesting. Search requests used to populate facets, additional content or any internal information, are not important and they skew and bias your results.
++ User-generated search events: Only search queries initiated by a user are interesting. Search requests used to populate facets, additional content or any internal information, are not important and they skew and bias your results.
 
-+ User-generated click events: By clicks in this document, we refer to a user selecting a particular search result returned from a search query. A click generally means that a document is a relevant result for a specific search query.
++ 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.
 
-By linking search and click events with a correlation ID, you'll gain more insights into how your application performing.
+By linking search and click events with a correlation ID, you'll gain a deeper understanding of how well your application's search functionality is performing. 
 
 ## Add search traffic analytics
 
-The signals mentioned in the preceding section must be gathered from the search application as the user interacts with it.
- Application Insights is an extensible monitoring solution, available for multiple platforms, with flexible instrumentation options. Usage of Application Insights lets you take advantage of the Power BI search reports created by Azure Cognitive Search to make the analysis of data easier.
+The signals mentioned in the preceding section must be gathered from the search application as the user interacts with it. Application Insights is an extensible monitoring solution, available for multiple platforms, with flexible instrumentation options. Usage of Application Insights lets you take advantage of the Power BI search reports created by Azure Cognitive Search to make the analysis of data easier.
 
 In the [portal](https://portal.azure.com) page for your Azure Cognitive Search service, the Search Traffic Analytics page contains a cheat sheet for following this telemetry pattern. You can also select or create an Application Insights resource, and see the necessary data, all in one place.
 
 ![Search Traffic Analytics page in the portal](media/search-traffic-analytics/azuresearch-trafficanalytics.png "Search Traffic Analytics page in the portal")
 
 ## 1 - Select a resource
 
-You need to select an Application Insights resource to use or create one if you don't have one already. You can use a resource that's already in use to log the required custom events.
+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.
 
-When creating a new Application Insights resource, all application types are valid for this scenario. Select the one that best fits the platform you are using.
+After you create the resource on Azure, [add Application Insights](https://docs.microsoft.com/azure/azure-monitor/app/platforms) to your code.
 
-You need the instrumentation key for creating the telemetry client for your application. You can get it from the Application Insights portal dashboard, or you can get it from the Search Traffic Analytics page, selecting the instance you want to use.
+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.
 
 ## 2 - Add instrumentation
 
 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:
 
 **Step 1: Create a telemetry client**
 
-This is the object that sends events to the Application Insights Resource.
+Create an object that sends events to Application Insights.
 
 *C#*
 
@@ -72,7 +71,7 @@ This is the object that sends events to the Application Insights Resource.
     window.appInsights=appInsights;
     </script>
 
-For other languages and platforms, see the complete [list](https://docs.microsoft.com/azure/application-insights/app-insights-platforms).
+For other languages, see the complete list of [supported platforms and frameworks](https://docs.microsoft.com/azure/application-insights/app-insights-platforms).
 
 **Step 2: Request a Search ID for correlation**
 
@@ -91,15 +90,15 @@ To correlate search requests with clicks, it's necessary to have a correlation I
      searchId = headerValues.FirstOrDefault();
     }
 
-*JavaScript*
+*JavaScript (calling REST APIs)*
 
     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');
 
 **Step 3: Log Search events**
 
-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:
+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.
 
 **SearchServiceName**: (string) search service name
 **SearchId**: (guid) unique identifier of the search query (comes in the search response)
@@ -109,11 +108,7 @@ Every time that a search request is issued by a user, you should log that as a s
 **ScoringProfile**: (string) name of the scoring profile used, if any
 
 > [!NOTE]
-> Request count on user generated queries by adding $count=true to your search query. See more information [here](/rest/api/searchservice/search-documents#counttrue--false).
->
-
-> [!NOTE]
-> Remember to only log search queries that are generated by users.
+> 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).
 >
 
 *C#*
@@ -126,7 +121,7 @@ Every time that a search request is issued by a user, you should log that as a s
     {"ResultCount", <results count>},
     {"ScoringProfile", <scoring profile used>}
     };
-    telemetryClient.TrackEvent("Search", properties);
+    _telemetryClient.TrackEvent("Search", properties);
 
 *JavaScript*
 
@@ -160,7 +155,7 @@ Every time that a user clicks on a document, that's a signal that must be logged
     {"ClickedDocId", <clicked document id>},
     {"Rank", <clicked document position>}
     };
-    telemetryClient.TrackEvent("Click", properties);
+    _telemetryClient.TrackEvent("Click", properties);
 
 *JavaScript*
 
@@ -200,6 +195,50 @@ The following screenshot shows the built-in reports and charts for analyzing sea
 
 ![Power BI dashboard for Azure Cognitive Search](./media/search-traffic-analytics/azuresearch-powerbi-dashboard.png "Power BI dashboard for Azure Cognitive Search")
 
+## Example
+
+**Create your first search app in C#** is an ASP.NET Core solution that you can use to practice adding instrumentation code.
+
+Use the sample code from the last lesson, [5 - Order results](https://docs.microsoft.com/en-us/azure/search/tutorial-csharp-orders), so that you can leverage search rank and more click behaviors. 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.
+
+1. Before adding Application Insights and instrumentation code, run the program to make sure there are no build errors.
+
+1. In Visual Studio, select **Project** > **Add Application Insights Telemetry**. For more information, 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).
+
+1. Click **Get Started**.
+
+1. Select your subscription, account, resource, and click **Register***.
+
+   At this point, your application is set up for application monitoring, which means all page loads are tracked with default metrics.
+
+1. Open **HomeController.cs**.
+
+1. On line 52, add `private static TelemetryClient _telemetryClient;` and when prompted, add `using Microsoft.ApplicationInsights;` as an assembly reference.
+
+1. On line 20, add a constructor that accepts a telemetry client:
+
+   ```csharp
+   public HomeController(TelemetryClient telemetry)
+    {
+        _telemetryClient = telemetry;
+    }
+   ```
+
+1. Correlate search and clicks events logged to Application Insights using the search ID. On line 79, add the following lines. When prompted, add `using System.Collections.Generic;` as an assembly reference.
+
+   ```csharp
+   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);
+
+    IEnumerable<string> headerValues;
+    string searchId = string.Empty;
+    if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
+         searchId = headerValues.FirstOrDefault();
+    }
+   ```
+
 ## Next steps
 Instrument your search application to get powerful and insightful data about your search service.
 
