Collector Configuration Manual for "Azure-Monitor Metric Collection"¶

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 are enabled 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 collection object configurations Multiple configurations under the same namespace have a logical relationship of "AND".
`targets[#].namespace`	str	Required	The cloud monitoring namespace (Azure resource type) to be collected. For example, VirtualMachines: `'Microsoft.Compute/virtualMachines'` Refer to the appendix for values.
`targets[#].metrics`	list	Required	List of cloud monitoring metric names to be collected Refer to the appendix for values.
`targets[#].metrics[#]`	str	Required	Metric name pattern, supports `"NOT"`, wildcard matching Normally, multiple metrics have a logical relationship of "OR". When `"NOT"` is included, multiple metrics have a logical relationship of "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, e.g., westus2

2. Configuration Examples¶

Specify Specific Metrics¶

Collect two metrics named CPU Credits Consumed and CPU Credits Remaining from VMs.

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

Wildcard Matching for Metrics¶

Metric names can be matched using the * wildcard.

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 the "NOT" tag at the beginning indicates that the following metrics should 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 Specifying Required Metrics¶

The same namespace can be specified multiple times, and the metric names are filtered sequentially from top to bottom.

In this example, the metric names are filtered as follows:

Select all metrics whose names contain CPU.
From the results of the previous step, 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 based on object attributes. The filter function returns True or False.

True: The target resource should be collected.
False: The target resource should not be collected.

# Example: Enable the filter to filter based on the resourceId attribute. The configuration format is 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. Here is an example using Microsoft.Compute/virtualMachines: 1. namespace is the namespace, which is the Microsoft cloud product resource type (case-insensitive), with the value: "Microsoft.Compute/virtualMachines".

metrics is the list of metrics to be collected. Refer to Metrics Supported by Microsoft.Compute/virtualMachines for the "Name in REST API" column, with values: ["Available Memory Bytes", "CPU Credits Consumed"].

4. Data Reporting Format¶

After data is successfully synchronized, you can view the data 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 in advance 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 usually placed at the end.
    ]

When a match is successful, the fields from the tags of the 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 for some API calls (currently: query API free tier limit is 1 million calls/month, exceeding this limit costs $0.01 per 1000 calls). The /{resourceUri}/providers/Microsoft.Insights/metrics used by this collector is also within this limit. The following explains the script set call count in detail:

1. The user has multiple resources and needs to collect various monitoring items. Will the free tier limit be exceeded?

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

2. Check the actual call count by viewing the task execution log:

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

[2023-10-24 14:31:53.203] [+6569ms] The [1] account collection is complete, took [16784 ms], and called APIs [2 times].
[2023-10-24 14:31:53.203] [+6569ms] Detailed calls are 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

Due to the free tier limit for cloud monitoring API calls, it is recommended that users configure monitoring items as needed to avoid additional costs caused by wildcard matching.

Precautions¶

Common Errors and Solutions¶

X. Appendix¶

Azure Related Documents: