<?xml version="1.0"?>

<page id="logging"
      type="guide"
      style="class"
      xmlns="http://projectmallard.org/1.0/"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/experimental/ui/">

  <info>
    <link type="guide" xref="index#api-reference"/>
  </info>

  <title>Logging</title>
  <subtitle>MongoDB C driver Logging Abstraction</subtitle>

  <section id="synopsis">
    <title>Synopsis</title>
    <screen><code mime="text/x-csrc"><![CDATA[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);]]></code></screen>
    <p>The MongoDB C driver comes with an abstraction for logging that you can use in your application, or integrate with an existing logging system.</p>
  </section>

  <section id="macros">
    <title>Macros</title>
    <p>To make logging a little less painful, various helper macros are provided. See the following example.</p>
    <screen><code mime="text/x-csrc"><![CDATA[#undef MONGOC_LOG_DOMAIN
#define MONGOC_LOG_DOMAIN "my-custom-domain"

MONGOC_WARNING ("An error occurred: %s", strerror (errno));]]></code></screen>
  </section>

  <section id="tracing">
    <title>Tracing</title>
    <p>If compiling your own copy of the MongoDB C driver, consider configuring with <code>--enable-tracing</code> to enable function tracing and hex dumps of network packets to <code>STDERR</code> and <code>STDOUT</code> during development and debugging.</p>
    <p>This is especially useful when debugging what may be going on internally in the driver.</p>
    <p>Trace messages can be enabled and disabled by calling <code>mongoc_log_trace_enable()</code> and <code>mongoc_log_trace_disable()</code></p>
    <note type="warning"><p>
       Compiling the driver with <code>--enable-tracing</code> will affect its performance. Disabling tracing with <code>mongoc_log_trace_disable()</code> significantly reduces the overhead, but cannot remove it completely.
    </p></note>

  </section>

  <section id="handlers">
    <title>Custom Log Handlers</title>
    <p>The default log handler prints a timestamp and the log message to <code>stdout</code>, or to <code>stderr</code> for warnings, critical messages, and errors.
    You can override the handler with <code>mongoc_log_set_handler()</code>.
    Your handler function is called in a mutex for thread safety.</p>
    <p>To restore the default handler:</p>
    <screen><code mime="text/x-csrc"><![CDATA[mongoc_log_set_handler (mongoc_log_default_handler, NULL);]]></code></screen>
  </section>

  <section id="disable-logs">
    <title>Disable logging</title>
    <p>To disable all logging, including warnings, critical messages and errors, you need to provide an empty log handler</p>
    <screen><code mime="text/x-csrc"><![CDATA[mongoc_log_set_handler (NULL, NULL);]]></code></screen>
  </section>

</page>
