Registry /
azure / azure-eventhub-checkpointstoreblob
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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.238s · 47MB
glibcpy 3.10–3.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.fixUpdate 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.fixUpgrade 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.fixWhen 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.
fixEnsure 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.
fixUpgrade 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.
fixSynchronize 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.
fixInvestigate 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.