Merge pull request #231827 from EdB-MSFT/api-promql-tweaks

small updates

Author: JamesJBarnett

articles/azure-monitor/essentials/prometheus-api-promql.md

@@ -38,7 +38,7 @@ To set up Azure Active Directory authentication, follow the steps below:
 1. To register an app, follow the steps in [Register an App to request authorization tokens and work with APIs](../logs/api/register-app-for-token.md?tabs=portal)
 
 ### Allow your app access to your workspace
-Allow your app to query data from your Azure Monitor workspace.
+Assign the *Monitoring Data Reader* role your app so it can query data from your Azure Monitor workspace.
 
 1. Open your Azure Monitor workspace in the Azure portal.
 
@@ -78,7 +78,7 @@ curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'client_id=<your apps client ID>' \
 --data-urlencode 'client_secret=<your apps client secret' \
---data-urlencode 'resource= https://prometheus.monitor.azure.com'
+--data-urlencode 'resource=https://prometheus.monitor.azure.com'
 ```
 
 Sample response body:
@@ -204,6 +204,8 @@ The following limitations are in addition to those detailed in the Prometheus sp
 
 For more information on Prometheus metrics limits, see [Prometheus metrics](../../azure-monitor/service-limits.md#prometheus-metrics)
 
+[!INCLUDE [prometheus-case-sensitivity.md](..//includes/prometheus-case-sensitivity.md)]
+
 ## Next steps
 
 [Azure Monitor workspace overview (preview)](./azure-monitor-workspace-overview.md)  

articles/azure-monitor/essentials/prometheus-metrics-overview.md

@@ -47,7 +47,7 @@ See [Azure Monitor service limits](../service-limits.md#prometheus-metrics) for
 - Metrics addon doesn't work on AKS clusters configured with HTTP proxy. 
 - Scraping and storing metrics at frequencies less than 1 second isn't supported.
 
-
+[!INCLUDE [prometheus-case-sensitivity.md](..//includes/prometheus-case-sensitivity.md)]
 ## Prometheus references
 Following are links to Prometheus documentation.
 

articles/azure-monitor/includes/prometheus-case-sensitivity.md

@@ -0,0 +1,25 @@
+---
+ms.service: azure-monitor
+ms.topic: include
+ms.date: 04/01/2023
+ms.author: edbaynash
+author: EdB-MSFT
+---
+
+## Case sensitivity
+Azure managed Prometheus is a case insensitive system. If one time series differs from another only by a difference in the case of a string - metric name, label name, label value, etc. - it's treated as the same time series. This behavior is different from native open source Prometheus, which is a case sensitive system.   
+
+In Azure managed Prometheus the following time series are considered the same: 
+
+  `diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")`  
+  `diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")` 
+
+The above examples are a single time series in a time series database.
+-	Any samples ingested against them are stored as if they're scraped/ingested against a single time series.
+-	If the examples above are ingested with the same timestamp, one of them is randomly dropped.
+-	The casing that's stored in the time series database and returned in query, is unpredictable. Different casing may be returned at different times for the same time series.
+-	Any metric name or label name/value matcher present in the query is retrieved from time series database by making a case-insensitive comparison. If there's a case sensitive matcher in a query, it's automatically treated as a case-insensitive matcher when making string comparisons.
+
+It is best practice to ensure that a time series is produced or scraped using a single consistent case.
+
+In OSS Prometheus, the above time series are treated as two different time series. Any samples scraped/ingested against them are stored separately.