Collector "Azure-Monitor Metric Collection" Configuration Manual¶

Before reading this document, please read:

Cloud Integration

Tip

Before using this collector, you must install "Integration Core" and its accompanying third-party dependencies.

Tip

This collector supports multi-threading by default (five threads by default). If you need to change the thread pool size, you can set the environment variable COLLECTOR_THREAD_POOL_SIZE.

1. Configuration Structure¶

The configuration structure of this collector is as follows:

Field	Type	Required	Description
`targets`	list	Required	List of cloud monitoring target configurations The logical relationship between multiple configurations in the same namespace is "AND".
`targets[#].namespace`	str	Required	The cloud monitoring namespace (Azure resource type) to be collected. Example for VirtualMachines: `'Microsoft.Compute/virtualMachines'` Refer to the appendix for values.
`targets[#].metrics`	list	Required	List of cloud monitoring Metrics names to be collected Refer to the appendix for values.
`targets[#].metrics[#]`	str	Required	Metric name pattern, supports `"NOT"`, wildcard matching Normally, the logical relationship between multiple Metrics is "OR". When `"NOT"` is included, the logical relationship between multiple Metrics is "AND". See below for details.
`subscriptions`	list	Optional	List of subscription IDs to be collected.
`subscriptions[#]`	str		Subscription ID
`locations`	list	Optional	List of regions.
`locations[#]`	str		Region, example: westus2
## 2. Configuration Examples

Specify Specific Metrics¶

Collect two Metrics named CPU Credits Consumed and CPU Credits Remaining in VM.

collector_configs = {
    'targets': [
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : ['CPU Credits Consumed', 'CPU Credits Remaining'],
        },
    ],
}

Wildcard Matching for Metrics¶

Metric names can use the * wildcard for matching.

In this example, the following Metrics will be collected:

Metric named CPU Credits Consumed
Metrics starting with CPU
Metrics ending with Remaining
Metrics containing IOPS

collector_configs = {
    'targets': [
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : ['CPU Credits Consumed', 'CPU*', '*Remaining', '*IOPS*'],
        },
    ],
}

Exclude Specific Metrics¶

Adding "NOT" at the beginning indicates the Metrics to be excluded.

In this example, the following Metrics will [not] be collected:

Metric named CPU Credits Consumed
Metrics starting with CPU
Metrics ending with Remaining
Metrics containing IOPS

collector_configs = {
    'targets': [
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : ['NOT', 'CPU Credits Consumed', 'CPU*', '*Remaining', '*IOPS*'],
        },
    ],
}

Multiple Filters for Required Metrics¶

The same namespace can be specified multiple times, and the Metrics will be filtered step by step from top to bottom.

In this example, the following filtering steps are performed on the Metric names:

Select all Metrics containing CPU in their names.
From the previous result, exclude the Metric named CPU Credits Consumed.

collector_configs = {
    'targets': [
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : ['*CPU*'],
        },
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : ['NOT', 'CPU Credits Consumed'],
        },
    ],
}

Configure Filters (Optional)¶

This collector script supports user-defined filters to allow users to filter target resources by object attributes. The filter function returns True or False.

True: The target resource needs to be collected.
False: The target resource does not need to be collected.

When custom object collection is enabled, more object attributes will be supported for filtering. Please refer to the corresponding product's custom object collector documentation for details.

# Example: Enable filter to filter by resourceId attribute, configuration format as follows:

def filter_metrics(instance, namespace='Microsoft.Compute/virtualMachines'):
    '''
    Collect Metrics for resources with resource IDs /subscriptions/xxxx/xxx1, /subscriptions/xxxx/xxx2
    '''
    resource_id = instance['tags'].get('resourceId')
    if resource_id in ['/subscriptions/xxxx/xxx1', '/subscriptions/xxxx/xxx2']:
        return True
    return False

from integration_core__runner import Runner
import integration_azure_monitor__main as main

@DFF.API('Azure-Monitor Metric Collection', timeout=3600, fixed_crontab="*/5 * * * *")
def run():
    Runner(main.DataCollector(account, collector_configs, filters=[filter_metrics])).run()

Tip

When multiple filters are configured under the same namespace, all filters must be satisfied for the data to be reported.

3. Data Collection Explanation¶

Cloud Product Configuration Information¶

Cloud product configuration includes two necessary parameters: namespace and metrics. Below is an example using Microsoft.Compute/virtualMachines: 1. namespace Namespace, the namespace is the Microsoft cloud product resource type (case-insensitive), value: "Microsoft.Compute/virtualMachines".

metrics List of Metrics to be collected, refer to Metrics Supported by Microsoft.Compute/virtualMachines "REST API Name" column, value: ["Available Memory Bytes", "CPU Credits Consumed"]

4. Data Reporting Format¶

