1# Azure Event Hubs SDK — Python
2 
3Package: `azure-eventhub` | [README](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/eventhub/azure-eventhub) | [Full Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/eventhub/azure-eventhub/TROUBLESHOOTING.md)
4 
5## Common Errors
6 
7| Exception | Cause | Fix |
8|-----------|-------|-----|
9| `EventHubError` | Base exception wrapping AMQP errors | Check `message`, `error`, `details` fields |
10| `ConnectionLostError` | Idle connection disconnected | Auto-recovers on next operation; no action needed |
11| `AuthenticationError` | Bad credentials or expired SAS | Regenerate key, check RBAC roles, verify connection string |
12| `OperationTimeoutError` | Network or throttling | Check firewall, try WebSockets (port 443), increase timeout |
13 
14## Retry Configuration
15 
16> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](auth-best-practices.md) for production patterns.
17 
18```python
19from azure.eventhub import EventHubProducerClient
20from azure.identity import DefaultAzureCredential
21 
22client = EventHubProducerClient(
23    fully_qualified_namespace="<your-namespace>.servicebus.windows.net",
24    eventhub_name="<your-eventhub>",
25    credential=DefaultAzureCredential(),
26    retry_total=3,
27    retry_backoff_factor=0.8,
28    retry_backoff_max=120,
29    retry_mode='exponential'
30)
31```
32 
33## Consumer Client Retry Configuration
34 
35> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](auth-best-practices.md) for production patterns.
36 
37Under heavy load, tune the retry policy on `EventHubConsumerClient` to reduce timeouts:
38 
39| Parameter | Default | Description |
40|-----------|---------|-------------|
41| `retry_total` | 3 | Max retry attempts per operation |
42| `retry_backoff_factor` | 0.8 | Backoff multiplier between retries (seconds) |
43| `retry_backoff_max` | 120 | Max backoff interval (seconds) |
44| `retry_mode` | `exponential` | `fixed` or `exponential` |
45 
46```python
47from azure.eventhub import EventHubConsumerClient
48from azure.eventhub.extensions.checkpointstoreblob import BlobCheckpointStore
49from azure.identity import DefaultAzureCredential
50 
51credential = DefaultAzureCredential()
52checkpoint_store = BlobCheckpointStore(
53    blob_account_url="https://<storage-account>.blob.core.windows.net",
54    container_name="<checkpoint-container>",
55    credential=credential
56)
57 
58client = EventHubConsumerClient(
59    fully_qualified_namespace="<your-namespace>.servicebus.windows.net",
60    eventhub_name="<your-eventhub>",
61    consumer_group="$Default",
62    credential=credential,
63    checkpoint_store=checkpoint_store,
64    retry_total=5,
65    retry_backoff_factor=1.0,
66    retry_backoff_max=120,
67    retry_mode='exponential'
68)
69```
70 
71## Enable Logging
72 
73```python
74import logging, sys
75 
76handler = logging.StreamHandler(stream=sys.stdout)
77handler.setFormatter(logging.Formatter("%(asctime)s | %(threadName)s | %(levelname)s | %(name)s | %(message)s"))
78logger = logging.getLogger('azure.eventhub')
79logger.setLevel(logging.DEBUG)
80logger.addHandler(handler)
81 
82# Enable AMQP frame tracing
83client = EventHubProducerClient(..., logging_enable=True)
84```
85 
86## Key Issues
87 
88- **Buffered producer not sending**: Ensure enough `ThreadPoolExecutor` workers (one per partition). Use `buffer_concurrency` kwarg.
89- **Blocking calls in async**: Run CPU-bound code in an executor; blocking the event loop impacts load balancing and checkpointing.
90- **Consumer disconnected**: Expected during load balancing. If persistent with no scaling, file an issue.
91- **Soft delete on checkpoint store**: Disable "soft delete" and "blob versioning" on the storage account used for checkpointing.
92- **Always close clients**: Use `with` statement or call `close()` to avoid socket/connection leaks.
93 
94## Checkpointing (BlobCheckpointStore)
95 
96Package: `azure-eventhub-checkpointstoreblob` (sync) / `azure-eventhub-checkpointstoreblob-aio` (async)
97 
98See the [Consumer Client Retry Configuration](#consumer-client-retry-configuration) section above for a full `EventHubConsumerClient` example with `BlobCheckpointStore`.
99 
100**Common issues:**
101- **Soft delete / blob versioning**: Disable both on the storage account — they cause large delays during load balancing.
102- **HTTP 412/409 from storage**: Normal during partition ownership negotiation; not an error.
103- **Checkpoint frequency**: Checkpoint after processing each batch, not each event, to avoid storage throttling.
104