FreeBSD Manual Pages
MONGOC_LOGGING(3) libmongoc MONGOC_LOGGING(3)
The MongoDB C driver has two different types of logging available:
• The original mongoc_log facility supports freeform string messages
that originate from the driver itself or from application code. This
has been retroactively termed "unstructured logging".
• A new mongoc_structured_log facility reports messages from the driver
itself using a BSON format defined across driver implementations by
the MongoDB Logging Specification.
These two systems are configured and used independently.
UNSTRUCTURED LOGGING
This is the original logging facility that supports freeform string
messages originating from the driver itself or from application code.
This has been retroactively termed "unstructured logging". See
Structured Logging for the newer standardized logging facility.
typedef enum {
MONGOC_LOG_LEVEL_ERROR,
MONGOC_LOG_LEVEL_CRITICAL,
MONGOC_LOG_LEVEL_WARNING,
MONGOC_LOG_LEVEL_MESSAGE,
MONGOC_LOG_LEVEL_INFO,
MONGOC_LOG_LEVEL_DEBUG,
MONGOC_LOG_LEVEL_TRACE,
} mongoc_log_level_t;
#define MONGOC_ERROR(...)
#define MONGOC_CRITICAL(...)
#define MONGOC_WARNING(...)
#define MONGOC_MESSAGE(...)
#define MONGOC_INFO(...)
#define MONGOC_DEBUG(...)
typedef void (*mongoc_log_func_t) (mongoc_log_level_t log_level,
const char *log_domain,
const char *message,
void *user_data);
void
mongoc_log_set_handler (mongoc_log_func_t log_func, void *user_data);
void
mongoc_log (mongoc_log_level_t log_level,
const char *log_domain,
const char *format,
...);
const char *
mongoc_log_level_str (mongoc_log_level_t log_level);
void
mongoc_log_default_handler (mongoc_log_level_t log_level,
const char *log_domain,
const char *message,
void *user_data);
void
mongoc_log_trace_enable (void);
void
mongoc_log_trace_disable (void);
This abstraction can be used for logging in your application, or you
can integrate the driver with an existing logging system.
Macros
To make logging a little less painful, various helper macros are pro-
vided. See the following example.
#undef MONGOC_LOG_DOMAIN
#define MONGOC_LOG_DOMAIN "my-custom-domain"
MONGOC_WARNING ("An error occurred: %s", strerror (errno));
Custom Log Handlers
The default log handler prints a timestamp and the log message to std-
out, or to stderr for warnings, critical messages, and errors. You can
override the handler with mongoc_log_set_handler(). Your handler func-
tion is called in a mutex for thread safety.
For example, you could register a custom handler to suppress messages
at INFO level and below:
void
my_logger (mongoc_log_level_t log_level,
const char *log_domain,
const char *message,
void *user_data)
{
/* smaller values are more important */
if (log_level < MONGOC_LOG_LEVEL_INFO) {
mongoc_log_default_handler (log_level, log_domain, message, user_data);
}
}
int
main (int argc, char *argv[])
{
mongoc_log_set_handler (my_logger, NULL);
mongoc_init ();
/* ... your code ... */
mongoc_cleanup ();
return 0;
}
Note that in the example above mongoc_log_set_handler() is called be-
fore mongoc_init(). Otherwise, some log traces could not be processed
by the log handler.
To restore the default handler:
mongoc_log_set_handler (mongoc_log_default_handler, NULL);
Disable logging
To disable all logging, including warnings, critical messages and er-
rors, provide an empty log handler:
mongoc_log_set_handler (NULL, NULL);
Tracing
If compiling your own copy of the MongoDB C driver, consider configur-
ing with -DENABLE_TRACING=ON to enable function tracing and hex dumps
of network packets to STDERR and STDOUT during development and debug-
ging.
This is especially useful when debugging what may be going on inter-
nally in the driver.
Trace messages can be enabled and disabled by calling mon-
goc_log_trace_enable() and mongoc_log_trace_disable()
NOTE:
Compiling the driver with -DENABLE_TRACING=ON will affect its per-
formance. Disabling tracing with mongoc_log_trace_disable() signifi-
cantly reduces the overhead, but cannot remove it completely.
STRUCTURED LOGGING
This document describes a newer "structured" logging facility which re-
ports messages from the driver itself using a BSON format defined
across driver implementations by the MongoDB Logging Specification.
See Unstructured Logging for the original freeform logging facility.
These two systems are configured and used independently.
Unstructured logging is global to the entire process, but structured
logging is configured separately for each mongoc_client_t or
mongoc_client_pool_t. See mongoc_client_set_structured_log_opts() and
mongoc_client_pool_set_structured_log_opts().
Options
Structured log settings are tracked explicitly by a
mongoc_structured_log_opts_t instance.
Like other drivers supporting structured logging, we take default set-
tings from environment variables and offer additional optional program-
matic configuration. Environment variables are captured during
mongoc_structured_log_opts_new(), refer there for a full list of the
supported variables.
Normally environment variables provide defaults that can be overridden
programmatically. To request the opposite behavior, where your pro-
grammatic defaults can be overridden by the environment, see
mongoc_structured_log_opts_set_max_levels_from_env().
Structured log messages may be filtered in arbitrary ways by the han-
dler, but as both a performance optimization and a convenience, a
built-in filter limits the maximum log level of reported messages with
a per-component setting.
mongoc_structured_log_opts_t
Synopsis
typedef struct mongoc_structured_log_opts_t mongoc_structured_log_opts_t;
mongoc_structured_log_opts_t is an opaque type that contains options
for the structured logging subsystem: per-component log levels, a maxi-
mum logged document length, and a handler function.
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(). Must be destroyed by
calling mongoc_structured_log_opts_destroy().
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 cap-
tured from the current environment.
Sets a default log handler which would write 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 warn-
ings delivered as an unstructured log.
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.
• 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 implementa-
tion-specific value near the maximum representable length. By de-
fault, the limit is 1000 bytes. This limit affects interior docu-
ments 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 in-
stance and subsequent instances will fail, falling back on the de-
fault of stderr. Applications that use multiple processes or mul-
tiple 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 MON-
GOC_STRUCTURED_LOG_COMPONENT_COMMAND.
• MONGODB_LOG_TOPOLOGY: A log level name to set as the maximum for MON-
GOC_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 oth-
erwise 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.
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.
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 refer-
ence to temporary data.
Structured log handlers must be thread-safe if they will be used with
mongoc_client_pool_t. Handlers must avoid unbounded recursion, prefer-
ably by avoiding the use of any libmongoc client or pool which uses the
same handler.
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 be-
low this severity level will be passed to mongoc_structured_log_func_t.
By default, each component's log level may come from environment vari-
ables. 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 in-
correct.
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.
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 in-
correct.
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: MON-
GODB_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.
Component levels with no valid environment variable setting will be
left unmodified.
This happens automatically when mongoc_structured_log_opts_new() estab-
lishes 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.
Returns
Returns true on success. If warnings are encountered in the environ-
ment, returns false and may log additional information to the unstruc-
tured logging facility. Note that, by design, these errors are by de-
fault 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.
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 will be truncated at this limit, interpreted as a count
of UTF-8 encoded bytes. Truncation will be indicated with a ... 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 se-
quence, we instead truncate the document earlier at the nearest bound-
ary between code points.
Parameters
• opts: Structured log options, allocated with
mongoc_structured_log_opts_new().
• max_document_length: Maximum length for each embedded JSON document,
in bytes, not including an ellipsis (...) added to indicate trunca-
tion. Values near or above INT_MAX will be rejected.
Returns
Returns true on success, or false if the supplied maximum length is too
large.
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. See
mongoc_structured_log_opts_new() for a description of the supported en-
vironment variable formats.
Parse errors may cause a warning message, delivered via unstructured
logging.
This happens automatically when mongoc_structured_log_opts_new() estab-
lishes 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_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.
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. Note that, by de-
sign, these errors are by default non-fatal. When
mongoc_structured_log_opts_new() internally calls this function, it ig-
nores the return value.
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.
SEE ALSO:
Structured Logging
SEE ALSO:
Structured Logging
Levels and Components
Log levels and components are defined as mongoc_structured_log_level_t
and mongoc_structured_log_component_t enumerations. Utilities are pro-
vided to convert between these values and their standard string repre-
sentations. The string values are case-insensitive.
typedef enum {
MONGOC_STRUCTURED_LOG_LEVEL_EMERGENCY = 0, // "Emergency" ("off" also accepted)
MONGOC_STRUCTURED_LOG_LEVEL_ALERT = 1, // "Alert"
MONGOC_STRUCTURED_LOG_LEVEL_CRITICAL = 2, // "Critical"
MONGOC_STRUCTURED_LOG_LEVEL_ERROR = 3, // "Error"
MONGOC_STRUCTURED_LOG_LEVEL_WARNING = 4, // "Warning" ("warn" also accepted)
MONGOC_STRUCTURED_LOG_LEVEL_NOTICE = 5, // "Notice"
MONGOC_STRUCTURED_LOG_LEVEL_INFO = 6, // "Informational" ("info" also accepted)
MONGOC_STRUCTURED_LOG_LEVEL_DEBUG = 7, // "Debug"
MONGOC_STRUCTURED_LOG_LEVEL_TRACE = 8, // "Trace"
} mongoc_structured_log_level_t;
typedef enum {
MONGOC_STRUCTURED_LOG_COMPONENT_COMMAND = 0, // "command"
MONGOC_STRUCTURED_LOG_COMPONENT_TOPOLOGY = 1, // "topology"
MONGOC_STRUCTURED_LOG_COMPONENT_SERVER_SELECTION = 2, // "serverSelection"
MONGOC_STRUCTURED_LOG_COMPONENT_CONNECTION = 3, // "connection"
} mongoc_structured_log_component_t;
mongoc_structured_log_level_t
Synopsis
typedef enum {
MONGOC_STRUCTURED_LOG_LEVEL_EMERGENCY = 0,
MONGOC_STRUCTURED_LOG_LEVEL_ALERT = 1,
MONGOC_STRUCTURED_LOG_LEVEL_CRITICAL = 2,
MONGOC_STRUCTURED_LOG_LEVEL_ERROR = 3,
MONGOC_STRUCTURED_LOG_LEVEL_WARNING = 4,
MONGOC_STRUCTURED_LOG_LEVEL_NOTICE = 5,
MONGOC_STRUCTURED_LOG_LEVEL_INFO = 6,
MONGOC_STRUCTURED_LOG_LEVEL_DEBUG = 7,
MONGOC_STRUCTURED_LOG_LEVEL_TRACE = 8,
} mongoc_structured_log_level_t;
mongoc_structured_log_level_t enumerates the available log levels for
use with structured logging.
Functions
mongoc_structured_log_get_level_name()
Synopsis
const char *
mongoc_structured_log_get_level_name (mongoc_structured_log_level_t level);
Parameters
• level: Log level as a mongoc_structured_log_level_t.
Returns
If the level is known, returns a pointer to a constant string that
should not be freed. If the level has no known name, returns NULL.
SEE ALSO:
Structured Logging
mongoc_structured_log_get_named_level()
Synopsis
bool
mongoc_structured_log_get_named_level (const char *name, mongoc_structured_log_level_t *out);
Look up a log level by name. Case insensitive.
Parameters
• name: A name to look up as a log level.
• out: On success, the corresponding mongoc_structured_log_level_t is
written here.
Returns
If the level name is known, returns true and writes the level enum to
*out. If the level name is not known, returns false and does not write
*out.
SEE ALSO:
Structured Logging
SEE ALSO:
Structured Logging
mongoc_structured_log_component_t
Synopsis
typedef enum {
MONGOC_STRUCTURED_LOG_COMPONENT_COMMAND = 0,
MONGOC_STRUCTURED_LOG_COMPONENT_TOPOLOGY = 1,
MONGOC_STRUCTURED_LOG_COMPONENT_SERVER_SELECTION = 2,
MONGOC_STRUCTURED_LOG_COMPONENT_CONNECTION = 3,
} mongoc_structured_log_component_t;
mongoc_structured_log_component_t enumerates the structured logging
components. Applications should never rely on having an exhaustive
list of all log components. Instead, use
mongoc_structured_log_opts_set_max_level_for_all_components() to set a
default level if needed.
Functions
mongoc_structured_log_get_component_name()
Synopsis
const char *
mongoc_structured_log_get_component_name (mongoc_structured_log_component_t component);
Parameters
• component: Log component as a mongoc_structured_log_component_t.
Returns
If the component is known, returns a pointer to a constant string that
should not be freed. If the component has no known name, returns NULL.
SEE ALSO:
Structured Logging
mongoc_structured_log_get_named_component()
Synopsis
bool
mongoc_structured_log_get_named_component (const char *name, mongoc_structured_log_component_t *out);
Look up a component by name. Case insensitive.
Parameters
• name: A name to look up as a log component.
• out: On success, the corresponding mongoc_structured_log_component_t
is written here.
Returns
If the component name is known, returns true and writes the component
enum to *out. If the component name is not known, returns false and
does not write *out.
SEE ALSO:
Structured Logging
SEE ALSO:
Structured Logging
SEE ALSO:
mongoc_structured_log_get_level_name mongoc_struc-
tured_log_get_named_level mongoc_structured_log_get_component_name
mongoc_structured_log_get_named_component
Log Handlers
Each mongoc_client_pool_t or standalone mongoc_client_t has its own in-
stance of the structured logging subsystem, with its own settings and
handler.
When using mongoc_client_pool_t, the pooled clients all share a common
logging instance. Handlers must be thread-safe.
The handler is called for each log entry with a level no greater than
its component's maximum. A mongoc_structured_log_entry_t pointer pro-
vides access to further details, during the handler only.
Handlers must take care not to re-enter libmongoc with the same
mongoc_client_t or mongoc_client_pool_t that the handler has been
called by.
mongoc_structured_log_func_t
Synopsis
typedef void (*mongoc_structured_log_func_t)
(const mongoc_structured_log_entry_t *entry, void *user_data);
Callback function for mongoc_structured_log_opts_set_handler(). Struc-
tured log handlers must be thread-safe if they will be used with
mongoc_client_pool_t. Handlers must avoid unbounded recursion, prefer-
ably by avoiding the use of any libmongoc client or pool which uses the
same handler.
Parameters
• entry: A mongoc_structured_log_entry_t pointer, only valid during the
handler invocation.
• user_data: Optional user data from
mongoc_structured_log_opts_set_handler().
SEE ALSO:
Structured Logging
Log Entries
Each log entry is represented within the handler by a short-lived
mongoc_structured_log_entry_t pointer. During the handler, this
pointer can be used to access the individual properties of an entry:
its level, component, and message.
The message will be assembled as a bson_t only when explicitly re-
quested by a call to mongoc_structured_log_entry_message_as_bson().
This results in a standalone document that may be retained for any
amount of time and must be explicitly destroyed.
mongoc_structured_log_entry_t
Synopsis
typedef struct mongoc_structured_log_entry_t mongoc_structured_log_entry_t;
mongoc_structured_log_entry_t is an opaque structure which represents
the temporary state of an in-progress log entry. It can only be used
during a mongoc_structured_log_func_t, it is not valid after the log
handler returns. Use the functions below to query individual aspects
of the log entry.
Functions
mongoc_structured_log_entry_get_component()
Synopsis
mongoc_structured_log_component_t
mongoc_structured_log_entry_get_component (const mongoc_structured_log_entry_t *entry);
Parameters
• entry: A mongoc_structured_log_entry_t pointer.
Returns
The mongoc_structured_log_component_t associated with this log entry.
SEE ALSO:
Structured Logging
mongoc_structured_log_entry_get_level()
Synopsis
mongoc_structured_log_level_t
mongoc_structured_log_entry_get_level (const mongoc_structured_log_entry_t *entry);
Parameters
• entry: A mongoc_structured_log_entry_t pointer.
Returns
The mongoc_structured_log_level_t associated with this log entry.
SEE ALSO:
Structured Logging
mongoc_structured_log_entry_get_message_string()
Synopsis
const char *
mongoc_structured_log_entry_get_message_string (const mongoc_structured_log_entry_t *entry);
Parameters
• entry: A mongoc_structured_log_entry_t pointer.
Returns
A string, guaranteed to be valid only during the lifetime of the struc-
tured log handler. It should not be freed or modified.
Identical to the value of the message key in the document returned by
mongoc_structured_log_entry_message_as_bson().
This is not a complete string representation of the structured log, but
rather a standardized identifier for a particular log event.
SEE ALSO:
Structured Logging
mongoc_structured_log_entry_message_as_bson()
Synopsis
bson_t *
mongoc_structured_log_entry_message_as_bson (const mongoc_structured_log_entry_t *entry);
Make a new copy, as a bson_t, of the log entry's standardized BSON rep-
resentation. When possible, a log handler should avoid serializing log
messages that will be discarded. Each call allocates an independent
copy of the message that must be freed.
Parameters
• entry: A mongoc_structured_log_entry_t pointer.
Returns
A new allocated bson_t that must be freed with a call to
bson_destroy().
SEE ALSO:
Structured Logging
SEE ALSO:
Structured Logging
Example
example-structured-log.c
/* gcc example-structured-log.c -o example-structured-log \
* $(pkg-config --cflags --libs libmongoc-1.0) */
#include <mongoc/mongoc.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
static pthread_mutex_t handler_mutex;
static void
example_handler (const mongoc_structured_log_entry_t *entry, void *user_data)
{
mongoc_structured_log_component_t component = mongoc_structured_log_entry_get_component (entry);
mongoc_structured_log_level_t level = mongoc_structured_log_entry_get_level (entry);
const char *message_string = mongoc_structured_log_entry_get_message_string (entry);
/*
* With a single-threaded mongoc_client_t, handlers will always be called
* by the thread that owns the client. On a mongoc_client_pool_t, handlers
* are shared by multiple threads and must be reentrant.
*
* Note that unstructured logging includes a global mutex in the API,
* but structured logging allows applications to avoid lock contention
* even when multiple threads are issuing commands simultaneously.
*
* Simple apps like this example can achieve thread safety by adding their
* own global mutex. For other apps, this would be a performance bottleneck
* and it would be more appropriate for handlers to process their log
* messages concurrently.
*
* In this example, our mutex protects access to a global log counter.
* In a real application, you may need to protect access to a shared stream
* or queue.
*/
pthread_mutex_lock (&handler_mutex);
static unsigned log_serial_number = 0;
printf ("%u. Log entry with component=%s level=%s message_string='%s'\n",
++log_serial_number,
mongoc_structured_log_get_component_name (component),
mongoc_structured_log_get_level_name (level),
message_string);
/*
* At this point, the handler might make additional filtering decisions
* before asking for a bson_t. As an example, let's log the component and
* level for all messages but only show contents for command logs.
*/
if (component == MONGOC_STRUCTURED_LOG_COMPONENT_COMMAND) {
bson_t *message = mongoc_structured_log_entry_message_as_bson (entry);
char *json = bson_as_relaxed_extended_json (message, NULL);
printf ("Full log message, as json: %s\n", json);
bson_destroy (message);
bson_free (json);
}
pthread_mutex_unlock (&handler_mutex);
}
int
main (void)
{
const char *uri_string = "mongodb://localhost:27017";
int result = EXIT_FAILURE;
bson_error_t error;
mongoc_uri_t *uri = NULL;
mongoc_structured_log_opts_t *log_opts = NULL;
mongoc_client_t *client = NULL;
mongoc_client_pool_t *pool = NULL;
/*
* Note that structured logging only applies per-client or per-pool,
* and it won't be used during or before mongoc_init.
*/
mongoc_init ();
/*
* Logging options are represented by a mongoc_structured_log_opts_t,
* which can be copied into a mongoc_client_t or mongoc_client_pool_t
* using mongoc_client_set_structured_log_opts() or
* mongoc_client_pool_set_structured_log_opts(), respectively.
*
* Default settings are captured from the environment into
* this structure when it's constructed.
*/
log_opts = mongoc_structured_log_opts_new ();
/*
* For demonstration purposes, set up a handler that receives all possible log messages.
*/
pthread_mutex_init (&handler_mutex, NULL);
mongoc_structured_log_opts_set_max_level_for_all_components (log_opts, MONGOC_STRUCTURED_LOG_LEVEL_TRACE);
mongoc_structured_log_opts_set_handler (log_opts, example_handler, NULL);
/*
* By default libmongoc proceses log options from the environment first,
* and then allows you to apply programmatic overrides. To request the
* opposite behavior, allowing the environment to override programmatic
* defaults, you can ask for the environment to be re-read after setting
* your own defaults.
*/
mongoc_structured_log_opts_set_max_levels_from_env (log_opts);
/*
* Create a MongoDB URI object. This example assumes a local server.
*/
uri = mongoc_uri_new_with_error (uri_string, &error);
if (!uri) {
fprintf (stderr, "URI parse error: %s\n", error.message);
goto done;
}
/*
* Create a new client pool.
*/
pool = mongoc_client_pool_new (uri);
if (!pool) {
goto done;
}
/*
* Set the client pool's log options.
* This must happen only once, and only before the first mongoc_client_pool_pop.
* There's no need to keep log_opts after this point.
*/
mongoc_client_pool_set_structured_log_opts (pool, log_opts);
/*
* Check out a client, and do some work that we'll see logs from.
* This example just sends a 'ping' command.
*/
client = mongoc_client_pool_pop (pool);
if (!client) {
goto done;
}
bson_t *command = BCON_NEW ("ping", BCON_INT32 (1));
bson_t reply;
bool command_ret = mongoc_client_command_simple (client, "admin", command, NULL, &reply, &error);
bson_destroy (command);
bson_destroy (&reply);
mongoc_client_pool_push (pool, client);
if (!command_ret) {
fprintf (stderr, "Command error: %s\n", error.message);
goto done;
}
result = EXIT_SUCCESS;
done:
mongoc_uri_destroy (uri);
mongoc_structured_log_opts_destroy (log_opts);
mongoc_client_pool_destroy (pool);
mongoc_cleanup ();
return result;
}
SEE ALSO:
mongoc_structured_log_entry_get_component mongoc_structured_log_en-
try_get_level mongoc_structured_log_entry_message_as_bson
AUTHOR
MongoDB, Inc
COPYRIGHT
2009-present, MongoDB, Inc.
1.30.2 Apr 12, 2025 MONGOC_LOGGING(3)
UNSTRUCTURED LOGGING | STRUCTURED LOGGING | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mongoc_logging&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>