Registry / azure / azure-eventhub-checkpointstoreblob

azure-eventhub-checkpointstoreblob

JSON →
library1.2.0pypypi✓ verified 22d ago

The `azure-eventhub-checkpointstoreblob` library provides a checkpointer implementation for Azure Event Hubs, using Azure Blob Storage as the persistent store. It integrates as a plug-in package with `EventHubConsumerClient` from `azure-eventhub` to manage checkpoints and partition ownership information. This is the synchronous version of the library; an asynchronous counterpart `azure-eventhub-checkpointstoreblob-aio` is also available. As part of the Azure SDK for Python, it follows a regular release cadence.

pip install azure-eventhub-checkpointstoreblob
INSTALL
IMPORT
SIG · AZURE-EVENTHUB-CHE
A
azure-eventhub-checkpointstoreblob
azurepythonv1.2.0
Install
3.7s avg
Import
1171ms
Disk
46MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.238s · 47MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.7s · import 1.104s · 47MB
46MB installed
● package 46MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BlobCheckpointStore
from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore
from azure.eventhub.extensions.checkpointstoreblob.blobstoragepm import BlobPartitionManager
The `BlobPartitionManager` class and `blobstoragepm` module were renamed to `BlobCheckpointStore` in `azure.eventhub.extensions.checkpointstoreblob` in version 1.0.0b6. The old module is now internal.

This quickstart demonstrates how to consume events from an Azure Event Hub using `EventHubConsumerClient` and persist checkpoints in Azure Blob Storage using `BlobCheckpointStore`. It authenticates using `DefaultAzureCredential` and processes events in a simple `on_event` callback, updating the checkpoint after each event. Ensure environment variables for Event Hubs connection details and Blob Storage account URL/container name are set.

