[DRIVERS-2516] Misc Updates to Logging Spec Created: 08/Dec/22  Updated: 21/Aug/23

Status: Implementing
Project: Drivers
Component/s: Logging
Fix Version/s: None

Type: Spec Change Priority: Major - P3
Reporter: Bailey Pearson Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Issue split
split to CDRIVER-4535 Misc Updates to Logging Spec Backlog
split to CXX-2626 Misc Updates to Logging Spec Backlog
split to CSHARP-4450 Misc Updates to Logging Spec Closed
split to GODRIVER-2688 Misc Updates to Logging Spec Closed
split to JAVA-4829 Misc Updates to Logging Spec Closed
split to MOTOR-1074 Misc Updates to Logging Spec Closed
split to NODE-4882 Misc Updates to Logging Spec Closed
split to PHPLIB-1050 Misc Updates to Logging Spec Closed
split to PYTHON-3537 Misc Updates to Logging Spec Closed
split to RUBY-3196 Misc Updates to Logging Spec Closed
split to RUST-1555 Misc Updates to Logging Spec Closed
Epic Link: Easier debugging with standardized logging
Driver Changes: Needed
Quarter: FY23Q3, FY23Q4, FY24Q1
Downstream Changes Summary:

If a driver has not started implementing logging yet, this ticket could be closed in favor of the original tickets around implementing the logging spec and adding log messages for other specs. All possible changes required by this ticket are captured in the text of the relevant specs.

Drivers who have already implemented or are in the process of implementing logging should review the changes in this commit and ensure their implementations comply. To summarize what changed:

  • For command log messages, when the user does not specify a port for a host and is therefore relying on the default 27017, the driver SHOULD include that default in log messages.
  • The suggested unstructured representations for command log messages have been slightly modified to match the CMAP log messages.
  • It's no longer a strict requirement that drivers support logging directly to a file. Instead, it is sufficient to provide a straightforward API that would allow a user to direct log messages to a file.
  • Clarify that drivers MAY attempt to warn users about invalid values of environment variables, but MUST NOT throw an error.
  • Require that if a driver supports configuring logging both via environment variables and programmatically, the programmatic configuration should take precedence.
  • Rationale sections were added for the previous two bullet points.
Start date:
Driver Compliance:
Key Status/Resolution FixVersion
CDRIVER-4535 Backlog
CXX-2626 Backlog
CSHARP-4450 Won't Fix
GODRIVER-2688 Duplicate
JAVA-4829 Duplicate
NODE-4882 Fixed 6.1.0
MOTOR-1074 Won't Do
PYTHON-3537 Won't Do
PHPLIB-1050 Duplicate
RUBY-3196 Done
RUST-1555 Duplicate
SWIFT-1684 Duplicate

 Description   

Summary

What is the problem or use case, what are we trying to achieve?

There was extended discussion in the DRIVERS-1208 logging slack channel about some modifications to the logging specification.  The slack discussion can be found [here|https://mongodb.slack.com/archives/G015EB3QHED/p1669665126177999].

The changes are summarized below:

  1. add rationale for the currently described behavior around “treating invalid values of env variables as if they were not specified at all”
  2. mention that programmatic configuration MUST win out over environment variables if a driver supports both and drivers SHOULD document how to have dynamic configuration via env var override programmatic config
  3. mention drivers MAY (SHOULD?) attempt to warn users about the misconfiguration via log messages or otherwise
  4. drivers MAY but are not required to directly support logging to an arbitrary file. if they do not support it, they MUST at least provide a straightforward, idiomatic way for users to programmatically consume messages for writing to a file and they MUST provide a basic documentation example showing how to do this.

Additionally, some minor changes should be made to the command logging and monitoring spec such that its representations of server addresses are consistent with decisions made in DRIVERS-1675.

Motivation

Who is the affected end user?

Drivers engineers implementing the logging spec.

How does this affect the end user?

Some drivers are 

How likely is it that this problem or use case will occur?

n/a

If the problem does occur, what are the consequences and how severe are they?

n/a

Is this issue urgent?

Does this ticket have a required timeline? What is it?

Is this ticket required by a downstream team?

No.

Is this ticket only for tests?

No.



 Comments   
Comment by Githook User [ 05/Jan/23 ]

Author:

{'name': 'Kaitlin Mahar', 'email': 'kaitlin.mahar@mongodb.com', 'username': 'kmahar'}

Message: DRIVERS-2516 Collection of follow-up logging changes (#1356)
Branch: master
https://github.com/mongodb/specifications/commit/e9b4c96f3ff9b639c61feb7ed149ed14b59aabb6

Generated at Thu Feb 08 08:25:47 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.