1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
<?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);
void mongoc_log_trace_enable (void);
void mongoc_log_trace_disable (void);]]></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="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>For example, you could register a custom handler to suppress messages at INFO level and below:</p>
<screen><code mime="text/x-csrc"><![CDATA[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_init ();
mongoc_log_set_handler (my_logger, NULL);
/* ... your code ... */
mongoc_cleanup ();
return 0;
}]]></code></screen>
<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, provide an empty log handler:</p>
<screen><code mime="text/x-csrc"><![CDATA[mongoc_log_set_handler (NULL, NULL);]]></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>
</page>
|
