124 строки
4.8 KiB
Markdown
124 строки
4.8 KiB
Markdown
Debug logging
|
||
=============
|
||
|
||
The SDK is equipped with debug logging infrastructure which can help
|
||
both during library development and troubleshooting on customer's side.
|
||
|
||
There are 4 preprocessor defines available for 4 log levels, each with a
|
||
different usage recommendation:
|
||
|
||
- `LOG_ERROR()`
|
||
Errors potentially preventing the SDK from properly collecting or
|
||
transmitting events.
|
||
Messages at this level should be written as nice sentences with
|
||
enough context to understand the error source and implications even
|
||
if only error-level messages are available.
|
||
Examples: invalid input, damaged offline storage, events
|
||
being dropped.
|
||
|
||
- `LOG_WARN()`
|
||
Unexpected failures which may negatively affect performance or
|
||
reliability of event collection and other important notices.
|
||
Messages at this level should be also written as nice sentences with
|
||
enough context to understand them even if only error- and
|
||
warning-level messages are available.
|
||
Examples: HTTP request failed (and must be retried), excessive size
|
||
of an event, ???.
|
||
|
||
- `LOG_INFO()`
|
||
Higher-level information about actions performed by the library.
|
||
Messages at this level should be still written as nice sentences, so
|
||
that even people not familiar with SDK internals can understand them
|
||
and learn what's going on with their events.
|
||
Examples: library started/stopped, event received, HTTP
|
||
request sent.
|
||
|
||
- `LOG_TRACE()`
|
||
Other detailed information about library's processing for advanced
|
||
debugging.
|
||
Messages at this level do not have to follow any particular style,
|
||
they can be simple dumps of variable values etc., understandable by
|
||
the SDK developers only.
|
||
Examples: individual database query results, validation steps
|
||
being performed.
|
||
|
||
Nothing inside the parentheses gets evaluated unless the relevant log
|
||
level is currently active. If that's not enough to disable some
|
||
intrusive logging, one can use another set of macros,
|
||
`EVENTS_LOG_ENABLED_xxx()` where `xxx` is one of
|
||
`ERROR`/`WARNING`/`INFO`/`DETAIL` again, which evaluates to `true` or
|
||
`false` depending on the state of the related log level.
|
||
|
||
The log lines never contain any PII (Personally Identifiable
|
||
Information) because potentially sensitive data can come to the library
|
||
only in form of custom values inside event properties and those are
|
||
never printed to debug log.
|
||
|
||
Implementations
|
||
---------------
|
||
|
||
### Skype
|
||
|
||
Logging is implemented using RootTools Unified Logging APIs.
|
||
|
||
The RT framework provides 11 (or even 100 internally) log levels with
|
||
quite fine grained distinction between them in order to facilitate
|
||
efficient remote collection of logs from customer's devices. The default
|
||
RT log level (on internal/debug builds) is `Debug4`.
|
||
|
||
The following table shows mapping of RootTools levels to the 4 levels
|
||
used by the SDK:
|
||
|
||
- `Trace`
|
||
Never used by the SDK. There is no instrumentation of
|
||
function entry/exit.
|
||
|
||
- `Debug6`
|
||
Never used by the SDK. This log level is expected to be used for
|
||
logging large strings like full HTTP responses etc. The library
|
||
never dumps such data.
|
||
|
||
- `Debug5`
|
||
Never used by the SDK. Avoided for simplicity ‒ `Debug4` is the
|
||
default level on internal/debug builds and therefore if we don't use
|
||
anything lower, we don't need to change anything on user's devices
|
||
to see all our messages.
|
||
|
||
- **`Debug4` = `LOG_TRACE()`**
|
||
|
||
- **`Debug3` = `LOG_INFO()`**
|
||
|
||
- **`Debug2` = `LOG_WARN()`**
|
||
|
||
- `Debug1`
|
||
Never used by the SDK. This log level is "suitable for logging of
|
||
significant events in the application, for example call started,
|
||
call ended, or user login". A background service for telemetry
|
||
collection does not have any such significant events to report.
|
||
|
||
- **`Warning` = `LOG_ERROR()`**
|
||
A log level "suitable for logging a warning when the app faced a
|
||
potential problem that was mitigated without affecting the user
|
||
experience in any way".
|
||
|
||
- `Error`
|
||
Never used by the SDK. This level is "suitable for logging a
|
||
significant problem that affected the user in some way \[...\],
|
||
resulting in parts of the app being unusable". That never applies to
|
||
telemetry collection happening in the background.
|
||
|
||
- `Fatal`
|
||
Never used by the SDK. This level is for "errors that are so serious
|
||
that the program will abort". Operations of the library are never
|
||
that important or sensitive (except for things like out of memory
|
||
conditions, but those are not handled directly by the library).
|
||
|
||
- `MetaData`
|
||
Never used by the SDK. The application which uses the library is
|
||
supposed to print its version and other system info at this level.
|
||
|
||
### Win32 (experimental)
|
||
|
||
Log messages are written with a custom formatter to the Windows debug
|
||
log through Win32 API `OutputDebugString()`.
|