|
| 1 | +# Azure Monitor |
| 2 | + |
| 3 | +This plugin will send custom metrics to Azure Monitor. Azure Monitor has a |
| 4 | +metric resolution of one minute. To handle this in Telegraf, the Azure Monitor |
| 5 | +output plugin will automatically aggregates metrics into one minute buckets, |
| 6 | +which are then sent to Azure Monitor on every flush interval. |
| 7 | + |
| 8 | +The metrics from each input plugin will be written to a separate Azure Monitor |
| 9 | +namespace, prefixed with `Telegraf/` by default. The field name for each |
| 10 | +metric is written as the Azure Monitor metric name. All field values are |
| 11 | +written as a summarized set that includes: min, max, sum, count. Tags are |
| 12 | +written as a dimension on each Azure Monitor metric. |
| 13 | + |
| 14 | +Since Azure Monitor only accepts numeric values, string-typed fields are |
| 15 | +dropped by default. There is a configuration option (`strings_as_dimensions`) |
| 16 | +to retain fields that contain strings as extra dimensions. Azure Monitor |
| 17 | +allows a maximum of 10 dimensions per metric so any dimensions over that |
| 18 | +amount will be deterministically dropped. |
| 19 | + |
| 20 | +### Configuration: |
| 21 | + |
| 22 | +```toml |
| 23 | +[[outputs.azure_monitor]] |
| 24 | + ## Timeout for HTTP writes. |
| 25 | + # timeout = "20s" |
| 26 | + |
| 27 | + ## Set the namespace prefix, defaults to "Telegraf/<input-name>". |
| 28 | + # namespace_prefix = "Telegraf/" |
| 29 | + |
| 30 | + ## Azure Monitor doesn't have a string value type, so convert string |
| 31 | + ## fields to dimensions (a.k.a. tags) if enabled. Azure Monitor allows |
| 32 | + ## a maximum of 10 dimensions so Telegraf will only send the first 10 |
| 33 | + ## alphanumeric dimensions. |
| 34 | + # strings_as_dimensions = false |
| 35 | + |
| 36 | + ## Both region and resource_id must be set or be available via the |
| 37 | + ## Instance Metadata service on Azure Virtual Machines. |
| 38 | + # |
| 39 | + ## Azure Region to publish metrics against. |
| 40 | + ## ex: region = "southcentralus" |
| 41 | + # region = "" |
| 42 | + # |
| 43 | + ## The Azure Resource ID against which metric will be logged, e.g. |
| 44 | + ## ex: resource_id = "/subscriptions/<subscription_id>/resourceGroups/<resource_group>/providers/Microsoft.Compute/virtualMachines/<vm_name>" |
| 45 | + # resource_id = "" |
| 46 | +``` |
| 47 | + |
| 48 | +### Setup |
| 49 | + |
| 50 | +1. [Register the `microsoft.insights` resource provider in your Azure subscription][resource provider]. |
| 51 | +2. If using Managed Service Identities to authenticate an Azure VM, |
| 52 | + [enable system-assigned managed identity][enable msi]. |
| 53 | +2. Use a region that supports Azure Monitor Custom Metrics, |
| 54 | + For regions with Custom Metrics support, an endpoint will be available with |
| 55 | + the format `https://<region>.monitoring.azure.com`. The following regions |
| 56 | + are currently known to be supported: |
| 57 | + - East US (eastus) |
| 58 | + - West US 2 (westus2) |
| 59 | + - South Central US (southcentralus) |
| 60 | + - West Central US (westcentralus) |
| 61 | + - North Europe (northeurope) |
| 62 | + - West Europe (westeurope) |
| 63 | + - Southeast Asia (southeastasia) |
| 64 | + |
| 65 | +[resource provider]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-supported-services |
| 66 | +[enable msi]: https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/qs-configure-portal-windows-vm |
| 67 | + |
| 68 | +### Region and Resource ID |
| 69 | + |
| 70 | +The plugin will attempt to discover the region and resource ID using the Azure |
| 71 | +VM Instance Metadata service. If Telegraf is not running on a virtual machine |
| 72 | +or the VM Instance Metadata service is not available, the following variables |
| 73 | +are required for the output to function. |
| 74 | + |
| 75 | +* region |
| 76 | +* resource_id |
| 77 | + |
| 78 | +### Authentication |
| 79 | + |
| 80 | +This plugin uses one of several different types of authenticate methods. The |
| 81 | +preferred authentication methods are different from the *order* in which each |
| 82 | +authentication is checked. Here are the preferred authentication methods: |
| 83 | + |
| 84 | +1. Managed Service Identity (MSI) token |
| 85 | + - This is the prefered authentication method. Telegraf will automatically |
| 86 | + authenticate using this method when running on Azure VMs. |
| 87 | +2. AAD Application Tokens (Service Principals) |
| 88 | + - Primarily useful if Telegraf is writing metrics for other resources. |
| 89 | + [More information][principal]. |
| 90 | + - A Service Principal or User Principal needs to be assigned the `Monitoring |
| 91 | + Contributor` roles. |
| 92 | +3. AAD User Tokens (User Principals) |
| 93 | + - Allows Telegraf to authenticate like a user. It is best to use this method |
| 94 | + for development. |
| 95 | + |
| 96 | +[principal]: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-application-objects |
| 97 | + |
| 98 | +The plugin will authenticate using the first available of the |
| 99 | +following configurations: |
| 100 | + |
| 101 | +1. **Client Credentials**: Azure AD Application ID and Secret. |
| 102 | + |
| 103 | + Set the following Telegraf configuration variables: |
| 104 | + |
| 105 | + - `azure_tenant_id`: Specifies the Tenant to which to authenticate. |
| 106 | + - `azure_client_id`: Specifies the app client ID to use. |
| 107 | + - `azure_client_secret`: Specifies the app secret to use. |
| 108 | + |
| 109 | + Or set the following environment variables: |
| 110 | + |
| 111 | + - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. |
| 112 | + - `AZURE_CLIENT_ID`: Specifies the app client ID to use. |
| 113 | + - `AZURE_CLIENT_SECRET`: Specifies the app secret to use. |
| 114 | + |
| 115 | +2. **Client Certificate**: Azure AD Application ID and X.509 Certificate. |
| 116 | + |
| 117 | + - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. |
| 118 | + - `AZURE_CLIENT_ID`: Specifies the app client ID to use. |
| 119 | + - `AZURE_CERTIFICATE_PATH`: Specifies the certificate Path to use. |
| 120 | + - `AZURE_CERTIFICATE_PASSWORD`: Specifies the certificate password to use. |
| 121 | + |
| 122 | +3. **Resource Owner Password**: Azure AD User and Password. This grant type is |
| 123 | + *not recommended*, use device login instead if you need interactive login. |
| 124 | + |
| 125 | + - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. |
| 126 | + - `AZURE_CLIENT_ID`: Specifies the app client ID to use. |
| 127 | + - `AZURE_USERNAME`: Specifies the username to use. |
| 128 | + - `AZURE_PASSWORD`: Specifies the password to use. |
| 129 | + |
| 130 | +4. **Azure Managed Service Identity**: Delegate credential management to the |
| 131 | + platform. Requires that code is running in Azure, e.g. on a VM. All |
| 132 | + configuration is handled by Azure. See [Azure Managed Service Identity][msi] |
| 133 | + for more details. Only available when using the [Azure Resource Manager][arm]. |
| 134 | + |
| 135 | +[msi]: https://docs.microsoft.com/en-us/azure/active-directory/msi-overview |
| 136 | +[arm]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview |
| 137 | + |
| 138 | +**Note: As shown above, the last option (#4) is the preferred way to |
| 139 | +authenticate when running Telegraf on Azure VMs. |
0 commit comments