MONGOC_STRUCTURED_LOG_OPTS_T(3)

📦
version 2.5.6 · 13 versions
, in epel 10

okay bestie, welcome to the libmongoc page for MONGOC_STRUCTURED_LOG_OPTS_T(3) — this is lowkey the blueprint for the whole structured-logging vibe, so grab a lil snack and stay with me 🍓

🌸 SYNOPSIS 🌸

typedef struct mongoc_structured_log_opts_t mongoc_structured_log_opts_t;

mongoc_structured_log_opts_t is an opaque type, meaning no peeking at its guts, bestie — it contains options for the structured logging subsystem: per-component log levels, a maximum logged document length, and a handler function. It's giving “trust the process” energy ✨

Here's the workflow: create a mongoc_structured_log_opts_t with mongoc_structured_log_opts_new(), set options and a callback on it, then pass it to mongoc_client_set_structured_log_opts() or mongoc_client_pool_set_structured_log_opts(). It must be destroyed by calling mongoc_structured_log_opts_destroy(). Periodt 💅

✨ FUNCTIONS ✨

💖 mongoc_structured_log_opts_new() 💖

📝 Synopsis

mongoc_structured_log_opts_t *
mongoc_structured_log_opts_new (void);

Creates a new mongoc_structured_log_opts_t, filled with defaults captured from the current environment. So it's literally reading the room — and the env — on creation 🫶

Sets a default log handler that writes a text representation of each log message to stderr, stdout, or another file configurable using MONGODB_LOG_PATH. This setting has no effect if the default handler is replaced using mongoc_structured_log_opts_set_handler().

Environment variable errors are non-fatal, and result in one-time warnings delivered as an unstructured log. Not the drama we wanted, but it's handled 💀

Per-component maximum levels are initialized equivalently to:

mongoc_structured_log_opts_set_max_level_for_all_components(opts, MONGOC_STRUCTURED_LOG_LEVEL_WARNING);
mongoc_structured_log_opts_set_max_levels_from_env(opts);

🌍 Environment Variables

This is a full list of the captured environment variables. No crumbs left behind 🔥

  • MONGODB_LOG_MAX_DOCUMENT_LENGTH — Maximum length for JSON-serialized documents that appear within a log message. It may be a number, in bytes, or unlimited (case insensitive) to choose an implementation-specific value near the maximum representable length. By default, the limit is 1000 bytes. This limit affects interior documents like commands and replies, not the total length of a structured log message.
  • MONGODB_LOG_PATH — A file path or one of the special strings stderr or stdout (case insensitive) specifying the destination for structured logs seen by the default handler. By default, it writes to stderr. This path will be captured during mongoc_structured_log_opts_new(), but it will not immediately be opened. If the file can't be opened, a warning is then written to the unstructured log and the handler writes structured logs to stderr instead.
⚠️ WARNING: When a file path is given for MONGODB_LOG_PATH, each log instance (one stand-alone client or pool) will separately open this file for append. The results are operating system specific. On UNIX-like platforms each instance's output will be interleaved, in most cases without splitting individual log messages. Notably on Windows the file will be opened in exclusive mode by the first instance and subsequent instances will fail, falling back on the default of stderr. Applications that use multiple processes or multiple client pools will likely want to supply a log handler that annotates each message with information about its originating log instance.
  • MONGODB_LOG_COMMAND — A log level name to set as the maximum for MONGOC_STRUCTURED_LOG_COMPONENT_COMMAND.
  • MONGODB_LOG_TOPOLOGY — A log level name to set as the maximum for MONGOC_STRUCTURED_LOG_COMPONENT_TOPOLOGY.
  • MONGODB_LOG_SERVER_SELECTION — A log level name to set as the maximum for MONGOC_STRUCTURED_LOG_COMPONENT_SERVER_SELECTION.
  • MONGODB_LOG_CONNECTION — A log level name to set as the maximum for MONGOC_STRUCTURED_LOG_COMPONENT_CONNECTION.
  • MONGODB_LOG_ALL — A log level name applied to all components not otherwise specified.

Note that log level names are always case insensitive. This is a full list of recognized names, including allowed aliases:

  • emergency, off
  • alert
  • critical
  • error
  • warning, warn
  • notice
  • informational, info
  • debug
  • trace

🎁 Returns

A newly allocated mongoc_structured_log_opts_t. Iconic behavior, no notes 👑

🫶 mongoc_structured_log_opts_destroy() 🫶

📝 Synopsis

void
mongoc_structured_log_opts_destroy (mongoc_structured_log_opts_t *opts);

📦 Parameters

  • opts: Pointer to a mongoc_structured_log_opts_t allocated with mongoc_structured_log_opts_new(), or NULL.

