Docs: Azure Monitor data source changes for 7.1 (#26096)

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

docs/sources/features/datasources/azuremonitor.md

@@ -21,9 +21,9 @@ The Azure Monitor data source supports multiple services in the Azure cloud:
 - **[Azure Monitor]({{< relref "#querying-the-azure-monitor-service" >}})** is the platform service that provides a single source for monitoring Azure resources.
 - **[Application Insights]({{< relref "#querying-the-application-insights-service" >}})** is an extensible Application Performance Management (APM) service for web developers on multiple platforms and can be used to monitor your live web application - it will automatically detect performance anomalies.
 - **[Azure Log Analytics]({{< relref "#querying-the-azure-log-analytics-service" >}})** (or Azure Logs) gives you access to log data collected by Azure Monitor.
-- **[Application Insights Analytics]({{< relref "#writing-analytics-queries-for-the-application-insights-service" >}})** allows you to query [Application Insights data](https://docs.microsoft.com/en-us/azure/azure-monitor/app/analytics) using the same query language used for Azure Log Analytics.
+- **[Application Insights Analytics]({{< relref "#query-the-application-insights-analytics-service" >}})** allows you to query [Application Insights data](https://docs.microsoft.com/en-us/azure/azure-monitor/app/analytics) using the same query language used for Azure Log Analytics.
 
-## Adding the data source
+## Add the data source
 
 The data source can access metrics from four different services. You can configure access to the services that you use. It is also possible to use the same credentials for multiple services if that is how you have set it up in Azure AD.
 
@@ -76,10 +76,13 @@ In the query editor for a panel, after choosing your Azure Monitor data source,
 - `Azure Monitor`
 - `Application Insights`
 - `Azure Log Analytics`
+- `Insights Analytics`
 
-The query editor will change depending on which one you pick. Azure Monitor is the default.
+The query editor changes depending on which one you pick. Azure Monitor is the default.
 
-## Querying the Azure Monitor service
+Starting in Grafana 7.1, Insights Analytics replaced the former edit mode from within Application Insights.
+
+## Query the Azure Monitor service
 
 The Azure Monitor service provides metrics for all the Azure services that you have running. It helps you understand how your applications on Azure are performing and to proactively find issues affecting your applications.
 
@@ -93,29 +96,34 @@ Examples of metrics that you can get from the service are:
 
 {{< docs-imagebox img="/img/docs/v60/azuremonitor-service-query-editor.png" class="docs-image--no-shadow" caption="Azure Monitor Query Editor" >}}
 
-### Formatting legend keys with aliases for Azure Monitor
+As of Grafana 7.1, the query editor allows you to query multiple dimensions for metrics that support them. Metrics that support multiple dimensions are those listed in the [Azure Monitor supported Metrics List](https://docs.microsoft.com/en-us/azure/azure-monitor/platform/metrics-supported) that have one or more values listed in the "Dimension" column for the metric.
+
+### Format legend keys with aliases for Azure Monitor
 
 The default legend formatting for the Azure Monitor API is:
 
-`resourceName{dimensionValue=dimensionName}.metricName`
+`metricName{dimensionName=dimensionValue,dimensionTwoName=DimensionTwoValue}`
 
-These can be quite long but this formatting can be changed using aliases. In the Legend Format field, the aliases which are defined below can be combined any way you want.
+> **Note:** Before Grafana 7.1, the formatting included the resource name in the default: `resourceName{dimensionName=dimensionValue}.metricName`. As of Grafana 7.1, the resource name has been removed from the default legend.
 
-Azure Monitor Examples:
+These can be quite long, but this formatting can be changed by using aliases. In the **Legend Format** field, you can combine the aliases defined below any way you want.
 
-- `dimension: {{dimensionvalue}}`
-- `{{resourcegroup}} - {{resourcename}}`
+Azure Monitor examples:
+
+- `Blob Type: {{ blobtype }}`
+- `{{ resourcegroup }} - {{ resourcename }}`
 
 ### Alias patterns for Azure Monitor
 
-- `{{resourcegroup}}` = replaced with the value of the Resource Group
-- `{{namespace}}` = replaced with the value of the Namespace (e.g. Microsoft.Compute/virtualMachines)
-- `{{resourcename}}` = replaced with the value of the Resource Name
-- `{{metric}}` = replaced with metric name (e.g. Percentage CPU)
-- `{{dimensionname}}` = replaced with dimension key/label (e.g. blobtype)
-- `{{dimensionvalue}}` = replaced with dimension value (e.g. BlockBlob)
+- `{{ resourcegroup }}` = replaced with the value of the Resource Group
+- `{{ namespace }}` = replaced with the value of the Namespace (e.g. Microsoft.Compute/virtualMachines)
+- `{{ resourcename }}` = replaced with the value of the Resource Name
+- `{{ metric }}` = replaced with metric name (e.g. Percentage CPU)
+- `{{ dimensionname }}` = *Legacy as of 7.1+ (for backwards compatibility)* replaced with the first dimension's key/label (as sorted by the key/label) (e.g. blobtype)
+- `{{ dimensionvalue }}` = *Legacy as of 7.1+ (for backwards compatibility)* replaced with first dimension's value (as sorted by the key/label) (e.g. BlockBlob)
+- `{{ arbitraryDim }}` = *Available in 7.1+* replaced with the value of the corresponding dimension. (e.g. `{{ blobtype }}` becomes BlockBlob)
 
-### Templating with variables for Azure Monitor
+### Create template variables for Azure Monitor
 
 Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
 
@@ -159,29 +167,31 @@ Grafana alerting is supported for the Azure Monitor service. This is not Azure A
 
 {{< docs-imagebox img="/img/docs/v60/azuremonitor-alerting.png" class="docs-image--no-shadow" caption="Azure Monitor Alerting" >}}
 
-## Querying the Application Insights Service
+## Query the Application Insights Service
+
+{{< docs-imagebox img="/img/docs/azuremonitor/insights_metrics_multi-dim.png" class="docs-image--no-shadow" caption="Application Insights Query Editor" >}}
 
-{{< docs-imagebox img="/img/docs/v60/appinsights-service-query-editor.png" class="docs-image--no-shadow" caption="Application Insights Query Editor" >}}
+As of Grafana 7.1, you can select more than one group by dimension.
 
 ### Formatting legend keys with aliases for Application Insights
 
 The default legend formatting is:
 
-`metric/name{group/by="groupbyvalue"}`
+`metricName{dimensionName=dimensionValue,dimensionTwoName=DimensionTwoValue}`
 
 In the Legend Format field, the aliases which are defined below can be combined any way you want.
 
-Application Insights Examples:
+Application Insights examples:
 
-- `server: {{groupbyvalue}}`
-- `city: {{groupbyvalue}}`
-- `{{groupbyname}}: {{groupbyvalue}}`
+- `city: {{ client/city }}`
+- `{{ metric }} [Location: {{ client/countryOrRegion }}, {{ client/city }}]`
 
 ### Alias patterns for Application Insights
 
-- `{{groupbyvalue}}` = replaced with the value of the group by
-- `{{groupbyname}}` = replaced with the name/label of the group by
-- `{{metric}}` = replaced with metric name (e.g. requests/count)
+- `{{ groupbyvalue }}` = *Legacy as of 7.1+ (for backwards compatibility)* replaced with the first dimension's key/label (as sorted by the key/label)
+- `{{ groupbyname }}` = *Legacy as of 7.1+ (for backwards compatibility)* replaced with first dimension's value (as sorted by the key/label) (e.g. BlockBlob)
+- `{{ metric }}` = replaced with metric name (e.g. requests/count)
+- `{{ arbitraryDim }}` = *Available in 7.1+* replaced with the value of the corresponding dimension. (e.g. `{{ client/city }}` becomes Chicago)
 
 ### Filter expressions for Application Insights
 
@@ -222,30 +232,55 @@ Grafana alerting is supported for Application Insights. This is not Azure Alerts
 
 ## Querying the Azure Log Analytics service
 
-Queries are written in the new [Azure Log Analytics (or KustoDB) Query Language](https://docs.loganalytics.io/index). A Log Analytics Query can be formatted as Time Series data or as Table data.
+Queries are written in the new [Azure Log Analytics (or KustoDB) Query Language](https://docs.loganalytics.io/index). A Log Analytics query can be formatted as time series data or as table data.
 
-Time Series queries are for the Graph Panel (and other panels like the Single Stat panel) and must contain a datetime column, a metric name column and a value column. Here is an example query that returns the aggregated count grouped by the Category column and grouped by hour:
+If your credentials give you access to multiple subscriptions, then choose the appropriate subscription before entering queries.
 
+### Time series queries
+
+Time series queries are for the Graph panel and other panels like the SingleStat panel. Each query must contain at least a datetime column and a numeric value column. The result must also be sorted in ascending order by the datetime column.
+
+Here is an example query that returns the aggregated count grouped by hour:
+
+```kusto
+Perf
+| where $__timeFilter(TimeGenerated)
+| summarize count() by bin(TimeGenerated, 1h)
+| order by TimeGenerated asc
 ```
-AzureActivity
+
+A query can also have one or more non-numeric/non-datetime columns, and those columns are considered dimensions and become labels in the response. For example, a query that returns the aggregated count grouped by hour, Computer, and the CounterName:
+
+```kusto
+Perf
 | where $__timeFilter(TimeGenerated)
-| summarize count() by Category, bin(TimeGenerated, 1h)
+| summarize count() by bin(TimeGenerated, 1h), Computer, CounterName
 | order by TimeGenerated asc
 ```
 
-Table queries are mainly used in the Table panel and row a list of columns and rows. This example query returns rows with the 6 specified columns:
+You can also select additional number value columns (with, or without multiple dimensions). For example, getting a count and average value by hour, Computer, CounterName, and InstanceName:
 
+```kusto
+Perf
+| where $__timeFilter(TimeGenerated)
+| summarize Samples=count(), AvgValue=avg(CounterValue)
+    by bin(TimeGenerated, $__interval), Computer, CounterName, InstanceName
+| order by TimeGenerated asc
 ```
+
+{{< docs-imagebox img="/img/docs/azuremonitor/logs_multi-value_multi-dim.png" class="docs-image--no-shadow" caption="Azure Logs query with multiple values and multiple dimensions" >}}
+
+### Table queries
+
+Table queries are mainly used in the Table panel and show a list of columns and rows. This example query returns rows with the six specified columns:
+
+```kusto
 AzureActivity
 | where $__timeFilter()
 | project TimeGenerated, ResourceGroup, Category, OperationName, ActivityStatus, Caller
 | order by TimeGenerated desc
 ```
 
-If your credentials give you access to multiple subscriptions then choose the appropriate subscription first.
-
-{{< docs-imagebox img="/img/docs/v60/azureloganalytics-service-query-editor.png" class="docs-image--no-shadow" caption="Azure Log Analytics Query Editor" >}}
-
 ### Azure Log Analytics macros
 
 To make writing queries easier there are several Grafana macros that can be used in the where clause of a query:
@@ -304,7 +339,7 @@ Example variable queries:
 
 Example of a time series query using variables:
 
-```
+```kusto
 Perf
 | where ObjectName == "$object" and CounterName == "$metric"
 | where TimeGenerated >= $__timeFrom() and TimeGenerated <= $__timeTo()
@@ -331,21 +366,11 @@ If you're not currently logged in to the Azure Portal, then the link opens the l
 
 Grafana alerting is supported for Application Insights. This is not Azure Alerts support. Read more about how alerting in Grafana works in [Alerting rules]({{< relref "../../alerting/alerts-overview.md" >}}).
 
-### Writing analytics queries For the Application Insights service
-
-If you change the service type to "Application Insights", the menu icon to the right adds another option, "Toggle Edit Mode". Once clicked, the query edit mode changes to give you a full text area in which to write log analytics queries. (This is identical to how the InfluxDB data source lets you write raw queries.)
-
-Once a query is written, the column names are automatically parsed out of the response data. You can then select them in the "X-axis", "Y-axis", and "Split On" dropdown menus, or just type them out.
-
-There are some important caveats to remember:
-
-- You'll want to order your y-axis in the query, eg. `order by timestamp asc`. The graph may come out looking bizarre otherwise. It's better to have Microsoft sort it on their side where it's faster, than to implement this in the plugin.
-
-- If you copy a log analytics query, typically they'll end with a render instruction, like `render barchart`. This is unnecessary, but harmless.
+## Query the Application Insights Analytics service
 
-- Currently, four default dashboard variables are supported: `$__timeFilter()`, `$__from`, `$__to`, and `$__interval`. If you're searching in timestamped data, replace the beginning of your where clause to `where $__timeFilter()`. Dashboard changes by time region are handled as you'd expect, as long as you leave the name of the `timestamp` column alone. Likewise, `$__interval` will automatically change based on the dashboard's time region _and_ the width of the chart being displayed. Use it in bins, so `bin(timestamp,$__interval)` changes into something like `bin(timestamp,1s)`. Use `$__from` and `$__to` if you just want the formatted dates to be inserted.
+If you change the service type to **Insights Analytics**, then a similar editor to the Log Analytics service is available. This service also uses the Kusto language, so the instructions for querying data are identical to [querying the log analytics service]({{< relref "#querying-the-azure-log-analytics-service" >}}), except that you query Application Insights Analytics data instead.
 
-- Templated dashboard variables are not yet supported! They will come in a future version.
+{{< docs-imagebox img="/img/docs/azuremonitor/insights_analytics_multi-dim.png" class="docs-image--no-shadow" caption="Azure Application Insights Analytics query with multiple dimensions" >}}
 
 ## Configure the data source with provisioning