Setting the file. One moment.
Chapter 15 · Azure Diagnostics
Subchapter 15.38
troubleshooting/messaging/azure-eventhubs-java.mdMarkdown3 KBView on GitHub
Package: azure-messaging-eventhubs | README |
⚠️ Note: The detailed Java troubleshooting guide has moved to Microsoft Learn (opens in a new tab).
| Exception | Cause | Fix |
|---|---|---|
AmqpException (connection:forced) | Idle connection disconnected | Auto-recovers; no action needed |
AmqpException (unauthorized-access) | Bad credentials or missing permissions | Verify connection string, SAS, or RBAC roles |
AmqpException (resource-limit-exceeded) | Too many concurrent receivers | Reduce receiver count or upgrade tier |
OperationTimeoutException | Network issue or throttling | Check firewall, try AMQP over WebSockets (port 443) |
Configure via SLF4J. Add logback-classic dependency and set level for com.azure.messaging.eventhubs:
<logger name="com.azure.messaging.eventhubs" level="DEBUG"/>For AMQP frame tracing:
<logger name="com.azure.core.amqp" level="DEBUG"/>See Java SDK logging docs (opens in a new tab) for details.
EventHubClientBuilder connections; avoid creating new clients per operation.Package: azure-messaging-eventhubs-checkpointstore-blob
Auth:
DefaultAzureCredentialis for local development. See auth-best-practices.md for production patterns.
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
BlobContainerAsyncClient blobClient = new BlobContainerClientBuilder()
.endpoint("https://<storage-account>.blob.core.windows.net/<checkpoint-container>")
.credential(credential)
.buildAsyncClient();
EventProcessorClient processor = new EventProcessorClientBuilder()
.credential("<your-namespace>.servicebus.windows.net", "<your-eventhub>", credential)
.consumerGroup("$Default")
.checkpointStore(new BlobCheckpointStore(blobClient))
.processEvent(eventContext -> {
// process event
eventContext.updateCheckpoint();
})
.buildEventProcessorClient();Common issues:
updateCheckpoint() per batch, not per event, to reduce storage calls.Include: partition count, machine specs, instance count, max heap (-Xmx), average EventData size, traffic pattern, and DEBUG-level logs (±10 min from issue).