After data is successfully synchronized, it can be viewed in the "Metrics" section of Guance.

Take the following collector configuration as an example:

collector_configs = {
    'targets': [
        {
            'namespace': 'Microsoft.Compute/virtualMachines',
            'metrics'  : ['CPU*'],
        },
    ],
}

The reported data example is as follows:

{
  "measurement": "azure_compute_virtualmachines",
  "tags": {
    "location"       : "eastus",
    "resource_group" : "func-resource",
    "resource_id"    : "/subscriptions/xxxx/xxx1",
    "subscription_id": "63a4a998-bd43-4cca-bd86-c4e7ed33a643",
    "tenant_id"      : "ce9fe5b4-ba02-4c9a-b54e-f0bbff18579c",
    "unit"           : "Count"
  },
  "fields": {
    "cpu_credits_consumed_average" : 0.0,
    "cpu_credits_remaining_average": 98.97
  }
}

Tip

All Metric values will be reported as float type.

Tip

Since Azure's original data field key naming does not follow a unified standard, the collector will convert them to lowercase with underscores when reporting.

5. Interaction with Custom Object Collectors¶

When other custom object collectors (such as VirtualMachines) are running in the same DataFlux Func, this collector will automatically try to match the tags.name field in the custom object based on fields like tags.resourceId (the tags.name field in the custom object is taken from resourceId).

Since custom object information needs to be known first for interaction in cloud monitoring collectors, it is generally recommended to place cloud monitoring collectors at the end of the list, such as:

    # Create collectors
    collectors = [
        azure_vm.DataCollector(account, common_azure_configs),
        azure_monitor.DataCollector(account, monitor_collector_configs), # Cloud monitoring collectors are generally placed at the end.
    ]

When a successful match is made, the fields from the tags of the matched custom object will be added to the tags of the monitoring data. The specific effect is as follows:

Assume the original data collected by cloud monitoring is as follows:

{
  "measurement"  : "azure_compute_virtualmachines",
  "tags": {
    "resource_id": "/subscriptions/xxxx/xxx1",
    "unit"       : "Count",
    "{key}"   : "{value}"
  },
  "fields": {
    "{metric}"      : "{metric_value}"
  }
}

At the same time, the custom object data collected by the Microsoft cloud VM collector is as follows:

{
  "measurement": "azure_compute_virtualmachines",
  "tags": {
    "name"          : "/subscriptions/xxxx/xxx1",
    "resource_id"   : "/subscriptions/xxxx/xxx1",
    "power_state"   : "running",
    "computer_name" : "test_vm",
    "zone"          : "1",
    "{key}"     : "{value}"
  },
  "fields": {
    "{key}": "{value}"
  }
}

Then, the final reported cloud monitoring data is as follows:

{
"measurement": "azure_compute_virtualmachines",
  "tags": {
    "name"          : "/subscriptions/xxxx/xxx1",
    "resource_id"    : "/subscriptions/xxxx/xxx1",
    "power_state"    : "running",
    "computer_name"  : "test_vm",
    "zone"          : "1",
    "unit"          : "Count",
    "{key}"   : "{value}"
  },
  "fields": {
    "{metric}": "{metric_value}"
  }
}

6. Cloud Monitoring API Call Count Explanation¶

Azure monitoring has a free tier limit on the number of API calls for some APIs (currently: query API free tier limit is 1 million calls/month, excess charges $0.01 USD/thousand calls). The /{resourceUri}/providers/Microsoft.Insights/metrics used by this collector is also within this limit. Below is a detailed explanation of the script set call count:

1. User has multiple resources and needs to collect multiple monitoring items, how to determine if the free tier limit will be exceeded:

This collector uses /{resourceUri}/providers/Microsoft.Insights/metrics (query resource Metrics values) one request can obtain multiple monitoring items under a certain dimension of a resource (up to 20 monitoring items with the same timeGrain, exceeding requires another request).

2. View the actual call count in the task execution log:

The collector counts the API calls for each task execution result, which can be viewed in the log, example:

[2023-10-24 14:31:53.203] [+6569ms] The [1] account collection is completed, total execution time [16784 ms], API calls [2 times] during this period.
[2023-10-24 14:31:53.203] [+6569ms] Detailed calls as follows:
[2023-10-24 14:31:53.203] [+6569ms] -> management.azure.com/{resourceUri}/providers/microsoft.insights/metricdefinitions: 1 time
[2023-10-24 14:31:53.203] [+6569ms] -> management.azure.com/{resourceUri}/providers/microsoft.insights/metrics: 1 time

!!! warning "Given the free tier limit on cloud monitoring API calls, it is recommended that users configure monitoring items as needed to avoid additional costs caused by wildcard usage."

Notes¶

Common Errors and Solutions¶

X. Appendix¶

Azure related documents: