1MONGOC_LOGGING(3)                  libmongoc                 MONGOC_LOGGING(3)
2
3
4
5MongoDB C driver Logging Abstraction
6

SYNOPSIS

8          typedef enum {
9             MONGOC_LOG_LEVEL_ERROR,
10             MONGOC_LOG_LEVEL_CRITICAL,
11             MONGOC_LOG_LEVEL_WARNING,
12             MONGOC_LOG_LEVEL_MESSAGE,
13             MONGOC_LOG_LEVEL_INFO,
14             MONGOC_LOG_LEVEL_DEBUG,
15             MONGOC_LOG_LEVEL_TRACE,
16          } mongoc_log_level_t;
17
18          #define MONGOC_ERROR(...)
19          #define MONGOC_CRITICAL(...)
20          #define MONGOC_WARNING(...)
21          #define MONGOC_MESSAGE(...)
22          #define MONGOC_INFO(...)
23          #define MONGOC_DEBUG(...)
24
25          typedef void (*mongoc_log_func_t) (mongoc_log_level_t log_level,
26                                             const char *log_domain,
27                                             const char *message,
28                                             void *user_data);
29
30          void
31          mongoc_log_set_handler (mongoc_log_func_t log_func, void *user_data);
32          void
33          mongoc_log (mongoc_log_level_t log_level,
34                      const char *log_domain,
35                      const char *format,
36                      ...) BSON_GNUC_PRINTF (3, 4);
37          const char *
38          mongoc_log_level_str (mongoc_log_level_t log_level);
39          void
40          mongoc_log_default_handler (mongoc_log_level_t log_level,
41                                      const char *log_domain,
42                                      const char *message,
43                                      void *user_data);
44          void
45          mongoc_log_trace_enable (void);
46          void
47          mongoc_log_trace_disable (void);
48
49       The MongoDB C driver comes with an abstraction for logging that you can
50       use in your application, or integrate with an existing logging system.
51

MACROS

53       To make logging a little less painful, various helper macros  are  pro‐
54       vided. See the following example.
55
56          #undef MONGOC_LOG_DOMAIN
57          #define MONGOC_LOG_DOMAIN "my-custom-domain"
58
59          MONGOC_WARNING ("An error occurred: %s", strerror (errno));
60

CUSTOM LOG HANDLERS

62       The  default log handler prints a timestamp and the log message to std‐
63       out, or to stderr for warnings, critical messages, and errors.
64              You can  override  the  handler  with  mongoc_log_set_handler().
65              Your handler function is called in a mutex for thread safety.
66
67       For  example,  you could register a custom handler to suppress messages
68       at INFO level and below:
69
70          void
71          my_logger (mongoc_log_level_t log_level,
72                     const char *log_domain,
73                     const char *message,
74                     void *user_data)
75          {
76             /* smaller values are more important */
77             if (log_level < MONGOC_LOG_LEVEL_INFO) {
78                mongoc_log_default_handler (log_level, log_domain, message, user_data);
79             }
80          }
81
82          int
83          main (int argc, char *argv[])
84          {
85             mongoc_log_set_handler (my_logger, NULL);
86             mongoc_init ();
87
88             /* ... your code ...  */
89
90             mongoc_cleanup ();
91             return 0;
92          }
93
94       Note that in the example above mongoc_log_set_handler() is  called  be‐
95       fore  mongoc_init().  Otherwise, some log traces could not be processed
96       by the log handler.
97
98       To restore the default handler:
99
100          mongoc_log_set_handler (mongoc_log_default_handler, NULL);
101

DISABLE LOGGING

103       To disable all logging, including warnings, critical messages  and  er‐
104       rors, provide an empty log handler:
105
106          mongoc_log_set_handler (NULL, NULL);
107

TRACING

109       If  compiling your own copy of the MongoDB C driver, consider configur‐
110       ing with -DENABLE_TRACING=ON to enable function tracing and  hex  dumps
111       of  network  packets to STDERR and STDOUT during development and debug‐
112       ging.
113
114       This is especially useful when debugging what may be  going  on  inter‐
115       nally in the driver.
116
117       Trace   messages   can   be   enabled  and  disabled  by  calling  mon‐
118       goc_log_trace_enable() and mongoc_log_trace_disable()
119
120       NOTE:
121          Compiling the driver with -DENABLE_TRACING=ON will affect  its  per‐
122          formance. Disabling tracing with mongoc_log_trace_disable() signifi‐
123          cantly reduces the overhead, but cannot remove it completely.
124

AUTHOR

126       MongoDB, Inc
127

129       2017-present, MongoDB, Inc
130
131
132
133
1341.25.1                           Nov 08, 2023                MONGOC_LOGGING(3)
Impressum