From f597ef1ea96d01f2eefba604698ed4b3cddfbb8d Mon Sep 17 00:00:00 2001 From: Jesse Squire Date: Fri, 18 Sep 2020 13:11:46 -0400 Subject: [PATCH] [Azure Messaging] README Updates (Troubleshooting + Logging) (#15237) The focus of these changes is to enhance the troubleshooting section of the README documentation with information about logging and distributed tracing, calling out to the existing Azure.Core resource for details. --- .../README.md | 16 +++++++++++++--- sdk/eventhub/Azure.Messaging.EventHubs/README.md | 14 ++++++++++++-- .../Azure.Messaging.ServiceBus/README.md | 14 +++++++++++--- 3 files changed, 36 insertions(+), 8 deletions(-) diff --git a/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md b/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md index 7e6a6dbab6044..b2c3ea7945258 100755 --- a/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md +++ b/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md @@ -209,7 +209,9 @@ When using Azure Active Directory with Azure Storage, your principal must be ass ## Troubleshooting -### Event Processor client exceptions +### Exception handling + +#### Event Processor client exceptions The Event Processor client makes every attempt to be resilient in the face of exceptions and will take the necessary actions to continue processing unless it is impossible to do so. No action from developers is needed for this to take place; it is natively part of the processor's behavior. @@ -217,16 +219,24 @@ In order to allow developers the opportunity to inspect and react to exceptions For a basic example of implementing the error handler, please see the sample: [Manage the Event Processor when an error is encountered](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample07_RestartProcessingOnError.cs). -### Exceptions in event handlers +#### Exceptions in event handlers Because the Event Processor client lacks the appropriate context to understand the severity of exceptions within the event handlers that developers provide, it cannot assume what actions would be a reasonable response to them. As a result, developers are considered responsible for exceptions that occur within the event handlers they provide using `try/catch` blocks and other standard language constructs. The Event Processor client will not attempt to detect exceptions in developer code nor surface them explicitly. The resulting behavior will depend on the processor's hosting environment and the context in which the event handler was called. Because this may vary between different scenarios, it is strongly recommended that developers code their event handlers defensively and account for potential exceptions. -### Exception details +#### Exception details For detailed information about exceptions that may occur, please refer to the Event Hubs client library [README]( https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub/Azure.Messaging.EventHubs/README.md#event-hubs-exception) and the service documentation for [Event Hubs messaging exceptions](https://docs.microsoft.com/azure/event-hubs/event-hubs-messaging-exceptions). +### Logging and diagnostics + +The Event Processor client library is fully instrumented for logging information at various levels of detail using the .NET `EventSource` to emit information. Logging is performed for each operation and follows the pattern of marking the starting point of the operation, it's completion, and any exceptions encountered. Additional information that may offer insight is also logged in the context of the associated operation. + +The Event Processor client logs are available to any `EventListener` by opting into the source named "Azure-Messaging-EventHubs-Processor-EventProcessorClient" or opting into all sources that have the trait "AzureEventSource". To make capturing logs from the Azure client libraries easier, the `Azure.Core` library used by Event Hubs offers an `AzureEventSourceListener`. More information can be found in the [Azure.Core Diagnostics sample](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#logging). + +The Event Processor library is also instrumented for distributed tracing using Application Insights or OpenTelemetry. More information can be found in the [Azure.Core Diagnostics sample](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#distributed-tracing). + ## Next steps Beyond the scenarios discussed, the Azure Event Hubs Processor library offers support for additional scenarios to help take advantage of the full feature set of the `EventProcessorClient`. In order to help explore some of these scenarios, the Event Hubs Processor client library offers a project of samples to serve as an illustration for common scenarios. Please see the samples [README](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/README.md) for details. diff --git a/sdk/eventhub/Azure.Messaging.EventHubs/README.md b/sdk/eventhub/Azure.Messaging.EventHubs/README.md index df063db503f89..d42cb78a158c6 100755 --- a/sdk/eventhub/Azure.Messaging.EventHubs/README.md +++ b/sdk/eventhub/Azure.Messaging.EventHubs/README.md @@ -198,7 +198,9 @@ When using Azure Active Directory, your principal must be assigned a role which ## Troubleshooting -### Event Hubs Exception +### Exception handling + +#### Event Hubs Exception An `EventHubsException` is triggered when an operation specific to Event Hubs has encountered an issue, including both errors within the service and specific to the client. The exception includes some contextual information to assist in understanding the context of the error and its relative severity. These are: @@ -230,10 +232,18 @@ catch (EventHubsException ex) when } ``` -### Other exceptions +#### Other exceptions For detailed information about the failures represented by the `EventHubsException` and other exceptions that may occur, please refer to [Event Hubs messaging exceptions](https://docs.microsoft.com/azure/event-hubs/event-hubs-messaging-exceptions). +### Logging and diagnostics + +The Event Hubs client library is fully instrumented for logging information at various levels of detail using the .NET `EventSource` to emit information. Logging is performed for each operation and follows the pattern of marking the starting point of the operation, it's completion, and any exceptions encountered. Additional information that may offer insight is also logged in the context of the associated operation. + +The Event Hubs client logs are available to any `EventListener` by opting into the source named "Azure-Messaging-EventHubs" or opting into all sources that have the trait "AzureEventSource". To make capturing logs from the Azure client libraries easier, the `Azure.Core` library used by Event Hubs offers an `AzureEventSourceListener`. More information can be found in the [Azure.Core Diagnostics sample](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#logging). + +The Event Hubs client library is also instrumented for distributed tracing using Application Insights or OpenTelemetry. More information can be found in the [Azure.Core Diagnostics sample](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#distributed-tracing). + ## Next steps Beyond the introductory scenarios discussed, the Azure Event Hubs client library offers support for additional scenarios to help take advantage of the full feature set of the Azure Event Hubs service. In order to help explore some of these scenarios, the Event Hubs client library offers a project of samples to serve as an illustration for common scenarios. Please see the samples [README](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/samples/README.md) for details. diff --git a/sdk/servicebus/Azure.Messaging.ServiceBus/README.md b/sdk/servicebus/Azure.Messaging.ServiceBus/README.md index 1a431dedb00d6..eb0c39b4f61c0 100755 --- a/sdk/servicebus/Azure.Messaging.ServiceBus/README.md +++ b/sdk/servicebus/Azure.Messaging.ServiceBus/README.md @@ -317,7 +317,9 @@ ServiceBusClient client = new ServiceBusClient(fullyQualifiedNamespace, new Defa ## Troubleshooting -### Service Bus Exception +### Exception handling + +#### Service Bus Exception A `ServiceBusException` is triggered when an operation specific to Service Bus has encountered an issue, including both errors within the service and specific to the client. The exception includes some contextual information to assist in understanding the context of the error and its relative severity. These are: @@ -345,11 +347,17 @@ catch (ServiceBusException ex) when } ``` -### Other exceptions +#### Other exceptions For detailed information about the failures represented by the `ServiceBusException` and other exceptions that may occur, please refer to [Service Bus messaging exceptions](https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-exceptions). -You can also easily [enable console logging](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#logging) if you want to dig deeper into the requests you're making against the service. +### Logging and diagnostics + +The Service Bus client library is fully instrumented for logging information at various levels of detail using the .NET `EventSource` to emit information. Logging is performed for each operation and follows the pattern of marking the starting point of the operation and either it's completion or exceptions encountered. Additional information that may offer insight is also logged in the context of the associated operation. + +The Service Bus client logs are available to any `EventListener` by opting into the source named "Azure-Messaging-ServiceBus" or opting into all sources that have the trait "AzureEventSource". To make capturing logs from the Azure client libraries easier, the `Azure.Core` library used by Service Bus offers an `AzureEventSourceListener`. More information can be found in the [Azure.Core Diagnostics sample](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#logging). + +The Service Bus client library is also instrumented for distributed tracing using Application Insights or OpenTelemetry. More information can be found in the [Azure.Core Diagnostics sample](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md#distributed-tracing). ## Next steps