Skip to main content

GDB pretty printers and commands for debugging the MongoDB Server

Project description

About

The gdbmongo package contains GDB pretty printers and commands for debugging the MongoDB Server. Its primary target audience is MongoDB employees.

Motivation

The gdbmongo package is mostly born out of joy from tinkering with low-level constructs while writing GDB pretty printers. There are some explicit areas for what it aims to achieve:

  1. GDB pretty printers and commands which only work against live MongoDB processes are of limited value. This is because the hang analyzer is only granted enough time in Evergreen to save a core file for each of the lingering processes. Further analysis is deferred until later by making use of these saved core files. GDB pretty printers and commands which are implemented by walking in-memory data structures and not by executing C++ code can run against core dumps and are therefore more widely applicable.

  2. New versions of the MongoDB Server are released regularly. Each new git branch fragments the tooling for testing the server. This can cause development on older branches to feel foreign and awkward because so many new enhancements were made in the meantime. Flipping the model so there’s a single version which attempts to work with all supported MongoDB versions can potentially enable more things to “just work.” Another way to think about it is that the new GDB pretty printers and commands may not be getting built for new MongoDB Server functionality and instead may be getting built for a newly-recognized debugging need.

Installation

The gdbmongo package must be loaded into the Python installation that the GDB process is running. In particular, launching gdb from within a Python virtual environment won’t give the GDB process access to the Python packages defined within the virtual environment. This is because gdb is dynamically linked against libpython and therefore always uses the site-packages of the base installation.

Adding the following snippet to a .gdbinit file will cause gdb at launch time to attempt to install the gdbmongo package if it isn’t already installed.

# In your ~/.gdbinit:
python
try:
    import gdbmongo
except ImportError:
    import sys
    if sys.prefix.startswith("/opt/mongodbtoolchain/"):
        import subprocess
        subprocess.run([sys.prefix + "/bin/python3", "-m", "pip", "install", "gdbmongo"], check=True)
        import gdbmongo
    else:
        import warnings
        warnings.warn("Not attempting to install gdbmongo into non MongoDB toolchain Python")

if "gdbmongo" in dir():
    gdbmongo.register_printers()
end

If you don’t plan to use the GDB pretty printers defined in the mongodb/mongo repository then you may want to consider enabling some of the other printers defined by the gdbmongo package by default.

register_printers(*, essentials=True, stdlib=False, abseil=False, boost=False, mongo_extras=False)

Register the pretty printers defined by the gdbmongo package with GDB itself.

The pretty printer collections other than gdbmongo-essentials are defaulted to off to avoid conflicting with the pretty printers defined in the mongodb/mongo repository.

Regardless of whether you choose to enable these other pretty printers by default, each of the gdbmongo-* pretty printer collections can still be enabled later on within GDB. For example, the gdbmongo-mongo-extras pretty printer collection can be enabled with the following command:

(gdb) enable pretty-printer global gdbmongo-mongo-extras

Tip: Use info pretty-printer, enable pretty-printer, disable pretty-printer, and print /r to inspect and toggle the state of any GDB pretty printers.

Usage

The gdbmongo package is a nascent GDB extension and quite limited in what it can do right now. But, if you’re looking to dump the contents of the global LockManager in a core dump, then you can run the following commands:

(gdb) python lock_mgr = gdbmongo.LockManagerPrinter.from_global()
(gdb) python print(lock_mgr.val)

Changelog

0.15.1 (2024-05-19)

  • Fix detecting libstdc++ version for Clang sanitizer builds.

  • Fix listing decorations of MongoDB 8.0. This includes accessing LockManager on global ServiceContext.

0.15.0 (2024-04-29)

  • Support dumping LockManager from core dump of MongoDB 8.0.

  • Fix mongo::StringData pretty printer and mongo::BSONObj pretty printer which consumes it.

0.14.0 (2023-09-30)

  • Include OperationContext* in output for LockManager dump.

0.13.0 (2023-09-29)

  • Include thread’s name and number in output for LockManager dump.

  • Fix detecting compiler version when cross-platform debugging.

0.12.0 (2023-09-22)

  • Support displaying thread names in core dump of MongoDB 4.4, 5.0, and 6.0.

0.11.0 (2023-09-16)

  • Support displaying contents of partitions within CursorManager.

0.10.0 (2023-09-03)

  • Support dumping LockManager from core dump of MongoDB 7.1.

0.9.0 (2023-08-26)

  • Support dumping LockManager from core dump of MongoDB 7.0.

0.8.1 (2023-03-04)

  • Fix two Python exceptions from thread names logic when no program or core dump was loaded.

  • Fix boost::optional pretty printer for scalar types.

0.8.0 (2023-02-04)

  • Always register gdbmongo pretty printers with GDB itself but continue defaulting them to off.

  • Support displaying thread names in core dump of MongoDB 6.2.

0.7.0 (2022-12-24)

  • Support binaries built with MongoDB v4 toolchain.

0.6.0 (2022-11-18)

  • Support dumping LockManager from core dump of MongoDB 6.2.

  • Fix resource type names in output of MongoDB 4.4.15, 5.0.10, and 6.0.0.

0.5.1 (2022-08-25)

  • Fix detecting MongoDB toolchain from –install-action=hardlink executables.

0.5.0 (2022-07-31)

  • Format BSON binary subtype 4 as UUID.

  • Include ErrorExtraInfo in output for Status and StatusWith<T>.

0.4.0 (2022-04-09)

  • Support detecting libstdc++ version in MongoDB binaries back to 4.2.0 and 4.4.0.

  • Support decoding BSONObjs even when they contain dates exceeding datetime.MAXYEAR (= 9999).

0.3.0 (2022-03-26)

  • Include database name in dump of DatabaseShardingState ResourceMutexes.

  • Avoid truncating namespace strings in LockManager dump.

0.2.0 (2022-03-05)

  • Support dumping LockManager from core dump of MongoDB 4.2, 4.4, and 5.0.

0.1.0 (2022-02-26)

  • Initial release.

  • Support dumping LockManager from core dump of MongoDB 5.3.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gdbmongo-0.15.1.tar.gz (58.7 kB view details)

Uploaded Source

Built Distribution

gdbmongo-0.15.1-py3-none-any.whl (65.4 kB view details)

Uploaded Python 3

File details

Details for the file gdbmongo-0.15.1.tar.gz.

File metadata

  • Download URL: gdbmongo-0.15.1.tar.gz
  • Upload date:
  • Size: 58.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.10.4

File hashes

Hashes for gdbmongo-0.15.1.tar.gz
Algorithm Hash digest
SHA256 09764667574705d1bfa1bab5221087d81305a15f7e88745057fc06e0c7b4d439
MD5 0ec23e2be63e675532f36bd8e070aaa6
BLAKE2b-256 8c395593e3e545c40ceadcc00b4a869de58f6cd0ccb90e8f453ecdf56e9f6f5d

See more details on using hashes here.

File details

Details for the file gdbmongo-0.15.1-py3-none-any.whl.

File metadata

  • Download URL: gdbmongo-0.15.1-py3-none-any.whl
  • Upload date:
  • Size: 65.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.10.4

File hashes

Hashes for gdbmongo-0.15.1-py3-none-any.whl
Algorithm Hash digest
SHA256 92348f382540405b8c2359d13de8b0f6bcaad3b9dd18d9ebcfbef98cf21d3990
MD5 4e5fcdfe0ebe46af2f481afc65929972
BLAKE2b-256 9c0fb83421cac3d672165862c9d9cc670c90ade66029dcf8a9c10d61c9470dae

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page