CREATING AN AZURE EVENT HUBS CONNECTION

This page explains how to create an Azure Event Hubs namespace and event hub, then connect it to ThingPark X IoT Flow through the Apache Kafka endpoint. The Azure resources in the screenshots are examples. Use a non-production namespace for testing and remove it when it is no longer needed.

Azure Event Hubs uses the following concepts:

Azure concept	Kafka equivalent	Role in IoT-Flow
Namespace	Kafka cluster	Provides the service endpoint and controls the namespace tier and capacity.
Event hub	Topic	Stores the event stream. Configure separate event hubs for uplinks and downlinks when the integration requires it.
Partition	Partition	Enables parallel publishing and consumption. Ordering is preserved within a partition, not across the whole event hub.
Consumer group	Consumer group	Provides an independent view of an event stream for a set of consumers.

For current service limits and pricing, see the Azure Event Hubs quotas and limits, Event Hubs features and terminology, and Event Hubs pricing.

Creating the Azure resources

Create or select a namespace

1. Open the Azure Portal.
2. Create an Event Hubs namespace, or select an existing non-production namespace. Choose a tier that supports the Apache Kafka endpoint. Basic tier does not support Apache Kafka.
3. Review the region and namespace tier. In the Standard tier, namespace capacity is measured in Throughput Units (TUs). Premium uses Processing Units (PUs), and Dedicated uses Capacity Units (CUs).
4. Review the namespace overview. The namespace provides the hostname used by the IoT-Flow connector.

Create an event hub

1. Open the namespace and select Event Hubs.
2. Select Create, enter an event hub name, and choose the partition count.
3. Set the retention period required by the integration, then create the event hub.

The partition count is a scaling and concurrency decision. Choose enough partitions for the expected peak workload and consumer parallelism, but do not increase the count solely because more partitions are available. In Standard tier, the partition count cannot be changed after creation; Premium and Dedicated support increasing the count, but not decreasing it. Increasing partitions can also change partition-key mapping, so avoid changing it when application ordering depends on that mapping.

The example event hub has one partition. The partition count is visible on the event hub overview page after creation.

Configure a consumer group

Each independent application or processing pipeline should use its own consumer group. IoT-Flow uses the event hub name as the Kafka topic and manages its Kafka consumer group as part of the connection runtime. Do not reuse a consumer group for unrelated consumers that must track the stream independently.

Create a shared access policy

Create a SAS policy scoped to the namespace or, preferably, to the event hub when the required access is limited to one hub. Do not use the root management policy for a production integration.

• Send is required for uplinks sent to Azure.
• Listen is required when downlinks are consumed from Azure. It is not required when downlink processing is disabled.
• Manage is not required by the IoT-Flow connector.

Copy the policy name and key only into the protected connector configuration. Never commit keys, connection strings, or tokens to documentation, source control, or screenshots.

Collecting the IoT-Flow connection parameters

The Azure Event Hubs connector uses the Kafka-compatible endpoint:

UI field	Description
Hostname	The namespace hostname followed by the Kafka TLS port, for example my-namespace.servicebus.windows.net:9093.
Shared access key name	The name of the SAS policy.
Shared access key	The secret key for the SAS policy. Do not expose it in screenshots or source control.
Uplinks Event Hubs Instance	The event hub name used as the uplink Kafka topic.
Downlinks Event Hubs Instance	The event hub name used as the downlink Kafka topic, when downlinks are enabled.

Azure Event Hubs maps event hubs to Kafka topics. The hostname identifies the namespace; the uplink and downlink event hub names identify the streams within that namespace.

Creating a connection from the UI

1. In IoT-Flow, select Connections, Create, and then ThingPark X IoT Flow.
2. Select Azure Event Hubs.
3. Enter the hostname, SAS policy name, SAS key, and uplink event hub name. Enter the downlink event hub name when downlinks are enabled.
4. Create the connection and verify its status in the connection details.

The following example shows the completed form. The key is intentionally redacted; replace it with the protected value from the Azure SAS policy when configuring your own connection.

The connector uses port 9093 because IoT-Flow connects to Azure Event Hubs through the Kafka protocol over TLS.

