Azureeventhub Receiver

Available in: contrib Maintainers: @atoulme, @cparkins, @dyl10s Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Azure resources and services can be configured 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

Configuration

Connection Settings

Either connection or auth must be specified.

Field	Type	Required	Description
`connection`	string	Yes*	Connection string from the Azure portal. Ignored if `auth` is set.
`auth`	string	Yes*	ID of an authentication extension (AAD, managed identity, or service principal).
`event_hub.name`	string	**	Event Hub name. Required when using `auth`.
`event_hub.namespace`	string	**	Fully qualified namespace (e.g., `namespace.servicebus.windows.net`). Required when using `auth`.

* One of connection or auth is required.
** Required when using auth.

Consumer Settings

Field	Type	Required	Default	Description
`group`	string	No	`$Default`	Consumer group to read from.
`partition`	string	No	`""`	Specific partition to watch. If empty, watches all partitions.
`offset`	string	No	`""`	Starting offset. Only applicable when `partition` is set.
`storage`	string	No		ID of a storage extension for checkpoint persistence.

Distributed Consumption Settings

When blob_checkpoint_store is set, the receiver uses the Azure SDK Processor to coordinate partition ownership across multiple collector instances via Azure Blob Storage. This is mutually exclusive with partition, offset, and storage.

Field	Type	Required	Description
`blob_checkpoint_store.connection`	string	*	Azure Blob Storage connection string. Required when not using `auth`.
`blob_checkpoint_store.storage_account_url`	string	*	Blob service URL (e.g., `https://myaccount.blob.core.windows.net`). Required when using `auth`.
`blob_checkpoint_store.container_name`	string	Yes	Blob container for checkpoint data. Must already exist before starting the collector.

* One of connection or storage_account_url is required.

Polling Settings

Field	Type	Required	Default	Description
`max_poll_events`	int	No	`100`	Maximum events to retrieve per poll.
`poll_rate`	int	No	`5`	Maximum seconds to wait before returning fewer than `max_poll_events`.
`prefetch_count`	int	No	`0`	Size of the SDK’s per-partition prefetch buffer. The SDK fills this buffer asynchronously so `ReceiveEvents` calls return from a local cache instead of waiting on the network. `0` uses the SDK default (300). A negative value disables prefetch. Increase this when poll batches are draining the buffer faster than the SDK refills it.

Data Transformation Settings

Field	Type	Required	Default	Description
`format`	string	No	`azure`	Message format: `azure`, `raw`, or `""`. Mutually exclusive with `encoding`. See Format section.
`encoding`	string	No		ID of an encoding extension used to unmarshal the message body. Mutually exclusive with `format`. See Encoding section.
`apply_semantic_conventions`	bool	No	`false`	Translate Azure Resource Logs using OpenTelemetry semantic convention attribute names.
`time_formats.logs`	[]string	No		Custom time formats for logs. Uses Go time layout. Falls back to ISO8601.
`time_formats.metrics`	[]string	No		Custom time formats for metrics.
`time_formats.traces`	[]string	No		Custom time formats for traces.
`metric_aggregation`	string	No		Set to `average` to aggregate datapoints as `sum/count`. By default, creates separate metrics with suffixes (`_TOTAL`, `_MIN`, etc.).

Example Configuration

The simplest configuration uses a connection string from the Azure portal:

receivers:
  azure_event_hub:
    connection: Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<hub-name>
    group: $Default  # optional, defaults to $Default

The full list of settings exposed for this receiver are documented above with detailed sample configurations in testdata/config.yaml.

Advanced Configuration

Azure Auth Extension with Service Principal

receivers:
  azure_event_hub:
    event_hub:
      name: hubName
      namespace: namespace.servicebus.windows.net
    auth: azure_auth

extensions:
  azure_auth:
    service_principal:
      client_id: ${env:AZURE_CLIENT_ID}
      client_secret: ${env:AZURE_CLIENT_SECRET}
      tenant_id: ${env:AZURE_TENANT_ID}

