.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MONGOC_STRUCTURED_LOG_OPTS_T" "3" "Apr 14, 2025" "1.30.3" "libmongoc"
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
typedef struct mongoc_structured_log_opts_t mongoc_structured_log_opts_t;
.EE
.UNINDENT
.UNINDENT
.sp
\fBmongoc_structured_log_opts_t\fP is an opaque type that contains options for the structured logging subsystem: per\-component log levels, a maximum logged document length, and a handler function.
.sp
Create a \fBmongoc_structured_log_opts_t\fP with \fI\%mongoc_structured_log_opts_new()\fP, set options and a callback on it, then pass it to \fI\%mongoc_client_set_structured_log_opts()\fP or \fI\%mongoc_client_pool_set_structured_log_opts()\fP\&.
Must be destroyed by calling \fI\%mongoc_structured_log_opts_destroy()\fP\&.
.SH FUNCTIONS
.SS mongoc_structured_log_opts_new()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
mongoc_structured_log_opts_t *
mongoc_structured_log_opts_new (void);
.EE
.UNINDENT
.UNINDENT
.sp
Creates a new \fI\%mongoc_structured_log_opts_t\fP, filled with defaults captured from the current environment.
.sp
Sets a default log handler which would write a text representation of each log message to \fBstderr\fP, \fBstdout\fP, or another file configurable using \fBMONGODB_LOG_PATH\fP\&.
This setting has no effect if the default handler is replaced using \fI\%mongoc_structured_log_opts_set_handler()\fP\&.
.sp
Environment variable errors are non\-fatal, and result in one\-time warnings delivered as an unstructured log.
.sp
Per\-component maximum levels are initialized equivalently to:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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);
.EE
.UNINDENT
.UNINDENT
.SS Environment Variables
.sp
This is a full list of the captured environment variables.
.INDENT 0.0
.IP \(bu 2
\fBMONGODB_LOG_MAX_DOCUMENT_LENGTH\fP: Maximum length for JSON\-serialized documents that appear within a log message.
It may be a number, in bytes, or \fBunlimited\fP (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.
.IP \(bu 2
\fBMONGODB_LOG_PATH\fP: A file path or one of the special strings \fBstderr\fP or \fBstdout\fP (case insensitive) specifying the destination for structured logs seen by the default handler.
By default, it writes to \fBstderr\fP\&.
This path will be captured during \fBmongoc_structured_log_opts_new()\fP, but it will not immediately be opened.
If the file can\(aqt be opened, a warning is then written to the unstructured log and the handler writes structured logs to \fBstderr\fP instead.
.sp
\fBWARNING:\fP
.INDENT 2.0
.INDENT 3.5
When a file path is given for \fBMONGODB_LOG_PATH\fP, 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\(aqs 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 \fBstderr\fP\&.
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.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fBMONGODB_LOG_COMMAND\fP: A log level name to set as the maximum for \fBMONGOC_STRUCTURED_LOG_COMPONENT_COMMAND\fP\&.
.IP \(bu 2
\fBMONGODB_LOG_TOPOLOGY\fP: A log level name to set as the maximum for \fBMONGOC_STRUCTURED_LOG_COMPONENT_TOPOLOGY\fP\&.
.IP \(bu 2
\fBMONGODB_LOG_SERVER_SELECTION\fP: A log level name to set as the maximum for \fBMONGOC_STRUCTURED_LOG_COMPONENT_SERVER_SELECTION\fP\&.
.IP \(bu 2
\fBMONGODB_LOG_CONNECTION\fP: A log level name to set as the maximum for \fBMONGOC_STRUCTURED_LOG_COMPONENT_CONNECTION\fP\&.
.IP \(bu 2
\fBMONGODB_LOG_ALL\fP: A log level name applied to all components not otherwise specified.
.UNINDENT
.sp
Note that log level names are always case insensitive.
This is a full list of recognized names, including allowed aliases:
.INDENT 0.0
.IP \(bu 2
\fBemergency\fP, \fBoff\fP
.IP \(bu 2
\fBalert\fP
.IP \(bu 2
\fBcritical\fP
.IP \(bu 2
\fBerror\fP
.IP \(bu 2
\fBwarning\fP, \fBwarn\fP
.IP \(bu 2
\fBnotice\fP
.IP \(bu 2
\fBinformational\fP, \fBinfo\fP
.IP \(bu 2
\fBdebug\fP
.IP \(bu 2
\fBtrace\fP
.UNINDENT
.SS Returns
.sp
A newly allocated \fI\%mongoc_structured_log_opts_t\fP\&.
.SS mongoc_structured_log_opts_destroy()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
void
mongoc_structured_log_opts_destroy (mongoc_structured_log_opts_t *opts);
.EE
.UNINDENT
.UNINDENT
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Pointer to a \fI\%mongoc_structured_log_opts_t\fP allocated with \fI\%mongoc_structured_log_opts_new()\fP, or NULL.
.UNINDENT
.SS Description
.sp
This function releases all resources associated with a \fI\%mongoc_structured_log_opts_t\fP\&.
Does nothing if \fBopts\fP is NULL.
.SS mongoc_structured_log_opts_set_handler()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
void
mongoc_structured_log_opts_set_handler (mongoc_structured_log_opts_t *opts,
                                        mongoc_structured_log_func_t log_func,
                                        void *user_data);
.EE
.UNINDENT
.UNINDENT
.sp
Sets the function to be called to handle structured log messages, as a \fI\%mongoc_structured_log_func_t\fP\&.
.sp
The callback is given a \fI\%mongoc_structured_log_entry_t\fP as a handle for obtaining additional information about the log message.
This entry pointer is only valid during a callback, because it\(aqs a low cost reference to temporary data.
.sp
Structured log handlers must be thread\-safe if they will be used with \fI\%mongoc_client_pool_t\fP\&.
Handlers must avoid unbounded recursion, preferably by avoiding the use of any \fBlibmongoc\fP client or pool which uses the same handler.
.sp
This function always replaces the default log handler from \fI\%mongoc_structured_log_opts_new()\fP, if it was still set.
If the \fBlog_func\fP is set to NULL, structured logging will be disabled.
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Structured log options, allocated with \fI\%mongoc_structured_log_opts_new()\fP\&.
.IP \(bu 2
\fBlog_func\fP: The handler to install, a \fI\%mongoc_structured_log_func_t\fP, or NULL to disable structured logging.
.IP \(bu 2
\fBuser_data\fP: Optional user data, passed on to the handler.
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_set_max_level_for_component()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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);
.EE
.UNINDENT
.UNINDENT
.sp
Sets the maximum log level per\-component.
Only log messages at or below this severity level will be passed to \fI\%mongoc_structured_log_func_t\fP\&.
.sp
By default, each component\(aqs log level may come from environment variables.
See \fI\%mongoc_structured_log_opts_set_max_levels_from_env()\fP\&.
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Structured log options, allocated with \fI\%mongoc_structured_log_opts_new()\fP\&.
.IP \(bu 2
\fBcomponent\fP: The component to set a max log level. for, as a \fI\%mongoc_structured_log_component_t\fP\&.
.IP \(bu 2
\fBlevel\fP: The new max log level for this component, as a \fI\%mongoc_structured_log_level_t\fP\&.
.UNINDENT
.SS Returns
.sp
Returns \fBtrue\fP on success, or \fBfalse\fP if the supplied parameters were incorrect.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_set_max_level_for_all_components()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
mongoc_structured_log_opts_set_max_level_for_all_components (mongoc_structured_log_opts_t *opts,
                                                             mongoc_structured_log_level_t level);
.EE
.UNINDENT
.UNINDENT
.sp
Sets all per\-component maximum log levels to the same value.
Only log messages at or below this severity level will be passed to \fI\%mongoc_structured_log_func_t\fP\&.
Effective even for logging components not known at compile\-time.
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Structured log options, allocated with \fI\%mongoc_structured_log_opts_new()\fP\&.
.IP \(bu 2
\fBlevel\fP: The max log level for all components, as a \fI\%mongoc_structured_log_level_t\fP\&.
.UNINDENT
.SS Returns
.sp
Returns \fBtrue\fP on success, or \fBfalse\fP if the supplied parameters were incorrect.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_set_max_levels_from_env()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
mongoc_structured_log_opts_set_max_levels_from_env (mongoc_structured_log_opts_t *opts);
.EE
.UNINDENT
.UNINDENT
.sp
Sets any maximum log levels requested by environment variables: \fBMONGODB_LOG_ALL\fP for all components, followed by per\-component log levels \fBMONGODB_LOG_COMMAND\fP, \fBMONGODB_LOG_CONNECTION\fP, \fBMONGODB_LOG_TOPOLOGY\fP, and \fBMONGODB_LOG_SERVER_SELECTION\fP\&.
.sp
Expects the value to be recognizable by \fI\%mongoc_structured_log_get_named_level()\fP\&.
Parse errors may cause a warning message, delivered via unstructured logging.
.sp
Component levels with no valid environment variable setting will be left unmodified.
.sp
This happens automatically when \fI\%mongoc_structured_log_opts_new()\fP establishes defaults.
Any subsequent programmatic modifications to the \fI\%mongoc_structured_log_opts_t\fP will override the environment variable settings.
For applications that desire the opposite behavior, where environment variables may override programmatic settings, they may call \fBmongoc_structured_log_opts_set_max_levels_from_env()\fP after calling \fI\%mongoc_structured_log_opts_set_max_level_for_component()\fP and \fI\%mongoc_structured_log_opts_set_max_level_for_all_components()\fP\&.
This will process the environment a second time, allowing it to override customized defaults.
.SS Returns
.sp
Returns \fBtrue\fP on success.
If warnings are encountered in the environment, returns \fBfalse\fP and may log additional information to the unstructured logging facility.
Note that, by design, these errors are by default non\-fatal.
When \fI\%mongoc_structured_log_opts_new()\fP internally calls this function, it ignores the return value.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_get_max_level_for_component()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
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);
.EE
.UNINDENT
.UNINDENT
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Structured log options, allocated with \fI\%mongoc_structured_log_opts_new()\fP\&.
.IP \(bu 2
\fBcomponent\fP: Log component as a \fI\%mongoc_structured_log_component_t\fP\&.
.UNINDENT
.SS Returns
.sp
Returns the configured maximum log level for a specific component, as a \fI\%mongoc_structured_log_level_t\fP\&.
This may be the last value set with \fI\%mongoc_structured_log_opts_set_max_level_for_component()\fP or \fI\%mongoc_structured_log_opts_set_max_level_for_all_components()\fP, or it may be the default obtained from environment variables.
If an invalid or unknown component enum is given, returns the lowest log level.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_set_max_document_length()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
mongoc_structured_log_opts_set_max_document_length (mongoc_structured_log_opts_t *opts,
                                                    size_t max_document_length);
.EE
.UNINDENT
.UNINDENT
.sp
Sets a maximum length for BSON documents that appear serialized in JSON form as part of a structured log message.
.sp
Serialized JSON will be truncated at this limit, interpreted as a count of UTF\-8 encoded bytes. Truncation will be indicated with a \fB\&...\fP suffix, the length of which is not included in the max document length. If truncation 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.
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Structured log options, allocated with \fI\%mongoc_structured_log_opts_new()\fP\&.
.IP \(bu 2
\fBmax_document_length\fP: Maximum length for each embedded JSON document, in bytes, not including an ellipsis (\fB\&...\fP) added to indicate truncation. Values near or above \fBINT_MAX\fP will be rejected.
.UNINDENT
.SS Returns
.sp
Returns \fBtrue\fP on success, or \fBfalse\fP if the supplied maximum length is too large.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
\fI\%mongoc_structured_log_opts_set_max_document_length_from_env()\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_set_max_document_length_from_env()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
mongoc_structured_log_opts_set_max_document_length_from_env (mongoc_structured_log_opts_t *opts);
.EE
.UNINDENT
.UNINDENT
.sp
Sets a maximum document length from the \fBMONGODB_LOG_MAX_DOCUMENT_LENGTH\fP environment variable, if a valid setting is found.
See \fI\%mongoc_structured_log_opts_new()\fP for a description of the supported environment variable formats.
.sp
Parse errors may cause a warning message, delivered via unstructured logging.
.sp
This happens automatically when \fI\%mongoc_structured_log_opts_new()\fP establishes defaults.
Any subsequent programmatic modifications to the \fI\%mongoc_structured_log_opts_t\fP will override the environment variable settings.
For applications that desire the opposite behavior, where environment variables may override programmatic settings, they may call \fBmongoc_structured_log_opts_set_max_document_length_from_env()\fP after calling \fI\%mongoc_structured_log_opts_set_max_document_length()\fP\&.
This will process the environment a second time, allowing it to override customized defaults.
.SS Returns
.sp
Returns \fBtrue\fP on success: either a valid environment setting was found, or the value is unset and \fBopts\fP will not be modified.
If warnings are encountered in the environment, returns \fBfalse\fP and may log additional information to the unstructured logging facility.
Note that, by design, these errors are by default non\-fatal.
When \fI\%mongoc_structured_log_opts_new()\fP internally calls this function, it ignores the return value.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SS mongoc_structured_log_opts_get_max_document_length()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.EX
size_t
mongoc_structured_log_opts_get_max_document_length (const mongoc_structured_log_opts_t *opts);
.EE
.UNINDENT
.UNINDENT
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBopts\fP: Structured log options, allocated with \fI\%mongoc_structured_log_opts_new()\fP\&.
.UNINDENT
.SS Returns
.sp
Returns the current maximum document length set in \fBopts\fP, as a \fBsize_t\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.nf
\fI\%Structured Logging\fP
.fi
.sp
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2009-present, MongoDB, Inc.
.\" Generated by docutils manpage writer.
.