[CDRIVER-4485] Easier debugging with standardized logging: logging specification Created: 07/Oct/22  Updated: 26/Sep/23

Status: Backlog
Project: C Driver
Component/s: Logging
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Major - P3
Reporter: PM Bot Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by PHPLIB-998 Easier debugging with standardized lo... Blocked
Issue split
split from DRIVERS-1677 Easier debugging with standardized lo... Implementing
Related
related to CDRIVER-4501 Add log messages to CMAP spec Closed
related to PHPC-2180 Allow applications to register a LogS... Closed
Epic Link: Easier debugging with standardized logging
Upstream Changes Summary:

DRIVERS-1677:
I suggest that drivers do their implementation of this ticket in tandem with their implementation of DRIVERS-1673 which adds command log messages. This way the driver will have actual log messages to emit and test and can confirm that their logging implementation and test code works as expected.

The logging spec can be found here.

The unified test format changes can be found here. To summarize:

  • Client entities may now have a new observeLogMessages property specifying logging configuration for the client
  • Tests may now have a new expectLogMessages property specifying expected log messages to be produced during the test
  • Two new special matching operators $$matchAsRoot and $$matchAsDocument have been added to enable logging assertions.
     

 Description   

This ticket was split from DRIVERS-1677, please see that ticket for a detailed description.



 Comments   
Comment by Kevin Albertson [ 11/Sep/23 ]

In that case, what would become of libmongoc's MONGOC_LOG_LEVEL_CRITICAL value? Would it retain the same definition but remain unused?

I expect "yes". MONGOC_LOG_LEVEL_CRITICAL is part of the public API. It could be considered for deprecation.

would it be worth defining constants for the min/max values of the mongoc_log_level_t enum

I suggest a validation function be introduced (maybe named: mongoc_log_level_is_valid(int);), so the integer min/max values are not added to public ABI.

Comment by Jeremy Mikola [ 11/Sep/23 ]

kevin.albertson@mongodb.com: In that case, what would become of libmongoc's MONGOC_LOG_LEVEL_CRITICAL value? Would it retain the same definition but remain unused?

On a related note, would it be worth defining constants for the min/max values of the mongoc_log_level_t enum so that consumers of libmongoc can apply some validation? As I'm implementing an API in PHPC-2180 that allows applications to both capture and write log messages, I found myself wanting some way to prohibit users from sending invalid log levels. I considered just comparing the integer argument against MONGOC_LOG_LEVEL_TRACE and MONGOC_LOG_LEVEL_ERROR but thought that may lead to trouble down the line if additional levels are introduced to comply with the Logging spec.

Comment by Kevin Albertson [ 01/Sep/23 ]

The specification defines Critical as more severe than Error.
libmongoc defines MONGOC_LOG_LEVEL_CRITICAL as less severe than MONGOC_LOG_LEVEL_ERROR.

At present, the specification does not use the Critical level. libmongoc does not log anything with MONGOC_LOG_LEVEL_CRITICAL.

If the specification adds Critical log messages in the future, I propose libmongoc log those with MONGOC_LOG_LEVEL_ERROR (not MONGOC_LOG_LEVEL_CRITICAL). Drivers are expected to log Critical messages if the application is configured to log Error or more severe:

drivers MUST emit messages for that level at the closest, less severe level if one is available, or the closest more severe level otherwise.

Generated at Wed Feb 07 21:21:03 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.