github/azure-sdk-for-cpp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Readme section on logging (#2521)

Browse Source 
* Readme section on logging

* Apply suggestions from code review

Co-authored-by: Rick Winter <rick.winter@microsoft.com>

* Update sdk/core/azure-core/README.md

Co-authored-by: Anton Kolesnyk <antkmsft@users.noreply.github.com>
Co-authored-by: Rick Winter <rick.winter@microsoft.com>
This commit is contained in:
Anton Kolesnyk 2021-06-30 16:49:30 -07:00 committed by GitHub
parent 40ab9315d1
commit c8006b4673
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
sdk/core/azure-core/README.md
View File

@ -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 <azure/core/diagnostics/logger.hpp>
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.