Skip to content

Add MongoDB driver handshake metadata#821

Open
alexbevi wants to merge 1 commit into
apache:mainfrom
alexbevi:add-client-metadata
Open

Add MongoDB driver handshake metadata#821
alexbevi wants to merge 1 commit into
apache:mainfrom
alexbevi:add-client-metadata

Conversation

@alexbevi

Copy link
Copy Markdown

Summary

This PR identifies Burr in the MongoDB driver handshake, enabling server-side telemetry to attribute connections back to the library. MongoDB records this metadata at connection time, making it visible incurrentOp, Atlas performance advisor, and mongod logs.

What changes

A module-level constant is defined once in b_pymongo.py:

_DRIVER_INFO = DriverInfo(name="Burr", version=_VERSION)

This is injected at every MongoClient construction site and, for the case where a caller passes in an existing client, via append_metadata.

How it appears in the logs

On a MongoDB 4.4+ server, the isMaster/hello handshake carries the
following client metadata document (truncated to key fields):

{
  "driver": {
    "name": "PyMongo|Burr",
    "version": "4.9.2|0.42.0"
  },
  "platform": "CPython 3.10.3.final.0"
}

In mongod diagnostic logs this appears as:

{"t":{"$date":"..."},"s":"I","c":"NETWORK","id":51800,"ctx":"conn1","msg":"client metadata","attr":{"remote":"127.0.0.1:54321","client":"conn1","doc":{"driver":{"name":"PyMongo|Burr","version":"4.9.2|0.42.0"},...}}}

The PyMongo|Burr driver name lets operators distinguish Burr connections from bare PyMongo connections in server logs, Atlas metrics, and db.currentOp().

Testing

Six unit tests added in tests/integrations/persisters/test_b_pymongo_driver_info.py
(no live database required):

  • _DRIVER_INFO has name="Burr" and version matching the installed package
  • from_values() passes driver=_DRIVER_INFO to MongoClient
  • from_values() does not override a caller-supplied driver
  • __init__() calls append_metadata(_DRIVER_INFO) when the client supports it
  • __init__() does not raise when the client lacks append_metadata (older pymongo)

No version constraint change is needed — DriverInfo is available since
pymongo 4.0, and append_metadata since 4.14; the existing unconstrained
"pymongo" dependency satisfies both.

Checklist

  • PR has an informative and human-readable title (this will be pulled into the release notes)
  • Changes are limited to a single goal (no scope creep)
  • Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
  • Any change in functionality is tested
  • New functions are documented (with a description, list of inputs, and expected output)
  • Placeholder code is flagged / future TODOs are captured in comments
  • Project documentation has been updated if adding/changing functionality.

Identify Burr in the MongoDB handshake so server-side telemetry can
distinguish Burr traffic. A module-level constant
_DRIVER_INFO = DriverInfo(name="Burr", version=_VERSION) is defined
once in b_pymongo.py and used at every client construction site.

b_pymongo.MongoDBBasePersister has three patterns:

  Pattern A – from_values() constructs MongoClient:
    mongo_client_kwargs.setdefault("driver", _DRIVER_INFO) guards against
    overriding a caller-supplied driver value.

  Pattern B – __init__() receives an existing client:
    if hasattr(client, "append_metadata"): client.append_metadata(_DRIVER_INFO)
    append_metadata is idempotent; the hasattr guard keeps this safe with
    older pymongo versions that predate the API.

  Pattern A – __setstate__() reconstructs MongoClient after unpickling:
    driver=_DRIVER_INFO passed directly.

b_mongodb.py is a deprecated shim that constructs its own MongoClient
instances in from_values() and __init__(). Both receive the same
setdefault guard, importing _DRIVER_INFO from b_pymongo.py.

Version is read via importlib.metadata("apache-burr") with a try/except
fallback so it works whether or not the package is pip-installed.

Adds tests/integrations/persisters/test_b_pymongo_driver_info.py
(no live DB required) verifying all five behaviours:
- _DRIVER_INFO has name="Burr" and matches the installed version
- from_values() passes driver=_DRIVER_INFO to MongoClient
- from_values() does not override a caller-supplied driver
- __init__() calls append_metadata(_DRIVER_INFO) when the client supports it
- __init__() does not raise when client lacks append_metadata

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added area/storage Persisters, state storage area/integrations External integrations (LLMs, frameworks) labels Jun 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/integrations External integrations (LLMs, frameworks) area/storage Persisters, state storage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant