# Logging

MongoDB C driver Logging Abstraction

## Synopsis

    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,
                ...) BSON_GNUC_PRINTF (3, 4);
    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);

The MongoDB C driver comes with an abstraction for logging that you can use in your application, or integrate with an existing logging system.

## Macros

To make logging a little less painful, various helper macros are provided. 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 `stdout`, or to `stderr` for warnings, critical messages, and errors.

  You can override the handler with `mongoc_log_set_handler()`. Your handler function 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 before `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 errors, provide an empty log handler:

    mongoc_log_set_handler (NULL, NULL);

## Tracing

If compiling your own copy of the MongoDB C driver, consider configuring with `-DENABLE_TRACING=ON` to enable function tracing and hex dumps of network packets to `STDERR` and `STDOUT` during development and debugging.

This is especially useful when debugging what may be going on internally in the driver.

Trace messages can be enabled and disabled by calling `mongoc_log_trace_enable()` and `mongoc_log_trace_disable()`

Note

Compiling the driver with `-DENABLE_TRACING=ON` will affect its performance. Disabling tracing with `mongoc_log_trace_disable()` significantly reduces the overhead, but cannot remove it completely.