{"id":4892,"library":"azure-eventhub-checkpointstoreblob","title":"Azure Event Hubs Checkpoint Store Blob","description":"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.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub-checkpointstoreblob","tags":["azure","event hubs","blob storage","checkpointing","messaging","cloud"],"install":[{"cmd":"pip install azure-eventhub-checkpointstoreblob","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core Event Hubs client library, required for EventHubConsumerClient.","package":"azure-eventhub","optional":false},{"reason":"Commonly used for Azure authentication, e.g., DefaultAzureCredential.","package":"azure-identity","optional":true}],"imports":[{"note":"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.","wrong":"from azure.eventhub.extensions.checkpointstoreblob.blobstoragepm import BlobPartitionManager","symbol":"BlobCheckpointStore","correct":"from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore"}],"quickstart":{"code":"import os\nfrom azure.eventhub import EventHubConsumerClient\nfrom azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore\nfrom azure.identity import DefaultAzureCredential\n\n# Environment variables for Event Hubs\nEVENTHUB_CONNECTION_STR = os.environ.get('EVENTHUB_CONNECTION_STR', '')\nEVENTHUB_NAME = os.environ.get('EVENTHUB_NAME', '')\nCONSUMER_GROUP = os.environ.get('CONSUMER_GROUP', '$Default')\n\n# Environment variables for Azure Blob Storage Checkpoint Store\nBLOB_STORAGE_ACCOUNT_URL = os.environ.get('BLOB_STORAGE_ACCOUNT_URL', '') # e.g., 'https://<your_storage_account_name>.blob.core.windows.net/'\nBLOB_CONTAINER_NAME = os.environ.get('BLOB_CONTAINER_NAME', '')\n\n# DefaultAzureCredential will attempt to authenticate using environment variables,\n# managed identity, Azure CLI, etc.\ncredential = DefaultAzureCredential()\n\ndef on_event(partition_context, event):\n    print(f\"Received event from partition {partition_context.partition_id}, sequence_number: {event.sequence_number}\")\n    # Your event processing logic here\n\n    # Update the checkpoint so that the program doesn't read the events\n    # that it has already read when you run it next time.\n    partition_context.update_checkpoint(event)\n\ndef main():\n    if not all([EVENTHUB_CONNECTION_STR, EVENTHUB_NAME, BLOB_STORAGE_ACCOUNT_URL, BLOB_CONTAINER_NAME]):\n        print(\"Please set EVENTHUB_CONNECTION_STR, EVENTHUB_NAME, BLOB_STORAGE_ACCOUNT_URL, and BLOB_CONTAINER_NAME environment variables.\")\n        return\n\n    # Create an Azure blob checkpoint store to store the checkpoints.\n    checkpoint_store = BlobCheckpointStore(\n        blob_account_url=BLOB_STORAGE_ACCOUNT_URL,\n        container_name=BLOB_CONTAINER_NAME,\n        credential=credential,\n    )\n\n    # Create a consumer client for the event hub.\n    client = EventHubConsumerClient.from_connection_string(\n        conn_str=EVENTHUB_CONNECTION_STR,\n        consumer_group=CONSUMER_GROUP,\n        eventhub_name=EVENTHUB_NAME,\n        checkpoint_store=checkpoint_store,\n    )\n\n    with client:\n        print(f\"Listening for events in consumer group '{CONSUMER_GROUP}' on Event Hub '{EVENTHUB_NAME}'...\")\n        # Call the receive method. Read from the beginning of the partition\n        client.receive(on_event=on_event, starting_position=\"-1\")\n\n    credential.close()\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Update imports to `from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore` and adjust constructor calls.","message":"Version 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.","severity":"breaking","affected_versions":"<1.0.0b6"},{"message":"For 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.","severity":"gotcha"},{"message":"In 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'.","severity":"gotcha"},{"fix":"Upgrade to Python 3.8 or later and use a compatible version of the library.","message":"Support 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.","severity":"deprecated","affected_versions":"<1.2.0"},{"fix":"When building external systems that rely on checkpoint data, favor sequence numbers over offsets for reliable scaling and monitoring.","message":"Azure 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.","severity":"gotcha","affected_versions":"All versions, particularly newer ones that internalize this change."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}