[receiver/azureeventhub] Implements support to ingest app metrics

.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.