Setting the file. One moment.
Chapter 15 · Azure Diagnostics
Subchapter 15.40
troubleshooting/messaging/azure-eventhubs-py.mdMarkdown4 KBView on GitHub
Package: azure-eventhub | README |
| Exception | Cause | Fix |
|---|---|---|
EventHubError | Base exception wrapping AMQP errors | Check message, error, details fields |
ConnectionLostError | Idle connection disconnected | Auto-recovers on next operation; no action needed |
AuthenticationError | Bad credentials or expired SAS | Regenerate key, check RBAC roles, verify connection string |
OperationTimeoutError | Network or throttling | Check firewall, try WebSockets (port 443), increase timeout |
Auth:
DefaultAzureCredentialis for local development. See auth-best-practices.md for production patterns.
from azure.eventhub import EventHubProducerClient
from azure.identity import DefaultAzureCredential
client = EventHubProducerClient(
fully_qualified_namespace="<your-namespace>.servicebus.windows.net",
eventhub_name="<your-eventhub>",
credential=DefaultAzureCredential(),
retry_total=3,
retry_backoff_factor=0.8,
retry_backoff_max=120,
retry_mode='exponential'
)Auth:
DefaultAzureCredentialis for local development. See auth-best-practices.md for production patterns.
Under heavy load, tune the retry policy on EventHubConsumerClient to reduce timeouts:
| Parameter | Default | Description |
|---|---|---|
retry_total | 3 | Max retry attempts per operation |
retry_backoff_factor | 0.8 | Backoff multiplier between retries (seconds) |
retry_backoff_max | 120 | Max backoff interval (seconds) |
retry_mode | exponential | fixed or exponential |
from azure.eventhub import EventHubConsumerClient
from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
checkpoint_store = BlobCheckpointStore(
blob_account_url="https://<storage-account>.blob.core.windows.net",
container_name="<checkpoint-container>",
credential=credential
)
client = EventHubConsumerClient(
fully_qualified_namespace="<your-namespace>.servicebus.windows.net",
eventhub_name="<your-eventhub>",
consumer_group="$Default",
credential=credential,
checkpoint_store=checkpoint_store,
retry_total=5,
retry_backoff_factor=1.0,
retry_backoff_max=120,
retry_mode='exponential'
)import logging, sys
handler = logging.StreamHandler(stream=sys.stdout)
handler.setFormatter(logging.Formatter("%(asctime)s | %(threadName)s | %(levelname)s | %(name)s | %(message)s"))
logger = logging.getLogger('azure.eventhub')
logger.setLevel(logging.DEBUG)
logger.addHandler(handler)
# Enable AMQP frame tracing
client = EventHubProducerClient(..., logging_enable=True)ThreadPoolExecutor workers (one per partition). Use buffer_concurrency kwarg.with statement or call close() to avoid socket/connection leaks.Package: azure-eventhub-checkpointstoreblob (sync) / azure-eventhub-checkpointstoreblob-aio (async)
See the Consumer Client Retry Configuration section above for a full EventHubConsumerClient example with BlobCheckpointStore.
Common issues: