![]() |
![]()
| ![]() |
![]()
This document describes a newer "structured" logging facility which reports 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(). OPTIONSStructured log settings are tracked explicitly by a mongoc_structured_log_opts_t instance. Like other drivers supporting structured logging, we take default settings from environment variables and offer additional optional programmatic 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 programmatic 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 handler, 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_tSynopsistypedef 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 maximum 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(). Functionsmongoc_structured_log_opts_new()Synopsismongoc_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. 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 warnings 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 VariablesThis is a full list of the captured environment variables.
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.
Note that log level names are always case insensitive. This is a full list of recognized names, including allowed aliases:
ReturnsA newly allocated mongoc_structured_log_opts_t. mongoc_structured_log_opts_destroy()Synopsisvoid mongoc_structured_log_opts_destroy (mongoc_structured_log_opts_t *opts); Parameters
DescriptionThis function releases all resources associated with a mongoc_structured_log_opts_t. Does nothing if opts is NULL. mongoc_structured_log_opts_set_handler()Synopsisvoid mongoc_structured_log_opts_set_handler (mongoc_structured_log_opts_t *opts, 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. 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. 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
SEE ALSO: Structured Logging mongoc_structured_log_opts_set_max_level_for_component()Synopsisbool mongoc_structured_log_opts_set_max_level_for_component (mongoc_structured_log_opts_t *opts, 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. By default, each component's log level may come from environment variables. See mongoc_structured_log_opts_set_max_levels_from_env(). Parameters
ReturnsReturns 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()Synopsisbool mongoc_structured_log_opts_set_max_level_for_all_components (mongoc_structured_log_opts_t *opts, 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
ReturnsReturns true on success, or false if the supplied parameters were incorrect. SEE ALSO: Structured Logging mongoc_structured_log_opts_set_max_levels_from_env()Synopsisbool 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. 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. ReturnsReturns 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()Synopsismongoc_structured_log_level_t mongoc_structured_log_opts_get_max_level_for_component (const mongoc_structured_log_opts_t *opts, Parameters
ReturnsReturns 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()Synopsisbool mongoc_structured_log_opts_set_max_document_length (mongoc_structured_log_opts_t *opts, 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 sequence, we instead truncate the document earlier at the nearest boundary between code points. Parameters
ReturnsReturns 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()Synopsisbool 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 environment variable formats. Parse errors may cause a warning message, delivered via unstructured logging. 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_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. ReturnsReturns 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 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_document_length()Synopsissize_t mongoc_structured_log_opts_get_max_document_length (const mongoc_structured_log_opts_t *opts); Parameters
ReturnsReturns the current maximum document length set in opts, as a size_t. SEE ALSO: Structured Logging SEE ALSO: Structured Logging LEVELS AND COMPONENTSLog levels and components are defined as mongoc_structured_log_level_t and mongoc_structured_log_component_t enumerations. Utilities are provided to convert between these values and their standard string representations. The string values are case-insensitive. typedef enum { mongoc_structured_log_level_tSynopsistypedef enum { mongoc_structured_log_level_t enumerates the available log levels for use with structured logging. Functionsmongoc_structured_log_get_level_name()Synopsisconst char * mongoc_structured_log_get_level_name (mongoc_structured_log_level_t level); Parameters
ReturnsIf 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()Synopsisbool 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
ReturnsIf 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_tSynopsistypedef enum { 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. Functionsmongoc_structured_log_get_component_name()Synopsisconst char * mongoc_structured_log_get_component_name (mongoc_structured_log_component_t component); Parameters
ReturnsIf 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()Synopsisbool mongoc_structured_log_get_named_component (const char *name, mongoc_structured_log_component_t *out); Look up a component by name. Case insensitive. Parameters
ReturnsIf 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_structured_log_get_named_level mongoc_structured_log_get_component_name
mongoc_structured_log_get_named_component
LOG HANDLERSEach mongoc_client_pool_t or standalone mongoc_client_t has its own instance 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 provides 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_tSynopsistypedef 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(). 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. Parameters
SEE ALSO: Structured Logging LOG ENTRIESEach 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 requested 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_tSynopsistypedef 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. Functionsmongoc_structured_log_entry_get_component()Synopsismongoc_structured_log_component_t mongoc_structured_log_entry_get_component (const mongoc_structured_log_entry_t *entry); Parameters
ReturnsThe mongoc_structured_log_component_t associated with this log entry. SEE ALSO: Structured Logging mongoc_structured_log_entry_get_level()Synopsismongoc_structured_log_level_t mongoc_structured_log_entry_get_level (const mongoc_structured_log_entry_t *entry); Parameters
ReturnsThe mongoc_structured_log_level_t associated with this log entry. SEE ALSO: Structured Logging mongoc_structured_log_entry_get_message_string()Synopsisconst char * mongoc_structured_log_entry_get_message_string (const mongoc_structured_log_entry_t *entry); Parameters
ReturnsA string, guaranteed to be valid only during the lifetime of the structured 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()Synopsisbson_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 representation. 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
ReturnsA new allocated bson_t that must be freed with a call to bson_destroy(). SEE ALSO: Structured Logging SEE ALSO: Structured Logging EXAMPLEexample-structured-log.c /* gcc example-structured-log.c -o example-structured-log \ SEE ALSO: mongoc_structured_log_entry_get_component
mongoc_structured_log_entry_get_level
mongoc_structured_log_entry_message_as_bson
AUTHORMongoDB, Inc COPYRIGHT2009-present, MongoDB, Inc.
|