> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/azure-event-hub.md).

# Azure Event Hub

## Prerequisites

The source must have access to an Azure Event Hub with the necessary permissions, the minimum permission being `Listen`. You can authenticate with either a connection string or an [Azure identity](#authenticate-with-an-azure-identity). You can configure resources' Diagnostic settings to send logs to the Azure Event Hub. Read more here: [Azure Event Hub](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/diagnostic-settings).

Each event hub should only accept one telemetry type.

To use [Distributed Consumption](https://docs.bindplane.com/~/changes/409/integrations/sources/azure-event-hub#distributed-consumption), you also need an Azure Blob Storage account and an existing container that all participating collectors can read and write to.

## Supported Platforms

Bindplane Collector: `v1.39.0`+ (basic configuration)

Bindplane Collector: `v1.97.0`+ (distributed consumption, polling controls)

Bindplane Collector: `v1.101.1`+ (Azure identity authentication)

| Platform            | Metrics | Logs | Traces |
| ------------------- | ------- | ---- | ------ |
| Linux               | ✓       | ✓    |        |
| Windows             | ✓       | ✓    |        |
| macOS               | ✓       | ✓    |        |
| Kubernetes Cluster  | ✓       | ✓    |        |
| OpenShift 4 Cluster | ✓       | ✓    |        |

## Configuration

<table><thead><tr><th width="240">Field</th><th>Description</th></tr></thead><tbody><tr><td>Telemetry Type</td><td>The type of telemetry to gather with this receiver. Only one telemetry type should be sent to a given event hub.</td></tr><tr><td>Use Azure Identity Authentication</td><td>Authenticate using an Azure identity (managed identity, workload identity, or service principal) instead of a connection string. Defaults to off. See <a href="#authenticate-with-an-azure-identity">Authenticate with an Azure Identity</a>.</td></tr><tr><td>Event Hub Name</td><td>Name of the event hub to read from. Required when Azure identity authentication is enabled.</td></tr><tr><td>Event Hub Namespace</td><td>Fully qualified Event Hubs namespace, e.g. <code>my-namespace.servicebus.windows.net</code>. Required when Azure identity authentication is enabled.</td></tr><tr><td>Authentication Type</td><td>The Azure identity method used to authenticate. Only used when Azure identity authentication is enabled.</td></tr><tr><td>Connection</td><td>A string describing the connection to an Azure event hub. Used when Azure identity authentication is disabled.</td></tr><tr><td>Consumer Group</td><td>The Consumer Group to read from. Defaults to <code>$$Default</code>. Dollar signs must be escaped with another dollar sign.</td></tr><tr><td>Partition</td><td>The partition to watch. If empty, it will watch all partitions. Ignored when Distributed Consumption is enabled.</td></tr><tr><td>Offset</td><td>The offset at which to start watching the event hub. If empty, starts with the latest offset. If <code>-1</code>, starts at the beginning. Ignored when Distributed Consumption is enabled.</td></tr><tr><td>Log Format</td><td>The log format to use when parsing logs from Event Hub. Must be one of <code>azure</code> or <code>raw</code>. Raw logs are byte encoded, see the "Raw Encoding" option.</td></tr><tr><td>Raw Encoding</td><td>The encoding used when decoding the raw logs into human readable text. Defaults to <code>utf-8</code>. The raw byte encoding can be preserved by selecting <code>byte</code>.</td></tr></tbody></table>

**Advanced Configuration**

<table><thead><tr><th width="280">Field</th><th>Description</th></tr></thead><tbody><tr><td>Max Poll Events</td><td>Maximum number of events to retrieve per poll. Increase to improve throughput. Defaults to <code>100</code>.</td></tr><tr><td>Poll Rate (seconds)</td><td>Maximum seconds to wait before returning fewer than Max Poll Events. Lower values reduce latency; higher values can improve batch efficiency. Defaults to <code>5</code>.</td></tr><tr><td>Enable Distributed Consumption</td><td>Coordinate partition ownership across multiple collector instances using an Azure Blob Storage checkpoint store. Mutually exclusive with Partition and Offset.</td></tr><tr><td>Checkpoint Store Connection String</td><td>Connection string for the Azure Blob Storage account used for checkpoint coordination. Required when Distributed Consumption is enabled and Azure identity authentication is disabled.</td></tr><tr><td>Checkpoint Store Storage Account URL</td><td>Blob service URL of the storage account used for checkpoint coordination, e.g. <code>https://myaccount.blob.core.windows.net</code>. Required when Distributed Consumption and Azure identity authentication are both enabled. The Azure identity must have access to the container.</td></tr><tr><td>Checkpoint Store Container Name</td><td>Blob container used for checkpoint data. The container must already exist before starting the collector. Required when Distributed Consumption is enabled.</td></tr></tbody></table>

### Example Configuration

**Basic Configuration**

For basic configuration, the `connection` parameter is required. Optionally, specify `consumer group`, `partition`, and `offset`.

**Web Interface**

<figure><img src="/files/BN91n4uMboeYujsF4HNX" alt=""><figcaption></figcaption></figure>

**Standalone Source**

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: azure_event_hub
  name: azure_event_hub
spec:
  type: azure_event_hub
  parameters:
    - name: telemetry_types
      value: Logs
    - name: connection
      value: '<your_connection_string>'
    - name: group
      value: '$$Default' # optional, defaults to $$Default
    - name: partition
      value: '' # optional, watches all partitions when empty
    - name: offset
      value: '' # optional, starts at latest when empty
    - name: format
      value: raw # azure or raw
    - name: raw_encoding
      value: utf-8 # only applies when format is raw
```

### **Distributed Consumption**

When running multiple collector instances against the same event hub, enable Distributed Consumption to coordinate partition ownership through an Azure Blob Storage container. Each partition is leased to a single collector at a time, and ownership rebalances automatically as collectors are added or removed. Progress is checkpointed to the same container, so collectors resume from where they left off after a restart.

The blob container must already exist before starting the collector, and every participating collector must use the same Consumer Group and container. Distributed Consumption is mutually exclusive with the `Partition` and `Offset` fields.

**Standalone Source**

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: azure_event_hub
  name: azure_event_hub
spec:
  type: azure_event_hub
  parameters:
    - name: telemetry_types
      value: Logs
    - name: connection
      value: '<your_connection_string>'
    - name: group
      value: '$$Default'
    - name: enable_distributed_consumption
      value: true
    - name: blob_checkpoint_store_connection
      value: '<your_blob_storage_connection_string>'
    - name: blob_checkpoint_store_container_name
      value: 'eventhub-checkpoints'
```

### **Tuning Throughput**

Use `Max Poll Events`, `Poll Rate`, and `Prefetch Count` to balance latency, memory usage, and batch efficiency.

* `Max Poll Events` / `Poll Rate` - Higher values increase batch size and throughput but also increase event latency. Lower values reduce per-event latency at the cost of smaller batches.
* `Prefetch` - When `Enable Prefetching` is on (default), the receiver buffers events from the Event Hub before processing. Increasing `Prefetch Count` (default 300) can improve throughput under heavy load but increases memory consumption.

▎ Prefetching requires Bindplane Collector `v1.100.0` or newer.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: azure_event_hub
  name: azure_event_hub
spec:
  type: azure_event_hub
  parameters:
    - name: telemetry_types
      value: Logs
    - name: connection
      value: '<your_connection_string>'
    - name: max_poll_events
      value: 500
    - name: poll_rate
      value: 2
    - name: enable_prefetch
      value: true
    - name: prefetch_count
      value: 300
```

### Authenticate with an Azure Identity

Instead of a connection string, the Event Hub source can authenticate with an Azure identity. Enable **Use Azure Identity Authentication**, provide the **Event Hub Name** and **Event Hub Namespace**, then choose an authentication method. The identity must have at least the `Listen` permission on the event hub, and read/write access to the checkpoint container when Distributed Consumption is enabled.

| Authentication Method | Description                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Managed Identity      | Use an Azure managed identity. Leave Client ID empty to use the system-assigned identity, or set it to use a user-assigned identity.                              |
| Workload Identity     | Use Azure AD workload identity federation, typically on Kubernetes. Requires the application Client ID, Tenant ID, and the path to the projected federated token. |
| Service Principal     | Authenticate as a service principal using either a client secret or a client certificate.                                                                         |

The authentication method is configured through the `auth_extension` parameter. The parameters below apply to the method you choose:

<table><thead><tr><th width="300">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>auth_method</td><td>One of <code>Managed Identity</code>, <code>Workload Identity</code>, or <code>Service Principal</code>.</td></tr><tr><td>managed_identity_client_id</td><td>Managed Identity only. Client ID of the user-assigned managed identity. Leave empty to use the system-assigned identity.</td></tr><tr><td>workload_identity_client_id</td><td>Workload Identity only. Client ID of the Azure AD application.</td></tr><tr><td>workload_identity_tenant_id</td><td>Workload Identity only. Tenant ID of the Azure AD application.</td></tr><tr><td>workload_identity_token_file</td><td>Workload Identity only. Path to the file containing the federated token, typically projected into the pod by the Azure Workload Identity webhook.</td></tr><tr><td>service_principal_client_id</td><td>Service Principal only. Client ID of the service principal.</td></tr><tr><td>service_principal_tenant_id</td><td>Service Principal only. Tenant ID of the service principal.</td></tr><tr><td>service_principal_credential_type</td><td>Service Principal only. Whether to authenticate with a <code>Client Secret</code> or a <code>Client Certificate</code>.</td></tr><tr><td>service_principal_client_secret</td><td>Service Principal only. Client secret of the service principal. Used when the credential type is <code>Client Secret</code>.</td></tr><tr><td>service_principal_certificate_path</td><td>Service Principal only. Path to the client certificate. Used when the credential type is <code>Client Certificate</code>.</td></tr><tr><td>scopes</td><td>Optional. Custom token scopes to request, e.g. <code>https://monitor.azure.com/.default</code>. Leave empty to use the default scope for the target service.</td></tr></tbody></table>

**Web Interface**

<figure><img src="/files/DZoavHGwnAMuxVriC8VB" alt=""><figcaption></figcaption></figure>

**Standalone Source**

This example authenticates with a user-assigned managed identity.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: azure_event_hub
  name: azure_event_hub
spec:
  type: azure_event_hub
  parameters:
    - name: telemetry_types
      value: Logs
    - name: enable_external_auth
      value: true
    - name: event_hub_name
      value: my-hub
    - name: event_hub_namespace
      value: my-namespace.servicebus.windows.net
    - name: auth_extension
      value:
        type: azure_auth
        parameters:
          - name: auth_method
            value: managed_identity
          - name: managed_identity_client_id
            value: '11111111-2222-3333-4444-555555555555' # optional, omit for the system-assigned identity
    - name: group
      value: '$$Default'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/azure-event-hub.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.