Checkpoint Persistence with Storage Extension

This component can persist its state (checkpoint offsets) using the storage extension. This is strongly recommended for production deployments to prevent message reprocessing after collector restarts. Without a storage extension configured, the receiver will start from the latest offset on each restart, potentially missing messages that arrived while the collector was down.

receivers:
  azure_event_hub:
    connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
    storage: file_storage

extensions:
  file_storage:
    directory: /var/lib/otelcol/eventhub

Distributed Consumption with Blob Checkpoint Store

When blob_checkpoint_store is configured, the receiver automatically:

Coordinates partition ownership across collector instances via blob leases
Checkpoints progress to Azure Blob Storage
Rebalances partitions when instances are added or removed

Prerequisites:

The blob container must already exist before starting the collector
All collector instances must use the same consumer group and container

receivers:
  azure_event_hub:
    connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
    blob_checkpoint_store:
      connection: DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net
      container_name: eventhub-checkpoints

# With auth extension
receivers:
  azure_event_hub:
    event_hub:
      name: hubName
      namespace: namespace.servicebus.windows.net
    auth: azureauth
    blob_checkpoint_store:
      storage_account_url: https://myaccount.blob.core.windows.net
      container_name: eventhub-checkpoints

Custom Time Formats and Partitioning

receivers:
  azure_event_hub:
    connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
    partition: "0"
    group: my-consumer-group
    offset: "1234-5566"
    format: "azure"
    time_formats:
      logs: ["01/02/2006 15:04:05", "2006-01-02 15:04:05"]
      metrics: ["01/02/2006 15:04:05"]

Known Limitations

Before using this receiver, be aware of the following limitations:

Checkpoint Persistence

Without a configured storage extension, checkpoint state is stored only in memory. If the collector restarts, the receiver will resume from the latest offset, potentially missing messages or reprocessing already-consumed messages.

Format

raw

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.

[!WARNING] This format is only supported for Logs. Using raw format with Metrics or Traces pipelines will result in an error.

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 Azure common log format and the OpenTelemetry attributes.

Azure	OpenTelemetry
callerIpAddress (optional)	network.peer.address (attribute)
correlationId (optional)	azure.correlation.id (attribute)
category (optional)	azure.category (attribute)
durationMs (optional)	azure.duration (attribute)
Level (optional)	severity_number, severity_text (field)
location (optional)	cloud.region (attribute)
—	cloud.provider (attribute)
operationName (required)	azure.operation.name (attribute)
operationVersion (optional)	azure.operation.version (attribute)
properties or EventProperties (optional)	azure.properties (attribute, nested, `properties` takes precedence)
resourceId (required)	azure.resource.id (resource attribute)
resultDescription (optional)	azure.result.description (attribute)
resultSignature (optional)	azure.result.signature (attribute)
resultType (optional)	azure.result.type (attribute)
tenantId (required, tenant logs)	azure.tenant.id (attribute)
time, timeStamp, EventTimeString, EventTimestamp, startTime (required)	time_unix_nano (fields listed in order of precedence, with `time` having the highest precedence)
identity (optional)	azure.identity (attribute, nested)

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, by type of metric. 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
time	time_unix_nano (field)
resourceId	azure.resource.id (resource attribute)
metricName
timeGrain	start_time_unix_nano (field)
total	mapped to datapoint metricName + “_TOTAL”
count	mapped to datapoint metricName + “_COUNT”
minimum	mapped to datapoint metricName + “_MINIMUM”
maximum	mapped to datapoint metricName + “_MAXIMUM”
average	mapped to datapoint metricName + “_AVERAGE”

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.

Azure	Open Telemetry
Time	start_time(time_unix_nano(time))
	end_time(start_time + time_unix_nano(durationMs))
Name	span.name
OperationId	trace.id
ParentId	span.parentId
Id	span.id
AppRoleName	service.name

Encoding

