MONGOC_BASIC_TROUBLESHOOTING(3)

📦
version 1.26.0 · 3 versions
, in ubuntu noble

💅 MONGOC_BASIC_TROUBLESHOOTING(3) 💅

okay bestie, welcome to the libmongoc glow-up guide ✨ this is the page you open when your C driver is acting up and you're like "why is this happening to me specifically 😭". no gatekeeping here, we're gonna walk through it together, hand in hand 🫶

🎀 TROUBLESHOOTING CHECKLIST 🎀

here's the short lil vibe-check list of stuff to look at when something's gone wrong:

  • did you actually call mongoc_init() in main()? if not, you're probably gonna get a segfault, no cap 💀 that one's on you boo.
  • have you leaked any clients or cursors? you can catch those with mongoc-stat <PID> 👀
  • have packets even made it to the server? check the egress bytes from mongoc-stat <PID> — if that number's giving zero, something's up.
  • does ASAN show any leaks? make sure you call mongoc_cleanup() at the end of your process so it cleans up the lingering allocations from the MongoDB C driver. closure is important, periodt 💖
  • if you're compiling your own copy of the MongoDB C Driver, lowkey consider using the cmake option -DENABLE_TRACING=ON to turn on function tracing and hex dumps of network packets to STDERR and STDOUT. it's giving debug era 🔍

✨ PERFORMANCE COUNTERS ✨

the MongoDB C Driver comes with an optional and genuinely unique feature to help developers and sysadmins troubleshoot problems in production. performance counters are available for each process using the C Driver. if available, the counters can be accessed outside of the application process via a shared memory segment — iconic behavior honestly 👑

and like, the counters can be used to graph statistics about your application process super easily from tools like Munin or Nagios 🌸 for example, the command

watch --interval=0.5 -d mongoc-stat $PID

may be used to monitor an application. look at her go 💅

performance counters are only available on Linux platforms and macOS arm64 platforms that support shared memory segments. on supported platforms, they are enabled by default ✨ applications can be built without the counters by specifying the cmake option -DENABLE_SHM_COUNTERS=OFF. and additionally, if performance counters are already compiled, they can be disabled at runtime by specifying the environment variable MONGOC_DISABLE_SHM. your choice, your rules 🎀

performance counters keep track of the following:

  • Active and Disposed Cursors
  • Active and Disposed Clients, Client Pools, and Socket Streams.
  • Number of operations sent and received, by type.
  • Bytes transferred and received.
  • Authentication successes and failures.
  • Number of wire protocol errors.
NOTE: 🫶 an operation is considered "sent" when one or more bytes of the corresponding message is written to the stream, regardless of whether the entire message is successfully written or if the operation ultimately succeeds or fails. this does not include bytes that may be written during the stream connection process, such as TLS handshake messages. important distinction bestie, don't @ me.

to access counters for a given process, simply provide the process id to the mongoc-stat program installed with the MongoDB C Driver.

$ mongoc-stat 22203
   Operations : Egress Total        : The number of sent operations.                    : 13247
   Operations : Ingress Total       : The number of received operations.                : 13246
   Operations : Egress Queries      : The number of sent Query operations.              : 13247
   Operations : Ingress Queries     : The number of received Query operations.          : 0
   Operations : Egress GetMore      : The number of sent GetMore operations.            : 0
   Operations : Ingress GetMore     : The number of received GetMore operations.        : 0
   Operations : Egress Insert       : The number of sent Insert operations.             : 0
   Operations : Ingress Insert      : The number of received Insert operations.         : 0
   Operations : Egress Delete       : The number of sent Delete operations.             : 0
   Operations : Ingress Delete      : The number of received Delete operations.         : 0
   Operations : Egress Update       : The number of sent Update operations.             : 0
   Operations : Ingress Update      : The number of received Update operations.         : 0
   Operations : Egress KillCursors  : The number of sent KillCursors operations.        : 0
   Operations : Ingress KillCursors : The number of received KillCursors operations.    : 0
   Operations : Egress Msg          : The number of sent Msg operations.                : 0
   Operations : Ingress Msg         : The number of received Msg operations.            : 0
   Operations : Egress Reply        : The number of sent Reply operations.              : 0
   Operations : Ingress Reply       : The number of received Reply operations.          : 13246
      Cursors : Active              : The number of active cursors.                     : 1
      Cursors : Disposed            : The number of disposed cursors.                   : 13246
      Clients : Active              : The number of active clients.                     : 1
      Clients : Disposed            : The number of disposed clients.                   : 0
      Streams : Active              : The number of active streams.                     : 1
      Streams : Disposed            : The number of disposed streams.                   : 0
      Streams : Egress Bytes        : The number of bytes sent.                         : 794931
      Streams : Ingress Bytes       : The number of bytes received.                     : 589694
      Streams : N Socket Timeouts   : The number of socket timeouts.                    : 0
 Client Pools : Active              : The number of active client pools.                : 1
 Client Pools : Disposed            : The number of disposed client pools.              : 0
     Protocol : Ingress Errors      : The number of protocol errors on ingress.         : 0
         Auth : Failures            : The number of failed authentication requests.     : 0
         Auth : Success             : The number of successful authentication requests. : 0

she's beautiful, she's organized, she's got numbers for days 🔥

🌈 SUBMITTING A BUG REPORT 🌈

think you've found a bug? want to see a new feature in the MongoDB C driver? please open a case in our issue management tool, JIRA 💜

  • Create an account and login.
  • Navigate to the CDRIVER project.
  • Click Create Issue — please provide as much information as possible about the issue type and how to reproduce it. the more deets the better bestie, we wanna help you fr fr 🥺

bug reports in JIRA for all driver projects (i.e. CDRIVER, CSHARP, JAVA) and the Core Server (i.e. SERVER) project are public. so like, everyone can see them 👀 slay responsibly.

👑 AUTHOR 👑

MongoDB, Inc

2017-present, MongoDB, Inc

that's the whole page bestie, you ate it up 💖 this has been libmongoc version 1.26.0, dated Mar 31, 2024 — go forth and debug, you absolute main character 🌟 mwah 💋

📦 where this page comes from