Editing pass

Author: HeidiSteen

articles/search/search-traffic-analytics.md

@@ -14,12 +14,12 @@ ms.date: 03/18/2020
 
 # Collect telemetry data for search traffic analytics
 
-Search traffic analytics is a pattern for implementing a feedback loop for your Azure Cognitive Search service. The objective is to collect telemetry on user-initiated click events and keyboard inputs. Using this information, you can determine the effectiveness of your search solution, including popular search terms, clickthrough rate, and which query inputs yield zero results.
+Search traffic analytics is a pattern for collecting telemetry about user interactions with your Azure Cognitive Search application, such as user-initiated click events and keyboard inputs. Using this information, you can determine the effectiveness of your search solution, including popular search terms, clickthrough rate, and which query inputs yield zero results.
 
-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 the Application Dashboard or any tool that connects to Application Insights.
+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. It requires that you 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 the Application Dashboard or 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, 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 code you add to your client. In contrast, service logs are easy to set up and can be done in the portal. For more information, see [Collect and analyze log data](search-monitor-logs.md).
 
 ## Identify relevant search data
 
@@ -41,9 +41,9 @@ In the [portal](https://portal.azure.com) page for your Azure Cognitive Search s
 
 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.
 
-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.
+To register your app with Application Insights, you can follow [instructions for supported languages and platforms](https://docs.microsoft.com/azure/azure-monitor/app/platforms). Registration is simply adding the instrumentation key from Application Insights to your code, which sets up the association. You can find the key in the portal, or from the Search Traffic Analytics page when you select an existing resource.
 
-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.
+For some Visual Studio project types, you can create an Application Insights resource and register your apps in just a few clicks.
 
 1. For Visual Studio and ASP.NET development, open your solution and select **Project** > **Add Application Insights Telemetry**.
 
@@ -67,7 +67,7 @@ On the client, you might have additional code that manipulates query inputs, add
 
 **Use C#**
 
-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 instructions if you are unsure of the key location.
+For C#, the **InstrumentationKey** is found in your application configuration, such as appsettings.json if your project is ASP.NET. Refer back to the registration instructions if you are unsure of the key location.
 
 ```csharp
 private static TelemetryClient _telemetryClient;
@@ -92,21 +92,22 @@ window.appInsights=appInsights;
 
 ### Step 2: Request a Search ID for correlation
 
-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.
+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 an HTTP header.
 
-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.  
+Having the search ID allows correlation of the metrics emitted by Azure Cognitive Search for the request itself, with the custom metrics you are logging in Application Insights.  
 
 **Use C#**
 
 ```csharp
 // 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);
-IEnumerable<string> headerValues;
 string searchId = string.Empty;
-if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
+if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues)){
     searchId = headerValues.FirstOrDefault();
 }
 ```
@@ -222,7 +223,7 @@ Metrics included the following items:
 + Search volume and most popular term-document pairs: terms that result in the same document clicked, ordered by clicks.
 + Searches without clicks: terms for top queries that register no clicks
 
-The following screenshot shows the built-in reports and charts for analyzing search traffic analytics.
+The following screenshot shows what a built-in report might look like if you have used all of the schema elements.
 
 ![Power BI dashboard for Azure Cognitive Search](./media/search-traffic-analytics/azuresearch-powerbi-dashboard.png "Power BI dashboard for Azure Cognitive Search")