[receiver/azureeventhub] Implements support to ingest app metrics (#41367)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

* Extends the metrics unmarshaler with support for parsing metrics with
type "AppMetrics" forwarded from Application Insights
* Moves the appending of attributes into each record, as if there could
be records from multiple resources within the same payload
* Implements an optional average aggregator, configured in the component
config

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue

Fixes
#41343

<!--Describe what testing was performed and which tests were added.-->
#### Testing

Tests added for the parsing of both resource and app metrics.

Maybe not of value for you, but tested in my development environment in
Azure, receiving metrics from remote tenants and exporting to a managed
prometheus data collection rule using the Prometheus remote writer
exporter.

<!--Describe the documentation added.-->
#### Documentation

I'm happy to extend the documentation if this code and feature is of any
interest

<!--Please delete paragraphs that you did not use before submitting.-->

---------

Co-authored-by: Antoine Toulme <[email protected]>

Author: spurge

.chloggen/feature_azureeventhub-appmetrics.yaml

@@ -0,0 +1,31 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: receiver/azureeventhub
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Adds support for receiving Azure app metrics from Azure Event Hubs in the azureeventhubreceiver"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues:
+  - 41343
+  - 41367
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  The azureeventhubreceiver now supports receiving custom metrics emitted by applications to Azure Insights and forwarded using Diagnostic Settings to Azure Event Hub.
+  There's also on optional setting to aggregate received metrics into a single metric to keep the original name, instead of multiply the metrics by added suffixes `_total`, `_sum`, `_max` etc.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/azureeventhubreceiver/README.md

@@ -15,11 +15,17 @@
 <!-- end autogenerated section -->
 
 ## Overview
+
 Azure resources and services can be
 [configured](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/diagnostic-settings)
-to send their logs to an Azure Event Hub. The Azure Event Hub receiver pulls logs from an Azure
+to send their telemetry to an Azure Event Hub. The Azure Event Hub receiver pulls telemetry from an Azure
 Event Hub, transforms them, and pushes them through the collector pipeline.
 
+### Read further
+
+* [Diagnostic settings in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/platform/diagnostic-settings?tabs=portal)
+* [Stream Azure monitoring data to an event hub and external partner](https://learn.microsoft.com/en-us/azure/azure-monitor/platform/stream-monitoring-data-event-hubs)
+
 ## Configuration
 
 ### connection (Required)
@@ -58,6 +64,21 @@ All supported time format for logs, metrics and traces. Default is `nil` (unset)
 
 Default: `nil`
 
+### metric_aggregation (optional)
+
+Metric records received from an Azure Event Hub will contain multiple aggregated datapoints. Depending on the
+[type of metric](https://learn.microsoft.com/en-us/azure/azure-monitor/metrics/data-platform-metrics#types-of-metrics),
+these datapoints will be slightly different, but all contain a total/sum, min, max and count. This setting will manage
+these datapoints.
+
+#### Possible values:
+
+* By default, these datapoints will be mapped to metrics named with a corresponding suffix, like `_total`, `_min`, etc.
+  See [azure format](#azure).
+* With `average`, datapoints will be aggregated into an average value (`sum/count`), and keep the original metric name.
+
+Default: `nil`
+
 > [!NOTE]
 > You can opt-in to use the [`azeventhubs`](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/messaging/azeventhubs) sdk by enabling the feature gate
 > `receiver.azureeventhubreceiver.UseAzeventhubs` when you run the OpenTelemetry Collector. See the following page
@@ -102,10 +123,13 @@ The "raw" format maps the AMQP properties and data into the
 attributes and body of an OpenTelemetry LogRecord, respectively.
 The body is represented as a raw byte array.
 
-This format is not supported for Metrics.
+> [!WARN]
+> This format is not supported for Metrics.
 
 ### azure
 
+#### Logs
+
 The "azure" format extracts the Azure log records from the AMQP
 message data, parses them, and maps the fields to OpenTelemetry
 attributes. The table below summarizes the mapping between the 
@@ -137,8 +161,18 @@ Notes:
 * JSON does not distinguish between fixed and floating point numbers. All
 JSON numbers are encoded as doubles.
 
+#### Metrics
+
 For Metrics the Azure Metric Records are an array
-of "records" with the following fields.
+of "records" with the following fields, by
+[type of metric](https://learn.microsoft.com/en-us/azure/azure-monitor/metrics/data-platform-metrics#types-of-metrics).
+
+From this data a Metric of type Gauge is created
+with a Data Points that represents the values
+for the Metric including: Total, Minimum, Maximum,
+Average and Count.
+
+##### Platform metric (from Azure resources)
 
 | Azure      | Open Telemetry                              |
 |------------|---------------------------------------------|
@@ -152,10 +186,28 @@ of "records" with the following fields.
 | maximum    | mapped to datapoint metricName + "_MAXIMUM" |
 | average    | mapped to datapoint metricName + "_AVERAGE" |
 
-From this data a Metric of type Gauge is created
-with a Data Points that represents the values
-for the Metric including: Total, Minimum, Maximum,
-Average and Count.
+##### Application metrics (from Application Insights)
+
+See: https://learn.microsoft.com/en-us/azure/azure-monitor/reference/tables/appmetrics
+
+| Azure                      | Open Telemetry                              |
+|----------------------------|---------------------------------------------|
+| time                       | time_unix_nano (field)                      |
+| resourceId                 | azure.resource.id (resource attribute)      |
+| Name                       | (metric name)                               |
+| AppRoleInstance            | service.instance.id (resource attribute)    |
+| AppRoleName                | service.name (resource attribute)           |
+| AppVersion                 | service.version (resource attribute)        |
+| SDKVersion                 | telemetry.sdk.version (resource attribute)  |
+| ClientCountryOrRegion      | cloud.region (resource attribute)           |
+| ClientOS                   | os.name (resource attribute)                |
+| Properties (key/value map) | mapped to resource attributes               |
+| Sum                        | mapped to datapoint metricName + "_TOTAL"   |
+| ItemCount                  | mapped to datapoint metricName + "_COUNT"   |
+| Min                        | mapped to datapoint metricName + "_MINIMUM" |
+| Max                        | mapped to datapoint metricName + "_MAXIMUM" |
+
+#### Traces
 
 Traces based on Azure Application Insights array of records from `AppRequests` & `AppDependencies` with the following fields.