gdbmongo

What it is and what it does

Gdbmongo is a GDB extension that adds pretty printers and debugging commands specifically for MongoDB Server internals. It is designed primarily for MongoDB employees and contributors who need to inspect server state during development and troubleshooting. The package walks in-memory data structures rather than executing C++ code, which allows it to work against both live processes and saved core dumps—a critical capability for post-mortem analysis in CI/CD environments.

The package targets a moving target: instead of fragmenting tools across each MongoDB version branch, gdbmongo aims to be a single version that works across multiple supported MongoDB releases. It currently supports dumping the global LockManager, displaying thread names, inspecting CursorManager partitions, and decoding BSON objects. Installation requires manual setup in GDB's Python environment (not a virtual environment), and pretty printer collections can be selectively enabled or disabled within GDB.

Use it for:

• Analyze MongoDB server core dumps in CI/CD pipelines to diagnose hangs, crashes, or resource contention without rebuilding the server.
• Inspect the global LockManager state in a running MongoDB process to understand lock holders and waiters during development.
• Decode BSON objects and thread metadata in core dumps to reconstruct server state at the time of failure.
• Debug MongoDB 4.2 through 8.1 binaries with a single tool version instead of maintaining branch-specific GDB extensions.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Gdbmongo provides GDB pretty printers and commands for inspecting MongoDB Server internals in live processes and core dumps, with support for multiple MongoDB versions.

Yes, if you are debugging MongoDB Server internals or analyzing MongoDB core dumps. The package is low-friction to install, has no runtime dependencies, and is actively maintained for recent MongoDB versions. No, if you are not working on MongoDB Server itself or do not have access to GDB with Python support in your environment.

Install

gdbmongo on PyPI

pip install gdbmongo

uv add gdbmongo

poetry add gdbmongo

Installing gdbmongo

Before you install

Low install friction with no runtime dependencies. Maintenance is dormant but recent—last commit 2025-02-13—and the package is actively tested against current MongoDB versions. Installation requires manual setup in GDB's Python environment, not a standard virtual environment.

License in practice

Apache License 2.0 is permissive; you may use, modify, and distribute this package freely in commercial and private projects provided you include the license notice.

Quickstart

# Add to ~/.gdbinit:
python
import gdbmongo
gdbmongo.register_printers()
end

# In GDB:
(gdb) python lock_mgr = gdbmongo.LockManagerPrinter.from_global()
(gdb) python print(lock_mgr.val)

GDB must be linked against the same Python installation where gdbmongo is installed; virtual environments do not work because GDB uses the base system libpython.

Verify before relying

• Whether the package works reliably against all advertised MongoDB versions or only those explicitly tested in recent releases.
• Performance impact of pretty printer registration on GDB startup time or responsiveness.
• Whether core dump analysis works across different architectures or only within the MongoDB toolchain environment.

Package facts

Evidence: gdbmongo-0.16.0-py3-none-any.whl

Keywords: mongo, mongodb, gdb

Tags

More Database packages