Rebase

Azure · Jun 30, 2021 · a3af338 · a3af338
1 parent dfad277
commit a3af338
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 56 deletions.
diff --git a/sdk/monitor/Azure.Monitor.Query/README.md b/sdk/monitor/Azure.Monitor.Query/README.md
@@ -1,44 +1,46 @@
 # Azure Monitor Query client library for .NET
 
-The `Azure.Monitor.Query` package provides an ability to query [Azure Monitor Logs](https://docs.microsoft.com/azure/azure-monitor/logs/data-platform-logs) and [Azure Monitor Metrics](https://docs.microsoft.com/azure/azure-monitor/essentials/data-platform-metrics) data.
+The `Azure.Monitor.Query` package provides the ability to query the following Azure Monitor data sources:
 
-[Azure Monitor Logs](https://docs.microsoft.com/azure/azure-monitor/logs/data-platform-logs) is a feature of Azure Monitor that collects and organizes log and performance data from monitored resources. Data from different sources such as platform logs from Azure services, log and performance data from virtual machines agents, and usage and performance data from applications can be consolidated into a single workspace so they can be analyzed together using a sophisticated query language that's capable of quickly analyzing millions of records.
-
-[Azure Monitor Metrics](https://docs.microsoft.com/azure/azure-monitor/essentials/data-platform-metrics) is a feature of Azure Monitor that collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics in Azure Monitor are lightweight and capable of supporting near real-time scenarios making them particularly useful for alerting and fast detection of issues.
+- [Azure Monitor Logs](https://docs.microsoft.com/azure/azure-monitor/logs/data-platform-logs) - Collects and organizes log and performance data from monitored resources. Data from different sources such as platform logs from Azure services, log and performance data from virtual machines agents, and usage and performance data from apps can be consolidated into a single workspace. The various data types can be analyzed together using the [Kusto Query Language](https://docs.microsoft.com/azure/data-explorer/kusto/query).
+- [Azure Monitor Metrics](https://docs.microsoft.com/azure/azure-monitor/essentials/data-platform-metrics) - Collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics in Azure Monitor are lightweight and capable of supporting near real-time scenarios, making them particularly useful for alerting and fast detection of issues.
 
 [Source code][query_client_src] | [Package (NuGet)][query_client_nuget_package]
 
 ## Getting started
 
 ### Install the package
+
 Install the Azure Monitor Query client library for .NET with [NuGet][query_client_nuget_package]:
 
 ```
 dotnet add package Azure.Monitor.Query --prerelease
 ```
 
 ### Prerequisites
-* An [Azure subscription][azure_sub].
-* To be able to query logs you would need an existing Log Analytics workspace. You can create it in one of the following approaches:
-    * [Azure Portal](https://docs.microsoft.com/azure/azure-monitor/logs/quick-create-workspace)
-    * [Azure CLI](https://docs.microsoft.com/azure/azure-monitor/logs/quick-create-workspace-cli)
-    * [PowerShell](https://docs.microsoft.com/azure/azure-monitor/logs/powershell-workspace-configuration)
 
-* To be able to query metrics all you need is an Azure resource of any kind (Storage Account, KeyVault, CosmosDB etc.)
+- An [Azure subscription][azure_sub].
+- To query logs, you need an existing Log Analytics workspace. You can create it with one of the following approaches:
+  - [Azure Portal](https://docs.microsoft.com/azure/azure-monitor/logs/quick-create-workspace)
+  - [Azure CLI](https://docs.microsoft.com/azure/azure-monitor/logs/quick-create-workspace-cli)
+  - [PowerShell](https://docs.microsoft.com/azure/azure-monitor/logs/powershell-workspace-configuration)
+- To query metrics, all you need is an Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.).
 
-### Authenticate the Client
+### Authenticate the client
 
-In order to interact with the Azure Monitor service, you will need to create an instance of a [TokenCredential](https://docs.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) class and pass it to the constructor of your `LogsClient` or `MetricsClient` class.
+To interact with the Azure Monitor service, create an instance of a [TokenCredential](https://docs.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) class. Pass it to the constructor of your `LogsQueryClient` or `MetricsQueryClient` class.
 
 ## Key concepts
 
-- `LogsClient` - Client that provides methods to query logs from Azure Monitor Logs.
-- `MetricsClient` - Client that provides methods to query metrics from Azure Monitor Metrics.
+- `LogsQueryClient` - Client that provides methods to query logs from Azure Monitor Logs.
+- `MetricsQueryClient` - Client that provides methods to query metrics from Azure Monitor Metrics.
 
 ### Thread safety
-We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
+
+All client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
 
 ### Additional concepts
+
 <!-- CLIENT COMMON BAR -->
 [Client options](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) |
 [Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) |
@@ -60,14 +62,17 @@ We guarantee that all client instance methods are thread-safe and independent of
 
 ### Query logs
 
-You can query logs using the `LogsClient.QueryAsync`. The result would be returned as a table with a collection of rows:
+You can query logs using the `LogsQueryClient.QueryAsync` method. The result is returned as a table with a collection of rows:
 
 ```C# Snippet:QueryLogsAsTable
 var endpoint = new Uri("https://api.loganalytics.io");
 string workspaceId = "<workspace_id>";
 
 var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
-Response<LogsQueryResult> response = await client.QueryAsync(workspaceId, "AzureActivity | top 10 by TimeGenerated", TimeSpan.FromDays(1));
+Response<LogsQueryResult> response = await client.QueryAsync(
+    workspaceId,
+    "AzureActivity | top 10 by TimeGenerated",
+    TimeSpan.FromDays(1));
 
 LogsQueryResultTable table = response.Value.PrimaryTable;
 
@@ -79,7 +84,7 @@ foreach (var row in table.Rows)
 
 ### Query logs as model
 
-You can map query results to a model using the `LogsClient.QueryAsync<T>` method.
+You can map query results to a model using the `LogsQueryClient.QueryAsync<T>` method.
 
 ```C# Snippet:QueryLogsAsModelsModel
 public class MyLogEntryModel
@@ -94,7 +99,8 @@ var client = new LogsQueryClient(TestEnvironment.LogsEndpoint, new DefaultAzureC
 string workspaceId = "<workspace_id>";
 
 // Query TOP 10 resource groups by event count
-Response<IReadOnlyList<MyLogEntryModel>> response = await client.QueryAsync<MyLogEntryModel>(workspaceId,
+Response<IReadOnlyList<MyLogEntryModel>> response = await client.QueryAsync<MyLogEntryModel>(
+    workspaceId,
     "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
     TimeSpan.FromDays(1));
 
@@ -106,7 +112,7 @@ foreach (var logEntryModel in response.Value)
 
 ### Query logs as primitive
 
-If your query return a single column (or a single value) of a primitive type you can use `LogsClient.QueryAsync<T>` overload to deserialize it:
+If your query returns a single column (or a single value) of a primitive type, use the `LogsQueryClient.QueryAsync<T>` overload to deserialize it:
 
 ```C# Snippet:QueryLogsAsPrimitive
 var endpoint = new Uri("https://api.loganalytics.io");
@@ -115,7 +121,8 @@ string workspaceId = "<workspace_id>";
 var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
 
 // Query TOP 10 resource groups by event count
-Response<IReadOnlyList<string>> response = await client.QueryAsync<string>(workspaceId,
+Response<IReadOnlyList<string>> response = await client.QueryAsync<string>(
+    workspaceId,
     "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count | project ResourceGroup",
     TimeSpan.FromDays(1));
 
@@ -127,7 +134,7 @@ foreach (var resourceGroup in response.Value)
 
 ### Batch query
 
-You can execute multiple queries in on request using the `LogsClient.CreateBatchQuery`:
+You can execute multiple queries in a single request using the `LogsQueryClient.CreateBatchQuery` method:
 
 ```C# Snippet:BatchQuery
 var endpoint = new Uri("https://api.loganalytics.io");
@@ -139,8 +146,14 @@ var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
 // And total event count
 var batch = new LogsBatchQuery();
 
-string countQueryId = batch.AddQuery(workspaceId, "AzureActivity | count", TimeSpan.FromDays(1));
-string topQueryId = batch.AddQuery(workspaceId, "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count", TimeSpan.FromDays(1));
+string countQueryId = batch.AddQuery(
+    workspaceId,
+    "AzureActivity | count",
+    TimeSpan.FromDays(1));
+string topQueryId = batch.AddQuery(
+    workspaceId,
+    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
+    TimeSpan.FromDays(1));
 
 Response<LogsBatchQueryResults> response = await client.QueryBatchAsync(batch);
 
@@ -156,14 +169,17 @@ foreach (var logEntryModel in topEntries)
 
 ### Query dynamic table
 
-You can also dynamically inspect the list of columns. The following example prints the result of the query as a table:
+You can also dynamically inspect the list of columns. The following example prints the query result as a table:
 
 ```C# Snippet:QueryLogsPrintTable
 var endpoint = new Uri("https://api.loganalytics.io");
 string workspaceId = "<workspace_id>";
 
 var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
-Response<LogsQueryResult> response = await client.QueryAsync(workspaceId, "AzureActivity | top 10 by TimeGenerated", TimeSpan.FromDays(1));
+Response<LogsQueryResult> response = await client.QueryAsync(
+    workspaceId,
+    "AzureActivity | top 10 by TimeGenerated",
+    TimeSpan.FromDays(1));
 
 LogsQueryResultTable table = response.Value.PrimaryTable;
 
@@ -197,10 +213,11 @@ string workspaceId = "<workspace_id>";
 var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
 
 // Query TOP 10 resource groups by event count
-Response<IReadOnlyList<int>> response = await client.QueryAsync<int>(workspaceId,
+Response<IReadOnlyList<int>> response = await client.QueryAsync<int>(
+    workspaceId,
     "AzureActivity | summarize count()",
     TimeSpan.FromDays(1),
-    options: new LogsQueryOptions()
+    options: new LogsQueryOptions
     {
         ServerTimeout = TimeSpan.FromMinutes(10)
     });
@@ -211,9 +228,9 @@ foreach (var resourceGroup in response.Value)
 }
 ```
 
-### Querying metrics
+### Query metrics
 
-You can query metrics using the `MetricsClient.QueryAsync`. For every requested metric a set of aggregated values would be returned inside the `TimeSeries` collection.
+You can query metrics using the `MetricsQueryClient.QueryAsync` method. For every requested metric, a set of aggregated values is returned inside the `TimeSeries` collection.
 
 ```C# Snippet:QueryMetrics
 var endpoint = new Uri("https://management.azure.com");
@@ -248,7 +265,7 @@ foreach (var metric in results.Value.Metrics)
 
 When you interact with the Azure Monitor Query client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API][monitor_rest_api] requests.
 
-For example, if you submit an invalid query a `400` error is returned, indicating "Bad Request".
+For example, if you submit an invalid query, an HTTP 400 error is returned, indicating "Bad Request".
 
 ```C# Snippet:BadRequest
 var endpoint = new Uri("https://api.loganalytics.io");
@@ -258,7 +275,8 @@ var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
 
 try
 {
-    await client.QueryAsync(workspaceId, "My Not So Valid Query", TimeSpan.FromDays(1));
+    await client.QueryAsync(
+        workspaceId, "My Not So Valid Query", TimeSpan.FromDays(1));
 }
 catch (Exception e)
 {
@@ -279,28 +297,22 @@ Content:
 
 ### Setting up console logging
 
-The simplest way to see the logs is to enable the console logging.
-To create an Azure SDK log listener that outputs messages to console use AzureEventSourceListener.CreateConsoleLogger method.
+The simplest way to see the logs is to enable the console logging. To create an Azure SDK log listener that outputs messages to the console, use the [AzureEventSourceListener.CreateConsoleLogger](https://docs.microsoft.com/dotnet/api/azure.core.diagnostics.azureeventsourcelistener.createconsolelogger?view=azure-dotnet) method:
 
 ```C#
-// Setup a listener to monitor logged events.
+// Set up a listener to monitor logged events.
 using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
 ```
 
-To learn more about other logging mechanisms see [here][logging].
+To learn more about other logging mechanisms, see [here][logging].
 
 ## Next steps
 
 ## Contributing
 
-This project welcomes contributions and suggestions.  Most contributions require
-you to agree to a Contributor License Agreement (CLA) declaring that you have
-the right to, and actually do, grant us the rights to use your contribution. For
-details, visit [cla.microsoft.com][cla].
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
 
-This project has adopted the [Microsoft Open Source Code of Conduct][coc].
-For more information see the [Code of Conduct FAQ][coc_faq] or contact 
-[opencode@microsoft.com][coc_contact] with any additional questions or comments.
+This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
 
 [query_client_src]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/monitor/Azure.Monitor.Query/src
 [query_client_nuget_package]: https://www.nuget.org/packages?q=Azure.Monitor.Query

diff --git a/....Monitor.Query/tests/LogsClientSamples.cs → ...tor.Query/tests/LogsQueryClientSamples.cs b/....Monitor.Query/tests/LogsClientSamples.cs → ...tor.Query/tests/LogsQueryClientSamples.cs
@@ -11,7 +11,7 @@
 
 namespace Azure.Monitor.Query.Tests
 {
-    public class LogsClientSamples: SamplesBase<MonitorQueryClientTestEnvironment>
+    public class LogsQueryClientSamples: SamplesBase<MonitorQueryClientTestEnvironment>
     {
         [Test]
         public async Task QueryLogsAsTable()
@@ -26,7 +26,10 @@ public async Task QueryLogsAsTable()
 #endif
 
             var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
-            Response<LogsQueryResult> response = await client.QueryAsync(workspaceId, "AzureActivity | top 10 by TimeGenerated", TimeSpan.FromDays(1));
+            Response<LogsQueryResult> response = await client.QueryAsync(
+                workspaceId,
+                "AzureActivity | top 10 by TimeGenerated",
+                TimeSpan.FromDays(1));
 
             LogsQueryResultTable table = response.Value.PrimaryTable;
 
@@ -52,7 +55,10 @@ public async Task QueryLogsAsTablePrintAll()
 #endif
 
             var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
-            Response<LogsQueryResult> response = await client.QueryAsync(workspaceId, "AzureActivity | top 10 by TimeGenerated", TimeSpan.FromDays(1));
+            Response<LogsQueryResult> response = await client.QueryAsync(
+                workspaceId,
+                "AzureActivity | top 10 by TimeGenerated",
+                TimeSpan.FromDays(1));
 
             LogsQueryResultTable table = response.Value.PrimaryTable;
 
@@ -94,7 +100,8 @@ public async Task QueryLogsAsPrimitive()
 
             // Query TOP 10 resource groups by event count
             #region Snippet:QueryLogsAsPrimitiveCall
-            Response<IReadOnlyList<string>> response = await client.QueryAsync<string>(workspaceId,
+            Response<IReadOnlyList<string>> response = await client.QueryAsync<string>(
+                workspaceId,
                 "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count | project ResourceGroup",
                 TimeSpan.FromDays(1));
             #endregion
@@ -121,7 +128,8 @@ public async Task QueryLogsAsModels()
 
             // Query TOP 10 resource groups by event count
             #region Snippet:QueryLogsAsModelCall
-            Response<IReadOnlyList<MyLogEntryModel>> response = await client.QueryAsync<MyLogEntryModel>(workspaceId,
+            Response<IReadOnlyList<MyLogEntryModel>> response = await client.QueryAsync<MyLogEntryModel>(
+                workspaceId,
                 "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
                 TimeSpan.FromDays(1));
             #endregion
@@ -154,8 +162,14 @@ public async Task BatchQuery()
             var batch = new LogsBatchQuery();
 
             #region Snippet:BatchQueryAddAndGet
-            string countQueryId = batch.AddQuery(workspaceId, "AzureActivity | count", TimeSpan.FromDays(1));
-            string topQueryId = batch.AddQuery(workspaceId, "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count", TimeSpan.FromDays(1));
+            string countQueryId = batch.AddQuery(
+                workspaceId,
+                "AzureActivity | count",
+                TimeSpan.FromDays(1));
+            string topQueryId = batch.AddQuery(
+                workspaceId,
+                "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
+                TimeSpan.FromDays(1));
 
             Response<LogsBatchQueryResults> response = await client.QueryBatchAsync(batch);
 
@@ -187,10 +201,11 @@ public async Task QueryLogsWithTimeout()
             var client = new LogsQueryClient(endpoint, new DefaultAzureCredential());
 
             // Query TOP 10 resource groups by event count
-            Response<IReadOnlyList<int>> response = await client.QueryAsync<int>(workspaceId,
+            Response<IReadOnlyList<int>> response = await client.QueryAsync<int>(
+                workspaceId,
                 "AzureActivity | summarize count()",
                 TimeSpan.FromDays(1),
-                options: new LogsQueryOptions()
+                options: new LogsQueryOptions
                 {
                     ServerTimeout = TimeSpan.FromMinutes(10)
                 });
@@ -219,7 +234,8 @@ public async Task BadRequest()
 
             try
             {
-                await client.QueryAsync(workspaceId, "My Not So Valid Query", TimeSpan.FromDays(1));
+                await client.QueryAsync(
+                    workspaceId, "My Not So Valid Query", TimeSpan.FromDays(1));
             }
             catch (Exception e)
             {
@@ -237,4 +253,4 @@ public class MyLogEntryModel
         }
         #endregion
     }
-}
+}
diff --git a/...nitor.Query/tests/MetricsClientSamples.cs → ....Query/tests/MetricsQueryClientSamples.cs b/...nitor.Query/tests/MetricsClientSamples.cs → ....Query/tests/MetricsQueryClientSamples.cs
@@ -9,7 +9,7 @@
 
 namespace Azure.Monitor.Query.Tests
 {
-    public class MetricsClientSamples: SamplesBase<MonitorQueryClientTestEnvironment>
+    public class MetricsQueryClientSamples: SamplesBase<MonitorQueryClientTestEnvironment>
     {
         [Test]
         [Ignore("https://github.com/Azure/azure-sdk-for-net/issues/21657")]
@@ -49,4 +49,4 @@ public async Task QueryMetrics()
             #endregion
         }
     }
-}
+}