Creating a connection with the API

The connection API requires the complete configuration when creating or updating a connection. Use a secret-management mechanism for the SAS key.

POST /connections
{
    "connectorId": "actility-azure-event-hub",
    "name": "My Azure Event Hubs Connection",
    "configuration": {
        "hostName": "my-namespace.servicebus.windows.net:9093",
        "sharedAccessKeyName": "IoTFlowSendListen",
        "sharedAccessKey": "<secret>",
        "uplinkTopicPattern": "my-uplink-event-hub",
        "downlinkTopicPattern": "my-downlink-event-hub"
    }
}

JSON field	Description
connectorId	Must be actility-azure-event-hub.
hostName	The Azure Event Hubs namespace hostname and Kafka port.
sharedAccessKeyName	The SAS policy name.
sharedAccessKey	The SAS policy secret.
uplinkTopicPattern	The event hub name used for uplinks.
downlinkTopicPattern	The event hub name used for downlinks.

Scaling and capacity

Throughput Units

Throughput Units are namespace-level capacity units for the Basic and Standard tiers. They are not a per-event-hub connector setting and are not supplied in the IoT-Flow connection payload. In the current Azure limits documentation, one TU provides up to 1 MB/s or 1,000 events/s ingress and 2 MB/s or 4,096 events/s egress, whichever limit is reached first. The effective workload also depends on event size, batching, partitions, tier, region, and other namespace limits.

Standard namespaces can use Auto-Inflate to increase TUs when the configured limit is reached. Premium namespaces use PUs, and Dedicated clusters use CUs; their capacity model is different. Always validate the current limits and pricing for the selected tier before sizing a production integration.

For a first estimate, calculate both the byte rate and event rate for ingress and egress, then compare each with the applicable namespace and partition limits. Include protocol overhead and headroom for bursts. Partition count improves parallelism, but it does not automatically increase the namespace's purchased capacity.

Effect on IoT-Flow

• More partitions can allow more Kafka consumers to process an event hub in parallel.
• Ordering is guaranteed only within a partition. A workload that needs ordering across all events should not be split across unrelated partitions.
• The uplink and downlink event hubs can be sized independently when they use separate streams.
• A larger partition count does not change the IoT-Flow connector fields and does not create an eventHubUnits setting in IoT-Flow.
• Monitor Azure namespace metrics and IoT-Flow connection state together. IoT-Flow's existing connection metrics are operational counters and Kafka lag; they are not Azure capacity utilization percentages.

Capacity information and 80% warning decision

The current IoT-Flow connector configuration contains the namespace hostname, SAS credentials, and event hub names, but not the Azure resource ID, namespace identity, tier capacity, or Azure Monitor authorization. The existing connection metrics therefore cannot calculate authoritative Azure throughput utilization, especially when several event hubs or connections share one namespace.

Consequently, this documentation does not present the existing bridge load or message counts as Azure capacity. A read-only capacity display and an 80% warning require a separate backend capability that can query Azure telemetry, aggregate usage at namespace scope, identify ingress and egress separately, and report timestamps plus stale or unavailable states. The UI implementation remains subject to that telemetry contract and product approval.

Troubleshooting

For service-specific errors, see Event Hubs messaging exceptions and Event Hubs frequently asked questions.

Connection uplink lost

If the connector reports an authentication or uplink error, verify the namespace hostname, the :9093 Kafka port, the SAS policy name, the SAS key, and the policy permissions. Regenerate the key if it may have been exposed.

Throughput or latency limitations

Check Azure namespace metrics and throttling indicators first. Confirm that the namespace tier and capacity match the ingress and egress workload, then review partition count and consumer-group assignments. Do not treat a partition count change as a replacement for increasing namespace capacity.

Verifying message flow with Visual Studio Code

The Azure Event Hub Explorer extension can be used to inspect an event hub during testing:

1. Install the Azure Event Hub Explorer extension in Visual Studio Code.
2. Use the command palette to select the event hub and start monitoring messages.
3. Confirm that the expected uplink or downlink events are visible.

This verifies message flow only. It does not replace Azure Monitor metrics or provide a capacity percentage.