As an alternative to the built-in format, the encoding option delegates unmarshaling of the message body to an encoding extension. This is mutually exclusive with format.

extensions:
  azure_encoding:

receivers:
  azure_event_hub:
    connection: Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<hub-name>
    encoding: azure_encoding

[!NOTE] The encoding extension only receives the message body. AMQP properties and enqueued time (which the raw format maps onto the LogRecord) are not applied on the encoding path. Use format: raw if you need those.

Configuration

Example Configuration

azure_event_hub:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName

azure_event_hub/missing_connection:

azure_event_hub/invalid_connection_string:
  connection: invalid

azure_event_hub/invalid_format:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  format: invalid

azure_event_hub/offset_without_partition:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  offset: "1234-5566"

azure_event_hub/offset_with_partition:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  partition: foo
  offset: "1234-5566"

azure_event_hub/auth:
  event_hub:
    name: hubName
    namespace: namespace.servicebus.windows.net
  auth: azureauth

azure_event_hub/auth_missing_event_hub_name:
  auth: azureauth
  event_hub:
    namespace: ns

azure_event_hub/auth_missing_namespace:
  auth: azureauth
  event_hub:
    name: hub

azure_event_hub/blob_checkpoint_store:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  blob_checkpoint_store:
    connection: DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net
    container_name: eventhub-checkpoints

azure_event_hub/blob_checkpoint_store_auth:
  event_hub:
    name: hubName
    namespace: namespace.servicebus.windows.net
  auth: azureauth
  blob_checkpoint_store:
    storage_account_url: https://myaccount.blob.core.windows.net
    container_name: eventhub-checkpoints

azure_event_hub/blob_checkpoint_store_missing_container:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  blob_checkpoint_store:
    connection: DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net

azure_event_hub/blob_checkpoint_store_missing_connection:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  blob_checkpoint_store:
    container_name: eventhub-checkpoints

azure_event_hub/blob_checkpoint_store_auth_missing_url:
  event_hub:
    name: hubName
    namespace: namespace.servicebus.windows.net
  auth: azureauth
  blob_checkpoint_store:
    container_name: eventhub-checkpoints

azure_event_hub/blob_checkpoint_store_with_partition:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  partition: "0"
  blob_checkpoint_store:
    connection: DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net
    container_name: eventhub-checkpoints

azure_event_hub/blob_checkpoint_store_with_storage:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  storage: file_storage
  blob_checkpoint_store:
    connection: DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net
    container_name: eventhub-checkpoints

azure_event_hub/encoding:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  encoding: azure_encoding

azure_event_hub/format_and_encoding:
  connection: Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=superSecret1234=;EntityPath=hubName
  format: raw
  encoding: azure_encoding

Last generated: 2026-08-24

​Azureeventhub Receiver

​Supported Telemetry

​Overview

​Overview

​Read further

​Configuration

​Connection Settings

​Consumer Settings

​Distributed Consumption Settings

​Polling Settings

​Data Transformation Settings

​Example Configuration

​Advanced Configuration

​Azure Auth Extension with Service Principal

​Checkpoint Persistence with Storage Extension

​Distributed Consumption with Blob Checkpoint Store

​Custom Time Formats and Partitioning

​Known Limitations

​Checkpoint Persistence

​Format

​raw

​azure

​Logs

​Metrics

Platform metric (from Azure resources)

Application metrics (from Application Insights)

​Traces

​Encoding

​Configuration

​Example Configuration

Azureeventhub Receiver

Supported Telemetry

Overview

Overview

Read further

Configuration

Connection Settings

Consumer Settings

Distributed Consumption Settings

Polling Settings

Data Transformation Settings

Example Configuration

Advanced Configuration

Azure Auth Extension with Service Principal

Checkpoint Persistence with Storage Extension

Distributed Consumption with Blob Checkpoint Store

Custom Time Formats and Partitioning

Known Limitations

Checkpoint Persistence

Format

raw

azure

Logs

Metrics

Traces

Encoding

Configuration

Example Configuration