🌿 Description

This function releases all resources associated with a mongoc_structured_log_opts_t. Does nothing if opts is NULL. Chill cleanup vibes only 🧹✨

🦋 mongoc_structured_log_opts_set_handler() 🦋

📝 Synopsis

void
mongoc_structured_log_opts_set_handler (mongoc_structured_log_opts_t *opts,
                                        mongoc_structured_log_func_t log_func,
                                        void *user_data);

Sets the function to be called to handle structured log messages, as a mongoc_structured_log_func_t.

The callback is given a mongoc_structured_log_entry_t as a handle for obtaining additional information about the log message. This entry pointer is only valid during a callback, because it's a low cost reference to temporary data. Basically: use it while you're in the callback, don't get attached 😭

Structured log handlers must be thread-safe if they will be used with mongoc_client_pool_t. Handlers must avoid unbounded recursion, preferably by avoiding the use of any libmongoc client or pool which uses the same handler. Fr fr, do not create a lil log-handler ouroboros 🙈

This function always replaces the default log handler from mongoc_structured_log_opts_new(), if it was still set. If the log_func is set to NULL, structured logging will be disabled.

📦 Parameters

  • opts: Structured log options, allocated with mongoc_structured_log_opts_new().
  • log_func: The handler to install, a mongoc_structured_log_func_t, or NULL to disable structured logging.
  • user_data: Optional user data, passed on to the handler.

SEE ALSO: Structured Logging

🌈 mongoc_structured_log_opts_set_max_level_for_component() 🌈

📝 Synopsis

bool
mongoc_structured_log_opts_set_max_level_for_component (mongoc_structured_log_opts_t *opts,
                                                        mongoc_structured_log_component_t component,
                                                        mongoc_structured_log_level_t level);

Sets the maximum log level per-component. Only log messages at or below this severity level will be passed to mongoc_structured_log_func_t. It's giving gatekeeping, but make it logging 💅

By default, each component's log level may come from environment variables. See mongoc_structured_log_opts_set_max_levels_from_env().

📦 Parameters

  • opts: Structured log options, allocated with mongoc_structured_log_opts_new().
  • component: The component to set a max log level for, as a mongoc_structured_log_component_t.
  • level: The new max log level for this component, as a mongoc_structured_log_level_t.

🎁 Returns

Returns true on success, or false if the supplied parameters were incorrect.

SEE ALSO: Structured Logging

👑 mongoc_structured_log_opts_set_max_level_for_all_components() 👑

📝 Synopsis

bool
mongoc_structured_log_opts_set_max_level_for_all_components (mongoc_structured_log_opts_t *opts,
                                                             mongoc_structured_log_level_t level);

Sets all per-component maximum log levels to the same value. Only log messages at or below this severity level will be passed to mongoc_structured_log_func_t. Effective even for logging components not known at compile-time. Future components? They're covered too, bestie ✨

📦 Parameters

  • opts: Structured log options, allocated with mongoc_structured_log_opts_new().
  • level: The max log level for all components, as a mongoc_structured_log_level_t.

🎁 Returns

Returns true on success, or false if the supplied parameters were incorrect.

SEE ALSO: Structured Logging

🧚 mongoc_structured_log_opts_set_max_levels_from_env() 🧚

📝 Synopsis

bool
mongoc_structured_log_opts_set_max_levels_from_env (mongoc_structured_log_opts_t *opts);

Sets any maximum log levels requested by environment variables: MONGODB_LOG_ALL for all components, followed by per-component log levels MONGODB_LOG_COMMAND, MONGODB_LOG_CONNECTION, MONGODB_LOG_TOPOLOGY, and MONGODB_LOG_SERVER_SELECTION.

Expects the value to be recognizable by mongoc_structured_log_get_named_level(). Parse errors may cause a warning message, delivered via unstructured logging. Not a fatal situation, just a lil “hmm” in the logs 💀

Component levels with no valid environment variable setting will be left unmodified.

This happens automatically when mongoc_structured_log_opts_new() establishes defaults. Any subsequent programmatic modifications to the mongoc_structured_log_opts_t will override the environment variable settings. For applications that desire the opposite behavior, where environment variables may override programmatic settings, they may call mongoc_structured_log_opts_set_max_levels_from_env() after calling mongoc_structured_log_opts_set_max_level_for_component() and mongoc_structured_log_opts_set_max_level_for_all_components(). This will process the environment a second time, allowing it to override customized defaults. Env said “actually, hold on,” and honestly? Slay 🌸

🎁 Returns

Returns true on success. If warnings are encountered in the environment, returns false and may log additional information to the unstructured logging facility. Note that, by design, these errors are by default non-fatal. When mongoc_structured_log_opts_new() internally calls this function, it ignores the return value.

