==================
gdb-mongodb-server
==================
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.
.. code-block:: python
# 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.
.. pull-quote::
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:
.. code-block::
(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:
.. code-block:: python
(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.
Raw data
{
"_id": null,
"home_page": "https://github.com/visemet/gdb-mongodb-server",
"name": "gdbmongo",
"maintainer": "Max Hirschhorn",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "max.hirschhorn@mongodb.com",
"keywords": "mongo, mongodb, gdb",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8c/39/5593e3e545c40ceadcc00b4a869de58f6cd0ccb90e8f453ecdf56e9f6f5d/gdbmongo-0.15.1.tar.gz",
"platform": "linux",
"description": "==================\ngdb-mongodb-server\n==================\n\nAbout\n=====\n\nThe *gdbmongo* package contains GDB pretty printers and commands for\ndebugging the MongoDB Server. Its primary target audience is MongoDB\nemployees.\n\nMotivation\n----------\n\nThe *gdbmongo* package is mostly born out of joy from tinkering with\nlow-level constructs while writing GDB pretty printers. There are some\nexplicit areas for what it aims to achieve:\n\n1. GDB pretty printers and commands which only work against live MongoDB\n processes are of limited value. This is because the hang analyzer is\n only granted enough time in Evergreen to save a core file for each of\n the lingering processes. Further analysis is deferred until later by\n making use of these saved core files. GDB pretty printers and\n commands which are implemented by walking in-memory data structures\n and not by executing C++ code **can run against core dumps** and are\n therefore more widely applicable.\n\n2. New versions of the MongoDB Server are released regularly. Each new\n git branch fragments the tooling for testing the server. This can\n cause development on older branches to feel foreign and awkward\n because so many new enhancements were made in the meantime. Flipping\n the model so there\u2019s **a single version which attempts to work with\n all supported MongoDB versions** can potentially enable more things\n to \u201cjust work.\u201d Another way to think about it is that the new GDB\n pretty printers and commands may not be getting built for new MongoDB\n Server functionality and instead may be getting built for a\n newly-recognized debugging need.\n\nInstallation\n============\n\nThe *gdbmongo* package must be loaded into the Python installation that\nthe GDB process is running. In particular, launching ``gdb`` from within\na Python virtual environment won\u2019t give the GDB process access to the\nPython packages defined within the virtual environment. This is because\n``gdb`` is dynamically linked against *libpython* and therefore always\nuses the site-packages of the base installation.\n\nAdding the following snippet to a .gdbinit file will cause ``gdb`` at\nlaunch time to attempt to install the *gdbmongo* package if it isn\u2019t\nalready installed.\n\n.. code-block:: python\n\n # In your ~/.gdbinit:\n python\n try:\n import gdbmongo\n except ImportError:\n import sys\n if sys.prefix.startswith(\"/opt/mongodbtoolchain/\"):\n import subprocess\n subprocess.run([sys.prefix + \"/bin/python3\", \"-m\", \"pip\", \"install\", \"gdbmongo\"], check=True)\n import gdbmongo\n else:\n import warnings\n warnings.warn(\"Not attempting to install gdbmongo into non MongoDB toolchain Python\")\n\n if \"gdbmongo\" in dir():\n gdbmongo.register_printers()\n end\n\nIf you don\u2019t plan to use the GDB pretty printers defined in the\nmongodb/mongo repository then you may want to consider enabling some of\nthe other printers defined by the *gdbmongo* package by default.\n\n.. pull-quote::\n\n register_printers(\\*, essentials=True, stdlib=False, abseil=False, boost=False, mongo_extras=False)\n Register the pretty printers defined by the gdbmongo package with GDB itself.\n\n The pretty printer collections other than gdbmongo-essentials are defaulted to off to avoid\n conflicting with the pretty printers defined in the mongodb/mongo repository.\n\nRegardless of whether you choose to enable these other pretty printers\nby default, each of the gdbmongo-\\* pretty printer collections can still\nbe enabled later on within GDB. For example, the gdbmongo-mongo-extras\npretty printer collection can be enabled with the following command:\n\n.. code-block::\n\n (gdb) enable pretty-printer global gdbmongo-mongo-extras\n\n*Tip*: Use ``info pretty-printer``, ``enable pretty-printer``,\n``disable pretty-printer``, and ``print /r`` to inspect and toggle the\nstate of any GDB pretty printers.\n\nUsage\n=====\n\nThe *gdbmongo* package is a nascent GDB extension and quite limited in\nwhat it can do right now. But, if you\u2019re looking to dump the contents of\nthe global ``LockManager`` in a core dump, then you can run the\nfollowing commands:\n\n.. code-block:: python\n\n (gdb) python lock_mgr = gdbmongo.LockManagerPrinter.from_global()\n (gdb) python print(lock_mgr.val)\n\nChangelog\n=========\n\n0.15.1 (2024-05-19)\n-------------------\n\n* Fix detecting libstdc++ version for Clang sanitizer builds.\n* Fix listing decorations of MongoDB 8.0. This includes accessing LockManager on global\n ServiceContext.\n\n0.15.0 (2024-04-29)\n-------------------\n\n* Support dumping LockManager from core dump of MongoDB 8.0.\n* Fix mongo::StringData pretty printer and mongo::BSONObj pretty printer which consumes it.\n\n0.14.0 (2023-09-30)\n-------------------\n\n* Include OperationContext* in output for LockManager dump.\n\n0.13.0 (2023-09-29)\n-------------------\n\n* Include thread\u2019s name and number in output for LockManager dump.\n* Fix detecting compiler version when cross-platform debugging.\n\n0.12.0 (2023-09-22)\n-------------------\n\n* Support displaying thread names in core dump of MongoDB 4.4, 5.0, and 6.0.\n\n0.11.0 (2023-09-16)\n-------------------\n\n* Support displaying contents of partitions within CursorManager.\n\n0.10.0 (2023-09-03)\n-------------------\n\n* Support dumping LockManager from core dump of MongoDB 7.1.\n\n0.9.0 (2023-08-26)\n------------------\n\n* Support dumping LockManager from core dump of MongoDB 7.0.\n\n0.8.1 (2023-03-04)\n------------------\n\n* Fix two Python exceptions from thread names logic when no program or core dump was loaded.\n* Fix boost::optional pretty printer for scalar types.\n\n0.8.0 (2023-02-04)\n------------------\n\n* Always register gdbmongo pretty printers with GDB itself but continue defaulting them to off.\n* Support displaying thread names in core dump of MongoDB 6.2.\n\n0.7.0 (2022-12-24)\n------------------\n\n* Support binaries built with MongoDB v4 toolchain.\n\n0.6.0 (2022-11-18)\n------------------\n\n* Support dumping LockManager from core dump of MongoDB 6.2.\n* Fix resource type names in output of MongoDB 4.4.15, 5.0.10, and 6.0.0.\n\n0.5.1 (2022-08-25)\n------------------\n\n* Fix detecting MongoDB toolchain from --install-action=hardlink executables.\n\n0.5.0 (2022-07-31)\n------------------\n\n* Format BSON binary subtype 4 as UUID.\n* Include ErrorExtraInfo in output for Status and StatusWith<T>.\n\n0.4.0 (2022-04-09)\n------------------\n\n* Support detecting libstdc++ version in MongoDB binaries back to 4.2.0 and 4.4.0.\n* Support decoding BSONObjs even when they contain dates exceeding datetime.MAXYEAR (= 9999).\n\n0.3.0 (2022-03-26)\n------------------\n\n* Include database name in dump of DatabaseShardingState ResourceMutexes.\n* Avoid truncating namespace strings in LockManager dump.\n\n0.2.0 (2022-03-05)\n------------------\n\n* Support dumping LockManager from core dump of MongoDB 4.2, 4.4, and 5.0.\n\n0.1.0 (2022-02-26)\n------------------\n\n* Initial release.\n* Support dumping LockManager from core dump of MongoDB 5.3.\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "GDB pretty printers and commands for debugging the MongoDB Server",
"version": "0.15.1",
"project_urls": {
"Homepage": "https://github.com/visemet/gdb-mongodb-server"
},
"split_keywords": [
"mongo",
" mongodb",
" gdb"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c0fb83421cac3d672165862c9d9cc670c90ade66029dcf8a9c10d61c9470dae",
"md5": "4e5fcdfe0ebe46af2f481afc65929972",
"sha256": "92348f382540405b8c2359d13de8b0f6bcaad3b9dd18d9ebcfbef98cf21d3990"
},
"downloads": -1,
"filename": "gdbmongo-0.15.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e5fcdfe0ebe46af2f481afc65929972",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 65385,
"upload_time": "2024-05-20T03:58:59",
"upload_time_iso_8601": "2024-05-20T03:58:59.236616Z",
"url": "https://files.pythonhosted.org/packages/9c/0f/b83421cac3d672165862c9d9cc670c90ade66029dcf8a9c10d61c9470dae/gdbmongo-0.15.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8c395593e3e545c40ceadcc00b4a869de58f6cd0ccb90e8f453ecdf56e9f6f5d",
"md5": "0ec23e2be63e675532f36bd8e070aaa6",
"sha256": "09764667574705d1bfa1bab5221087d81305a15f7e88745057fc06e0c7b4d439"
},
"downloads": -1,
"filename": "gdbmongo-0.15.1.tar.gz",
"has_sig": false,
"md5_digest": "0ec23e2be63e675532f36bd8e070aaa6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 58695,
"upload_time": "2024-05-20T03:59:01",
"upload_time_iso_8601": "2024-05-20T03:59:01.046690Z",
"url": "https://files.pythonhosted.org/packages/8c/39/5593e3e545c40ceadcc00b4a869de58f6cd0ccb90e8f453ecdf56e9f6f5d/gdbmongo-0.15.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-20 03:59:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "visemet",
"github_project": "gdb-mongodb-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "gdbmongo"
}
JSON