import os from azure.eventhub import EventHubConsumerClient from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore from azure.identity import DefaultAzureCredential # Environment variables for Event Hubs EVENTHUB_CONNECTION_STR = os.environ.get('EVENTHUB_CONNECTION_STR', '') EVENTHUB_NAME = os.environ.get('EVENTHUB_NAME', '') CONSUMER_GROUP = os.environ.get('CONSUMER_GROUP', '$Default') # Environment variables for Azure Blob Storage Checkpoint Store BLOB_STORAGE_ACCOUNT_URL = os.environ.get('BLOB_STORAGE_ACCOUNT_URL', '') # e.g., 'https://<your_storage_account_name>.blob.core.windows.net/' BLOB_CONTAINER_NAME = os.environ.get('BLOB_CONTAINER_NAME', '') # DefaultAzureCredential will attempt to authenticate using environment variables, # managed identity, Azure CLI, etc. credential = DefaultAzureCredential() def on_event(partition_context, event): print(f"Received event from partition {partition_context.partition_id}, sequence_number: {event.sequence_number}") # Your event processing logic here # Update the checkpoint so that the program doesn't read the events # that it has already read when you run it next time. partition_context.update_checkpoint(event) def main(): if not all([EVENTHUB_CONNECTION_STR, EVENTHUB_NAME, BLOB_STORAGE_ACCOUNT_URL, BLOB_CONTAINER_NAME]): print("Please set EVENTHUB_CONNECTION_STR, EVENTHUB_NAME, BLOB_STORAGE_ACCOUNT_URL, and BLOB_CONTAINER_NAME environment variables.") return # Create an Azure blob checkpoint store to store the checkpoints. checkpoint_store = BlobCheckpointStore( blob_account_url=BLOB_STORAGE_ACCOUNT_URL, container_name=BLOB_CONTAINER_NAME, credential=credential, ) # Create a consumer client for the event hub. client = EventHubConsumerClient.from_connection_string( conn_str=EVENTHUB_CONNECTION_STR, consumer_group=CONSUMER_GROUP, eventhub_name=EVENTHUB_NAME, checkpoint_store=checkpoint_store, ) with client: print(f"Listening for events in consumer group '{CONSUMER_GROUP}' on Event Hub '{EVENTHUB_NAME}'...") # Call the receive method. Read from the beginning of the partition client.receive(on_event=on_event, starting_position="-1") credential.close() if __name__ == "__main__": main()
Debug
Known issues
breakingVersion 1.0.0b6 introduced breaking changes: `BlobPartitionManager` was renamed to `BlobCheckpointStore`, and its constructor was updated to accept storage container details directly instead of a `ContainerClient` instance. The `blobstoragepm` module became internal.
fix
Update imports to `from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore` and adjust constructor calls.
affects: <1.0.0b6
gotchaFor optimal performance and reliability, it is strongly recommended to use a dedicated Blob Storage container for each consumer group. The storage account should be in the same region as the Event Hub consumer application, and it should not be used for other workloads. Additionally, disable 'Hierarchical namespace', 'Blob soft delete', and 'Versioning' for the container.
gotchaIn environments like Azure Stack Hub, which may support older Azure Storage Service API versions, you might need to explicitly specify `api_version` (e.g., `api_version='2017-11-09'`) when creating `BlobCheckpointStore` to avoid `HttpResponseError` exceptions. The default API version is '2019-07-07'.
deprecatedSupport for Python 2.7 has officially ended on January 1, 2022. All versions of this library from 1.2.0 onwards require Python 3.8 or later. Earlier versions had varying Python 3.x support.
fix
Upgrade to Python 3.8 or later and use a compatible version of the library.
affects: <1.2.0
gotchaAzure Event Hubs client libraries are transitioning towards exclusively using sequence number-based checkpoints. Relying on offsets for external systems like KEDA scalers can be problematic because offsets do not change predictably. While the library contract might remain stable, the underlying behavior for external monitoring or scaling based on checkpoint data could change.
fix
When building external systems that rely on checkpoint data, favor sequence numbers over offsets for reliable scaling and monitoring.
affects: All versions, particularly newer ones that internalize this change.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.eventhub.extensions.checkpointstoreblob'
This error typically occurs when the `azure-eventhub-checkpointstoreblob` package is not correctly installed or Python cannot resolve the module path, sometimes due to issues with namespace packages in specific deployment environments like Azure Databricks.
fix
Ensure the package is installed using `pip install azure-eventhub-checkpointstoreblob`. If using multiple Azure SDK packages that are namespace packages, verify the installation environment supports correct resolution of these packages.
KeyError (often related to 'ownerid' or other metadata during checkpointing)
This `KeyError` arises when the `BlobCheckpointStore` attempts to read checkpoint or ownership metadata (like 'ownerid') from a blob in Azure Storage, but the expected key is missing or the blob itself is empty or in an unexpected state, particularly with Data Lake-enabled storage accounts or older library versions.
fix
Upgrade the `azure-eventhub-checkpointstoreblob` library to its latest version. Ensure your Azure Blob Storage account has recommended settings (e.g., hierarchical namespace, blob soft delete, and versioning disabled) and the container is used exclusively for checkpointing data. Consider deleting and recreating checkpoint data if corruption is suspected.
ClientAuthenticationError("Server failed to authenticate the request. ... Request date header too old: '...' ")
This authentication error indicates a significant time difference between the client machine where the application is running and the Azure Storage service, causing the request's date header to be rejected as too old.
fix
Synchronize the client machine's system clock with a reliable time source. Additionally, ensure you are using a recent version of the `azure-eventhub-checkpointstoreblob` library, as updates have included fixes for underlying storage SDK authentication issues.
ConnectionClose('ErrorCodes.UnknownError: Connection in an unexpected error state.')
This generic connection closure error often signifies underlying network instability, such as intermittent network issues, a long latency between the client and Azure services (e.g., cross-region deployments), or an unreliable proxy/VPN connection impacting the Event Hub consumer's ability to maintain a connection.
fix
Investigate network connectivity and stability between your application and Azure Event Hubs/Blob Storage. Deploy the application in the same Azure region as the Event Hub and Storage Account to minimize latency, and verify that no unstable proxies or VPNs are interfering with the connection.
Upgrade
Version history
1.2.0latest on PyPI · released Feb 13, 2025
Audit
Dependencies
azure-eventhubrequiredCore Event Hubs client library, required for EventHubConsumerClient.
azure-identityoptionalCommonly used for Azure authentication, e.g., DefaultAzureCredential.
Agent activity
44 hits · last 30 days
node
38
OpenAI (training)
1
Resources