MONGOC_DEBUGGING(3)

🎀 MONGOC_DEBUGGING — libmongoc, bestie edition 🎀

okay so you're in libmongoc and something is Being Weird and you need to actually look inside your BSON. good news: there's tooling. bad news: it's in a manpage, and manpages are giving "assigned reading, 8am lecture". so sit down, hydrate, and let's go 💖

---

🌸 GDB 🌸

this repo ships a .gdbinit file, and inside it lives a lil collection of helper functions whose whole job is making data structures not a mystery. GDB will load it automatically — but only if two things are true, and the universe is picky about this:

1. you've added the directory containing the .gdbinit file to GDB's auto-load safe-path, and
2. you start GDB from the directory that holds the .gdbinit file.

you can peek at the safe-path right from a GDB prompt with:

show auto-load safe-path

and you can set it up by putting this in ~/.gdbinit:

add-auto-load-safe-path /path/to/mongo-c-driver

if you haven't added the path to your auto-load safe-path, or you started GDB from some other directory (we've all been there), just load it manually:

source path/to/mongo-c-driver/.gdbinit

the .gdbinit file defines the printbson function, which shows you the contents of a bson_t * variable. ✨ big deal, honestly. heads up though: if you've got a local bson_t, you must prefix the variable with a &. no skipping that, it's not optional, it's the law 💅

a whole GDB session looks like this:

(gdb) printbson bson
ALLOC [0x555556cd7310 + 0] (len=475)
{
    'bool' : true,
    'int32' : NumberInt("42"),
    'int64' : NumberLong("3000000042"),
    'string' : "Stŕìñg",
    'objectId' : ObjectID("5A1442F3122D331C3C6757E1"),
    'utcDateTime' : UTCDateTime(1511277299031),
    'arrayOfInts' : [
        '0' : NumberInt("1"),
        '1' : NumberInt("2")
    ],
    'embeddedDocument' : {
        'arrayOfStrings' : [
            '0' : "one",
            '1' : "two"
        ],
        'double' : 2.718280,
        'notherDoc' : {
            'true' : NumberInt("1"),
            'false' : false
        }
    },
    'binary' : Binary("02", "3031343532333637"),
    'regex' : Regex("@[a-z]+@", "im"),
    'null' : null,
    'js' : JavaScript("print foo"),
    'jsws' : JavaScript("print foo") with scope: {
        'f' : NumberInt("42"),
        'a' : [
            '0' : 3.141593,
            '1' : 2.718282
        ]
    },
    'timestamp' : Timestamp(4294967295, 4294967295),
    'double' : 3.141593
}

like… look at it. nested docs, arrays, regex, timestamps, the whole vibe. iconic 🌈

---

🦋 LLDB 🦋

LLDB girlies are not left out, do not worry. the mongo-c-driver repository contains a script called lldb_bson.py that you can import into an LLDB session, and it unlocks rich inspection of BSON values. rich!! 💜

NOTE: the lldb_bson.py module requires an LLDB with Python 3.8 or newer. check your Python, bestie, don't get got.

to activate the script, import it straight from the LLDB command line:

(lldb) command script import /path/to/mongo-c-driver/lldb_bson.py

if it worked, you'll see this printed to the LLDB console:

lldb_bson is ready

and that message is lowkey so satisfying, it's giving main character energy 👑

you can make that import automatic too, by adding the command to an .lldbinit file. for example, create a file ~/.lldbinit containing:

command script import /path/to/mongo-c-driver/lldb_bson.py

there's a docstring at the top of the lldb_bson.py file with way more info on what the module can actually do — go read it, it ate 🍓

---

🔥 DEBUG ASSERTIONS 🔥

want runtime debug assertions? say less. just configure with:

-DENABLE_DEBUG_ASSERTIONS=ON

that's it. that's the whole vibe check ✅

---

💖 AUTHOR 💖

MongoDB, Inc

---

💅 COPYRIGHT 💅

2017-present, MongoDB, Inc

---

okay that's the whole page, you're officially certified 🫶 this was MONGOC_DEBUGGING(3) from libmongoc, version 1.26.0, dated Mar 31, 2024. go debug something and slay, bestie 💖✨🎀