Feature suggestion: debug output, selectable detail

[dstaudt]

Every well-implemented layer in the stack needs robust debug/trace/serviceability capability!

It would be great to provide debug output - of selectable detail - providing insight into the inner workings of the SDK, and perhaps helping troubleshooting issues occurring between the app logic and the Webex Teams service.

[cmlccie]

@dstaudt, I completely agree that there is an opportunity to improve observability into the library’s operations and provide elegant access to the low level operations that it automates. Improving observability and transparency are goals for v2.

Can you provide some examples of what you would like to see?

There is also a question of how much detail should be included in each level and if there should be a limit to the things that the library should include in logging messages it generates. For example, consider that the contents (JSON bodies) of many Webex Teams objects (messages, memberships, and even rooms) may include personally identifiable information (PII) and confidential information. A client application may choose to log PII data (and then hopefully protect it); however from a secure by default perspective, I am reluctant to have the library log any potential PII or confidential information.

Your thoughts?

[dstaudt]

Can't go too far wrong (hopefully) by implementing debug logging similar to the official Node SDK, i.e. via env variables: https://developer.webex.com/docs/sdks/node#sdk-api-reference
https://webex.github.io/webex-js-sdk/api/#loggerconfig

Perhaps initial logging levels could be something like:

• Silent - (default) no log output
• Warn - Include info about any throttling responses
• Error - Warn + Include essentially the same information as any exceptions encountered (handled or not)
• Debug - Error + API URL/request-response bodies
• Trace - Debug + API HTTP transport details (request-response headers), but elide access tokens

Details about the inner workings of the SDK code itself may be interesting to developers (or maintainers, if provided when investigating bugs), but not sure what those might be.

Thoughts about sensitive data are apropos, and I would agree default could certainly be 'Silent' mode. Probably secrets should never be displayed. PII is also interesting...I can see a developer going to appropriate lengths to protect PII in the way he handles/stores data traversing the API being foiled by the person running the app simply prepending an env variable enabling debug logging output. Perhaps redact certain fields (user email: hidden, userId: shown)?

[cmlccie]

From a logging level perspective, and in line with our core goal to expose the Webex APIs and provide a Python-native and natural experience, we will use the Python logging system and established logging levels.

I'd love feedback at what the community would like to see at these various levels. Here are some thoughts based on what we are doing today and planning for the future:

Level	Uses / Potential Uses
CRITICAL	Unrecoverable errors? Today the library doesn' have any of these. These are normally raised by the application runtime code.
ERROR	We can and probably should log the ApiErrors that are raised by the library.
WARNING	We can and probably should log the ApiWarnings that are raised by the library.
INFO	Add transparency logging messages that visualize the operations the library is performing for you (requesting additional pages, handling ApiErrors like rate-limiting, etc.).
DEBUG	Somewhat detailed request tracing (log API requests and responses), needs to sanitize or exclude bodies to protect PII.
NOTSET	Silent. Don't log anything! 😎