Uploaded image for project: 'Drivers'
  1. Drivers
  2. DRIVERS-2516

Misc Updates to Logging Spec

XMLWordPrintableJSON

    • Type: Icon: Spec Change Spec Change
    • Resolution: Unresolved
    • Priority: Icon: Major - P3 Major - P3
    • None
    • Component/s: Logging
    • None
    • Needed
    • Hide

      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.
      Show
      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.
    • $i18n.getText("admin.common.words.hide")
      Key Status/Resolution FixVersion
      CDRIVER-4535 In Code Review
      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
      $i18n.getText("admin.common.words.show")
      #scriptField, #scriptField *{ border: 1px solid black; } #scriptField{ border-collapse: collapse; } #scriptField td { text-align: center; /* Center-align text in table cells */ } #scriptField td.key { text-align: left; /* Left-align text in the Key column */ } #scriptField a { text-decoration: none; /* Remove underlines from links */ border: none; /* Remove border from links */ } /* Add green background color to cells with FixVersion */ #scriptField td.hasFixVersion { background-color: #00FF00; /* Green color code */ } /* Center-align the first row headers */ #scriptField th { text-align: center; } Key Status/Resolution FixVersion CDRIVER-4535 In Code Review 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

      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.

            Assignee:
            Unassigned Unassigned
            Reporter:
            bailey.pearson@mongodb.com Bailey Pearson
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated: