Standardizing logging across commands

[Jwaegebaert]

We're aiming to enhance the clarity and consistency of verbose and debug messages across our commands. This effort will help make our logging more uniform and informative. Below is the first draft of some guidelines on how and when to implement each type of logging.

Verbose Logging

• Prefix each log entry with a timestamp to aid in debugging and tracing. Format: [YYYY-MM-DD HH:MM:SS] Message
  • Here I would even look into coloring the timestamp clearly to make it more visual.
  • Maybe even work out some logic where we add some more whitespace after each log.
• Begin each command with a concise description of its action, e.g., [2024-03-23 15:45:15] Listing all Teams Apps...
• Log each API endpoint called, e.g., [2024-03-23 15:45:30] GET: "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=distributionMethod eq 'organization'"

Debug Logging

• Focus on logging internal processes, such as received options, token validity, the complete API request being made, and timing reports.
• Avoid adding custom logs in commandAction to explain actions being performed. If they want to do this, it should be a verbose log instead.

---

To facilitate the changes suggested for verbose logging, I propose adding a new property to Logger, such as logger.logVerbose. This will allow us to centralize the logic for checking the verbose flag and formatting messages with a timestamp in cli.ts. Consequently, writing verbose messages within commandAction will become more straightforward.

Implementation Steps

• [ ] Explore NPM packages for logging usage.
• [ ] Finalize the guidelines.
• [ ] Define the next steps. ...
• [ ] Apply these changes to each command.

[Adam-it]

good call. One comment from my side is that I would avoid adding custom color to a response. Nowadays terminals are full of customization and one may any terminal background color ... yes even white 😮😉, or blue or red etc. it's going to be hard to define a color which will be visible in any background. Thats why i would leave the default one and let the terminal theme functionalities work on the UI part

[Jwaegebaert]

@Adam-it, good point. Picking a single color from so many options isn't straightforward. We already use chalk to set colors in a few spots for logging. My suggestion is to stick with gray for the timestamp and keep everything else the same. But that's not a major feature here, just an idea 😄. The first step is to decide on the layout. So, @pnp/cli-for-microsoft-365-maintainers, any thoughts?

[waldekmastykarz]

Many node apps use the debug library for logging. What's great about it, is that it's widely used, and offers a standardized way of logging that folks already know, comes with coloring, printing time, etc. Not saying that we should adapt that exact package, but let's consider what's already out there and weigh it as an option in our decision.

[Jwaegebaert]

That's a great idea to check out existing libraries. I just took a quick look at debug and it seems pretty clean. One small thing to note, though, is that it doesn't look like it's actively maintained anymore. I'll add a step to explore some existing libraries to see what they offer.