From 71aaa844f52455c6543f84b9de3ba2333f7d76c3 Mon Sep 17 00:00:00 2001
From: Gunnar Aasen <gunnar.r.aasen@gmail.com>
Date: Wed, 12 Sep 2018 12:01:42 -0700
Subject: [PATCH] Update Azure Monitor README

---
 plugins/outputs/azure_monitor/README.md | 28 ++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/plugins/outputs/azure_monitor/README.md b/plugins/outputs/azure_monitor/README.md
index cd1386136..d1b91a838 100644
--- a/plugins/outputs/azure_monitor/README.md
+++ b/plugins/outputs/azure_monitor/README.md
@@ -1,5 +1,8 @@
 # Azure Monitor
 
+__The Azure Monitor custom metrics service is currently in preview and not
+available in a subset of Azure regions.__
+
 This plugin will send custom metrics to Azure Monitor. Azure Monitor has a
 metric resolution of one minute. To handle this in Telegraf, the Azure Monitor
 output plugin will automatically aggregates metrics into one minute buckets,
@@ -11,12 +14,6 @@ metric is written as the Azure Monitor metric name. All field values are
 written as a summarized set that includes: min, max, sum, count. Tags are
 written as a dimension on each Azure Monitor metric.
 
-Since Azure Monitor only accepts numeric values, string-typed fields are
-dropped by default. There is a configuration option (`strings_as_dimensions`)
-to retain fields that contain strings as extra dimensions. Azure Monitor
-allows a maximum of 10 dimensions per metric so any dimensions over that
-amount will be deterministically dropped.
-
 ### Configuration:
 
 ```toml
@@ -88,7 +85,8 @@ authentication is checked. Here are the preferred authentication methods:
     - Primarily useful if Telegraf is writing metrics for other resources.
       [More information][principal].
     - A Service Principal or User Principal needs to be assigned the `Monitoring
-      Contributor` roles.
+      Metrics Publisher` role on the resource(s) metrics will be emitted
+      against.
 3. AAD User Tokens (User Principals)
     - Allows Telegraf to authenticate like a user. It is best to use this method
       for development.
@@ -137,3 +135,19 @@ following configurations:
 
 **Note: As shown above, the last option (#4) is the preferred way to
 authenticate when running Telegraf on Azure VMs.
+
+### Dimensions
+
+Azure Monitor only accepts values with a numeric type. The plugin will drop
+fields with a string type by default. The plugin can set all string type fields
+as extra dimensions in the Azure Monitor custom metric by setting the
+configuration option `strings_as_dimensions` to `true`. 
+
+Keep in mind, Azure Monitor allows a maximum of 10 dimensions per metric. The
+plugin will deterministically dropped any dimensions that exceed the 10
+dimension limit.
+
+To convert only a subset of string-typed fields as dimensions, enable
+`strings_as_dimensions` and use the [`fieldpass` or `fielddrop`
+processors](https://docs.influxdata.com/telegraf/v1.7/administration/configuration/#processor-configuration)
+to limit the string-typed fields that are sent to the plugin.