SEE ALSO: Structured Logging

🎀 mongoc_structured_log_opts_get_max_level_for_component() 🎀

📝 Synopsis

mongoc_structured_log_level_t
mongoc_structured_log_opts_get_max_level_for_component (const mongoc_structured_log_opts_t *opts,
                                                        mongoc_structured_log_component_t component);

📦 Parameters

  • opts: Structured log options, allocated with mongoc_structured_log_opts_new().
  • component: Log component as a mongoc_structured_log_component_t.

🎁 Returns

Returns the configured maximum log level for a specific component, as a mongoc_structured_log_level_t. This may be the last value set with mongoc_structured_log_opts_set_max_level_for_component() or mongoc_structured_log_opts_set_max_level_for_all_components(), or it may be the default obtained from environment variables. If an invalid or unknown component enum is given, returns the lowest log level. We love a graceful fallback 🫶

SEE ALSO: Structured Logging

💜 mongoc_structured_log_opts_set_max_document_length() 💜

📝 Synopsis

bool
mongoc_structured_log_opts_set_max_document_length (mongoc_structured_log_opts_t *opts,
                                                    size_t max_document_length);

Sets a maximum length for BSON documents that appear serialized in JSON form as part of a structured log message.

Serialized JSON gets yeeted at the limit, bestie — the limit is read as a count of UTF-8 encoded bytes. Truncation is flagged with a ... suffix, and the length of that suffix is not included in the max document length. And here's the ✨ careful ✨ part: if truncating at the exact indicated length would split a valid UTF-8 sequence, we instead truncate the document earlier, at the nearest boundary between code points. No broken characters, periodt. 🫶

Parameters

  • opts — structured log options, allocated with mongoc_structured_log_opts_new().
  • max_document_length — the maximum length for each embedded JSON document, in bytes, not including the ellipsis (...) added to indicate truncation. Values near or above INT_MAX will be rejected. 🚫

Returns

Returns true on success, or false if the supplied maximum length is too large. Simple as that, ngl.

SEE ALSO

  • Structured Logging
  • mongoc_structured_log_opts_set_max_document_length_from_env()

🦋 mongoc_structured_log_opts_set_max_document_length_from_env()

Synopsis

bool
mongoc_structured_log_opts_set_max_document_length_from_env (mongoc_structured_log_opts_t *opts);

Sets a maximum document length from the MONGODB_LOG_MAX_DOCUMENT_LENGTH environment variable, if a valid setting is found. 💖 For a description of the supported environment variable formats, go peek at mongoc_structured_log_opts_new() — it's all laid out there.

Parse errors may cause a warning message, delivered via unstructured logging. So like, it'll tell you, just not in the structured way. 🙈

This happens automatically when mongoc_structured_log_opts_new() establishes defaults. Any subsequent programmatic modifications to the mongoc_structured_log_opts_t will override the environment variable settings. So env sets the vibe, code has the final say. 👑

But for applications that desire the opposite behavior — where environment variables may override programmatic settings — they may call mongoc_structured_log_opts_set_max_document_length_from_env() after calling mongoc_structured_log_opts_set_max_document_length(). This will process the environment a second time, allowing it to override customized defaults. Round two, env wins. 🔥

Returns

Returns true on success: either a valid environment setting was found, or the value is unset and opts will not be modified. If warnings are encountered in the environment, returns false and may log additional information to the unstructured logging facility. And note — by design, these errors are by default non-fatal. 💀 So don't panic. When mongoc_structured_log_opts_new() internally calls this function, it ignores the return value. Like, fully ignores it. Rude but true.

SEE ALSO

  • Structured Logging

🌸 mongoc_structured_log_opts_get_max_document_length()

Synopsis

size_t
mongoc_structured_log_opts_get_max_document_length (const mongoc_structured_log_opts_t *opts);

Parameters

  • opts — structured log options, allocated with mongoc_structured_log_opts_new().

Returns

Returns the current maximum document length set in opts, as a size_t. That's it, that's the whole function. 🎀

SEE ALSO

  • Structured Logging

SEE ALSO

  • Structured Logging
Yes, Structured Logging is listed twice in the original. Not a typo on my end, bestie — I'm just keeping it exactly as it is. Iconic honestly. 💅

👑 AUTHOR

MongoDB, Inc

2009-present, MongoDB, Inc.

And that's a wrap on this page, babes! 🎉 This was MONGOC_STRUCTURED_LOG_OPTS_T(3), version 2.5.6, dated Oct 09, 2026 — go forth and log structuredly, you gorgeous main character. 🌈✨💜

📦 where this page comes from