Debugging

The MongoDB server runs as a long-lived multi-threaded C++ process; debugging it usually means reading logs, attaching a debugger, or enabling fail points and diagnostic counters.

Logs

mongod and mongos use the logv2 structured logging system (src/mongo/logv2/). Logs are JSON by default and tagged with a stable component name, severity, and a numeric id that you can grep on. The system is documented in docs/logging.md and summarized on the logv2 page.

To get more detail at runtime:

// In jstestshell or mongosh:
db.adminCommand({
  setParameter: 1,
  logComponentVerbosity: { command: { verbosity: 2 } },
});

To follow specific subsystems (replication, sharding, query) raise their verbosity individually. The component tree is defined in src/mongo/logv2/log_component.cpp.

Stack traces

When mongod crashes, it prints a stack trace and writes diagnostic data to the data directory. The traces include source locations from the binary's debug symbols. To decode an obfuscated trace, use the script described in docs/parsing_stack_traces.md:

buildscripts/parse_stacktrace.py <crashlog.txt>

The lldb and gdb init files (.lldbinit, .gdbinit) configure useful pretty-printers for BSONObj, Status, OptionalBson, and the smart-pointer types used in the codebase.

Attaching a debugger

# Build with debug symbols (default in dbg mode)
bazel build --config=dbg install-mongod

# Run under gdb
gdb --args bazel-bin/install/bin/mongod --dbpath /tmp/mongo-data

For live processes, attach by PID:

gdb -p $(pgrep mongod)

The pretty-printers handle most common types out of the box. print bson (when iterating BSON elements) and mongo-decoration (a custom command for decorations on OperationContext) help unwind common types.

Fail points

Fail points are runtime-controllable hooks named in code via MONGO_FAIL_POINT_DEFINE (or compiler-time families) and toggled by tests via configureFailPoint. They can be used to inject errors, delays, or take a fixed branch through a code path. See Fail points and docs/fail_points.md.

// Pause oplog application on this secondary
db.adminCommand({ configureFailPoint: 'rsSyncApplyStop', mode: 'alwaysOn' });

// Re-enable
db.adminCommand({ configureFailPoint: 'rsSyncApplyStop', mode: 'off' });

The list of registered fail points is inspectable via db.adminCommand({ getFailPointInfo: 1 }).

Inspecting in-flight operations

db.currentOp({ active: true });

currentOp is implemented in src/mongo/db/curop.cpp and src/mongo/db/op_debug.cpp. Each thread that runs a command updates a CurOp instance with the command name, namespace, plan summary, lock acquisition timing, slow-query metrics, and so on. db.currentOp() aggregates these snapshots.

For long-running operations, also check:

• db.killOp(opid) — request cancellation.
• db.serverStatus() — process-wide counters.
• The slow-query log, controlled by slowOpThresholdMs and the profile collection.

Diagnostic data (FTDC)

The Full-Time Diagnostic Data Collector (src/mongo/db/ftdc/) writes a compressed, periodic snapshot of serverStatus, replSetGetStatus, and other administrative commands to the data directory. The output is the basis for support escalations. See src/mongo/db/ftdc/README* for the file layout and buildscripts/ftdc_to_csv.py to decode.

Common gotchas

• Hung writes are usually a missing WriteUnitOfWork::commit() or a thread holding a collection lock while waiting on a future. Check db.currentOp() and the globalLock and replicationCoordinator sections of serverStatus.
• "Operation was killed" typically means an interrupt was raised on the OperationContext — by killOp, maxTimeMS, replication state transition, or shutdown. The errInfo in the log entry will name the source.
• Mismatched feature flags look like commands that "should work" returning BadValue or unrecognized field errors. Check the FCV: db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 }).
• Sharded clusters add a layer of indirection: an error from mongos may originate from a single shard. The wire-protocol response includes topologyVersion and shard identifiers that point to the right node.

Local devcontainer

The .devcontainer/ directory provides a reproducible Docker-based dev environment. See docs/devcontainer-setup.md for usage. The image carries the supported toolchain, Bazel, and the Poetry virtualenv pre-installed.