From c8006b4673ff26cd113c34c65223f7f7d773c17d Mon Sep 17 00:00:00 2001 From: Anton Kolesnyk <41349689+antkmsft@users.noreply.github.com> Date: Wed, 30 Jun 2021 16:49:30 -0700 Subject: [PATCH] Readme section on logging (#2521) * Readme section on logging * Apply suggestions from code review Co-authored-by: Rick Winter * Update sdk/core/azure-core/README.md Co-authored-by: Anton Kolesnyk Co-authored-by: Rick Winter --- sdk/core/azure-core/README.md | 45 ++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/sdk/core/azure-core/README.md b/sdk/core/azure-core/README.md index 90025ede5..600678e39 100644 --- a/sdk/core/azure-core/README.md +++ b/sdk/core/azure-core/README.md @@ -74,9 +74,52 @@ Out of the box, the Azure SDK for C++ supports the libcurl and WinHTTP libraries Three main ways of troubleshooting failures are: - Inspecting exceptions -- Enabling logging (`Available in future release`) +- Enabling logging (see [SDK Log Messages](#sdk-log-messages)) - Distributed tracing (`Available in future release`) +### SDK Log Messages + +The simplest way to enable logs is to set `AZURE_LOG_LEVEL` environment variable to one of the values: +|`AZURE_LOG_LEVEL`|`Azure::Core::Diagnostics::Logger::Level`|Log message level +|-|-|- +|`4`, or `error`, or `err`|`Error`|Logging level for failures that the application is unlikely to recover from. +|`3`, or `warning`, or `warn`|`Warning`|Logging level when a function fails to perform its intended task. +|`2`, or `informational`, or `information`, or `info`|`Informational`|Logging level when a function operates normally. +|`1`, or `verbose`, or `debug`|`Verbose`|Logging level for detailed troubleshooting scenarios. + +Then, log messages will be printed to console (`stderr`). +Note that `stderr` messages can be redirected into a log file like this: + +On Windows: +```cmd +myprogram.exe 2> log.txt +``` + +On Linux or macOS: +```sh +./myprogram 2> log.txt +``` + +In addition, log messages can be programmatically processed by providing a callback function, which can save them to a file, or display them in a desired custom way. +```cpp +#include + +int main() +{ + using namespace Azure::Core::Diagnostics; + + // See above for the level descriptions. + Logger::SetLevel(Logger::Level::Verbose); + + // SetListener accepts std::function<>, which can be either lambda or a function pointer. + Logger::SetListener([&](auto lvl, auto msg){ /* handle Logger::Level lvl and std::string msg */ }); +} +``` + +Note, the listener callback is executed on the same thread as the operation that triggered the log message. + It is recommended implementation due the minimal amount of log message processing on the callback thread. +Where message processing is required, consider implementing in a way that the callback pushes the message string into a thread-safe queue, so that another thread would pick the messages from that queue and handle them. + ## Next steps Explore and install available Azure SDK libraries.