Structured Logging

Overview

In this guide, you can learn how to use the C driver to configure structured logging for your application. Logging allows you to view a discrete, event-based log of driver activities.

Loggers log messages at a severity, or verbosity, level that you can specify. When you enable logging in your application, you can receive information about your application's activities at different levels of detail. The driver allows you to log information categorized at the following severity levels:

• emergency

• alert

• critical

• error

• warn

• notice

• info

• debug

• trace

• off

The preceding list is ordered by decreasing severity level, with emergency as the highest severity level. When you specify a severity level, the driver also logs all messages with higher severity levels. For example, if you set the log level to critical, the driver will also log messages with emergency and alert severity levels.

The lower the severity level you specify, the more information the driver logs, which might impact the performance of your application.

Logging Options

Structured log settings are tracked explicitly by a mongoc_structured_log_opts_t instance. The C driver takes default settings from environment variables and offers additional optional programmatic configuration. Use mongoc_structured_log_opts_new() to specify environment variables. To learn more about mongoc_structured_log_opts_t, see mongoc_structured_log_opts_t in the libmongoc API documentation.

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, use the mongoc_structured_log_opts_set_max_levels_from_env() function. Structured log messages might 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. To learn more about mongoc_structured_log_opts_set_max_levels_from_env(), see mongoc_structured_log_opts_set_max_levels_from_env() in the libmongoc API documentation.

Implement Logging

The following code block implements logging by doing the following:

• Creates a mongoc_structured_log_opts_t type to configure logging

• Sets the desired log level to INFO

• Provides a handler function to process log messages

• Applies the logging options to your client or client pool by using the mongoc_client_set_structured_log_opts() function

#include <mongoc/mongoc.h>  
#include <stdio.h>  
  
static void log_handler(const mongoc_structured_log_entry_t *entry, void *user_data) {  
    printf("Log: %s - %s\n",  
           mongoc_structured_log_get_component_name(mongoc_structured_log_entry_get_component(entry)),  
           mongoc_structured_log_entry_get_message_string(entry));  
}  
  
int main(void) {  
    mongoc_init();  
      
    // Create logging options  
    mongoc_structured_log_opts_t *log_opts = mongoc_structured_log_opts_new();  
    mongoc_structured_log_opts_set_max_level_for_all_components(log_opts, MONGOC_STRUCTURED_LOG_LEVEL_INFO);  
    mongoc_structured_log_opts_set_handler(log_opts, log_handler, NULL);  
      
    // Create client and set logging  
    mongoc_client_t *client = mongoc_client_new("<connection-string>");  
    mongoc_client_set_structured_log_opts(client, log_opts);  
      
    // Perform operation to generate logs  
    bson_t *command = BCON_NEW("ping", BCON_INT32(1));  
    bson_t reply;  
    bson_error_t error;  
    mongoc_client_command_simple(client, "admin", command, NULL, &reply, &error);  
      
    // Cleanup  
    bson_destroy(command);  
    bson_destroy(&reply);  
    mongoc_structured_log_opts_destroy(log_opts);  
    mongoc_client_destroy(client);  
    mongoc_cleanup();  
    return 0;  
}  

If you run your application and log against connections at the debug level, the driver emits messages whenever you open, use, and close a connection. The following code shows the command for this logging specification:

mongoc_structured_log_opts_t *log_opts = mongoc_structured_log_opts_new();  
mongoc_structured_log_opts_set_max_level_for_all_components(  
    log_opts, MONGOC_STRUCTURED_LOG_LEVEL_DEBUG);  
mongoc_structured_log_opts_set_handler(log_opts, debug_log_handler, NULL);  
  
// Create client with DEBUG logging enabled  
mongoc_client_t *client = mongoc_client_new("<connection-string>");  
mongoc_client_set_structured_log_opts(client, log_opts);

With debug level tracing specified, when you open and use a connection, the driver generates debug log messages:

bson_t *doc = BCON_NEW("x", BCON_INT32(1));
bson_error_t error;
if (!mongoc_collection_insert_one(collection, doc, NULL, NULL, &error)) {
    fprintf(stderr, "Insert failed: %s\n", error.message);
}

[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool created topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool created topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool created topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection pool ready topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection checkout started topologyId="..." serverHost="..." serverPort=27017
[2023-07-21T18:13:00Z DEBUG mongodb::connection] Connection created topologyId="..." serverHost="..." serverPort=27017 driverConnectionId=1
...

To learn more about how to specify other log levels in the C driver, see Levels and Components in the libmongoc API documentation.

Additional Information

To learn more about setting client options, see the guide on Connect to MongoDB. To learn more about structured logging in the C driver, see Structured Logging in the libmongoc API documentation.