Document db.operation.name discrepancies and add missing covered operations

XMLWordPrintableJSON

    • Type: Task
    • Resolution: Unresolved
    • Priority: Major - P3
    • None
    • Component/s: Observability
    • None
    • Needed - No Spec Changes
    • Hide

      Summary of necessary driver changes

      •  

      Commits for syncing spec/prose tests
      (and/or refer to an existing language POC if needed)

      •  

      Context for other referenced/linked tickets

      •  
      Show
      Summary of necessary driver changes   Commits for syncing spec/prose tests (and/or refer to an existing language POC if needed)   Context for other referenced/linked tickets  
    • $i18n.getText("admin.common.words.hide")
      Key Status/Resolution FixVersion
      CDRIVER-6438 Blocked
      CXX-3564 Blocked
      CSHARP-6203 Blocked
      GODRIVER-4107 Blocked
      JAVA-6295 Blocked
      NODE-7795 Blocked
      PYTHON-6054 Ready for Work
      PHPLIB-1940 Blocked
      RUBY-3949 Blocked
      RUST-2485 Blocked
      $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 */ } #scriptField td.willNotDo { background-color: #FF0000; /* Red color code */ } /* Center-align the first row headers */ #scriptField th { text-align: center; } Key Status/Resolution FixVersion CDRIVER-6438 Blocked CXX-3564 Blocked CSHARP-6203 Blocked GODRIVER-4107 Blocked JAVA-6295 Blocked NODE-7795 Blocked PYTHON-6054 Ready for Work PHPLIB-1940 Blocked RUBY-3949 Blocked RUST-2485 Blocked

      Summary

      Follow-up to the OTel db.operation.name work: the "Covered operations" table itself has a few discrepancies and is missing
      some standard operations.

      Background

      The spec implies db.operation.name follows the command name (see the findOneAndDelete/findAndModify note), and upstream OTel's MongoDB semantic conventions agree. These two operations do not match their command name:

      • createCollection (command: create)
      • dropCollection (command: drop)

      Both the Java and C# drivers have shipped with these names, so we should keep them and document the discrepancies.

      The table is also missing the following operations:

      • renameCollection (command: renameCollection)
      • countDocuments (command: aggregate)
      • collection bulkWrite (commands: insert, update, delete)
      • watch (command: aggregate)

      I propose countDocuments and watch as the operation names to be more descriptive on intent.
      For collection bulkWrite, I propose we match the logic in C#: use bulkWrite for mixed operations, and insert, delete, or update for uniform operations.

      Both Java and C# use the same underlying logic to derive the operation names for OTel and Server Selection Logging, so we should
      enforce and cross-link them in the spec.

      Finally, there are a few entries that have errors: estimatedDocumentCount is actually called count in the unified test,
      and the last two rows have swapped links: updateSearchIndex points to delete.yml and delete points to atlas_search.yml

      Separately, the spec names operations sent through the generic runCommand API runCommand, but only addresses the helper that returns a document. The cursor-returning helper (Database.cursor_command in PyMongo) is unspecified, so db.command("listCollections") and db.cursor_command("listCollections") can report different db.operation.name for the same command.

      Proposed changes

      Document, don't rename:

      • createCollection and dropCollection appear to be oversights, but renaming now would cause churn across driver releases and require skip conditions in unified tests. Document the discrepancy in the table instead of renaming.
      • withTransaction has no underlying command and should be called out as an outlier.

      Rename in the table:

      • estimatedDocumentCount is the CRUD spec helper name, but the operation name we actually use is count. Update the table entry to count and call out the discrepancy.

      Fix broken links:

      • The last two rows have swapped links: updateSearchIndex points to delete.yml and delete points to atlas_search.yml. Fix both.

      Add missing operations:

      • Add countDocuments and watch operations and use their logical names instead of aggregate. List the discrepancy.
      • Add renameCollection, which cleanly maps to the renameCollection command.

      Collection-level bulkWrite:

      • bulk_write.yml covers only the client-level helper; collection-level bulkWrite is unspecified. Collection bulkWrite sends insert, update, and delete commands. We follow the example of C# and use bulkWrite for mixed operations
        and the operation name for uniform operations.

      Generic cursor-returning commands:

      • Decide whether a generic command helper that returns a cursor reports runCommand. If it does, define db.namespace and db.collection.name for that span, since unlike Database.command it usually targets a collection.

      Unified spec tests
      We add new spec test files for countDocuments, renameCollection, watch, and collection bulkWrite, plus a generic cursor-returning command.

      Server Selection Logging
      Update the server selection logging spec to point to the table in OTel for the definitive list of operation names.
      Add unified test files covering all the names in the table, to ensure they agree.

      Scope

      This should land as a single PR that updates the OTel spec's "Covered operations" table and description, the server selection
      logging spec's description of operation names, and unified test files for both.

            Assignee:
            Steve Silvester
            Reporter:
            Steve Silvester
            Nabil Hachicha Nabil Hachicha
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated: