Import wiredtiger: 568c00457245bb02ee14e465eb59ffe73ddbf203 from branch mongodb-master

ref: 1439b90c1f..568c004572
for: 5.2.0

WT-8257       Update WiredTiger Doxygen documentation to reflect changes to the verbose configuration API

4 files changed, 156 insertions, 1 deletions

diff --git a/src/third_party/wiredtiger/examples/c/ex_verbose.c b/src/third_party/wiredtiger/examples/c/ex_verbose.c
new file mode 100644
index 00000000000..b464ef19c55
--- /dev/null
+++ b/src/third_party/wiredtiger/examples/c/ex_verbose.c
@@ -0,0 +1,92 @@
+/*-
+ * Public Domain 2014-present MongoDB, Inc.
+ * Public Domain 2008-2014 WiredTiger, Inc.
+ *
+ * This is free and unencumbered software released into the public domain.
+ *
+ * Anyone is free to copy, modify, publish, use, compile, sell, or
+ * distribute this software, either in source code form or as a compiled
+ * binary, for any purpose, commercial or non-commercial, and by any
+ * means.
+ *
+ * In jurisdictions that recognize copyright laws, the author or authors
+ * of this software dedicate any and all copyright interest in the
+ * software to the public domain. We make this dedication for the benefit
+ * of the public at large and to the detriment of our heirs and
+ * successors. We intend this dedication to be an overt act of
+ * relinquishment in perpetuity of all present and future rights to this
+ * software under copyright law.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+ * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * ex_verbose.c
+ *	Demonstrate how to configure verbose messaging in WiredTiger.
+ */
+#include <test_util.h>
+
+static const char *home;
+
+int handle_wiredtiger_message(WT_EVENT_HANDLER *, WT_SESSION *, const char *);
+
+/*
+ * handle_wiredtiger_message --
+ *     Function to handle message callbacks from WiredTiger.
+ */
+int
+handle_wiredtiger_message(WT_EVENT_HANDLER *handler, WT_SESSION *session, const char *message)
+{
+    /* Unused parameters */
+    (void)handler;
+    printf("WiredTiger Message - Session: %p, Message: %s\n", session, message);
+
+    return (0);
+}
+
+static void
+config_verbose(void)
+{
+    WT_CONNECTION *conn;
+    WT_SESSION *session;
+    WT_CURSOR *cursor;
+
+    WT_EVENT_HANDLER event_handler;
+
+    event_handler.handle_message = handle_wiredtiger_message;
+    event_handler.handle_error = NULL;
+    event_handler.handle_progress = NULL;
+    event_handler.handle_close = NULL;
+
+    /*! [Configure verbose_messaging] */
+    error_check(wiredtiger_open(
+      home, (WT_EVENT_HANDLER *)&event_handler, "create,verbose=[api:1,version,write:0]", &conn));
+    /*! [Configure verbose_messaging] */
+
+    /* Make a series of API calls, to ensure verbose messages are produced. */
+    printf("ex_verbose: expect verbose messages to follow:\n");
+    error_check(conn->open_session(conn, NULL, NULL, &session));
+    error_check(session->create(session, "table:verbose", "key_format=S,value_format=S"));
+    error_check(session->open_cursor(session, "table:verbose", NULL, NULL, &cursor));
+    cursor->set_key(cursor, "foo");
+    cursor->set_value(cursor, "bar");
+    error_check(cursor->insert(cursor));
+    error_check(cursor->close(cursor));
+    printf("ex_verbose: end of verbose messages\n");
+
+    error_check(conn->close(conn, NULL));
+}
+
+int
+main(int argc, char *argv[])
+{
+    home = example_setup(argc, argv);
+
+    config_verbose();
+
+    return (EXIT_SUCCESS);
+}
diff --git a/src/third_party/wiredtiger/import.data b/src/third_party/wiredtiger/import.data
index 704ed3d2138..02ff9225a24 100644
--- a/src/third_party/wiredtiger/import.data
+++ b/src/third_party/wiredtiger/import.data
@@ -2,5 +2,5 @@
     "vendor": "wiredtiger",
     "github": "wiredtiger/wiredtiger.git",
     "branch": "mongodb-master",
-    "commit": "1439b90c1f696d732a3fb0fd7772e815556a994e"
+    "commit": "568c00457245bb02ee14e465eb59ffe73ddbf203"
 }
diff --git a/src/third_party/wiredtiger/src/docs/programming.dox b/src/third_party/wiredtiger/src/docs/programming.dox
index e640293fd95..b8bae54cbaf 100644
--- a/src/third_party/wiredtiger/src/docs/programming.dox
+++ b/src/third_party/wiredtiger/src/docs/programming.dox
@@ -15,6 +15,7 @@ each of which is ordered by one or more columns.
 - @subpage cursors
 - @subpage transactions
 - @subpage error_handling
+- @subpage verbose_messaging
 
 <h2>Storage options</h2>
 - @subpage schema
diff --git a/src/third_party/wiredtiger/src/docs/verbose-messaging.dox b/src/third_party/wiredtiger/src/docs/verbose-messaging.dox
new file mode 100644
index 00000000000..314c57e1514
--- /dev/null
+++ b/src/third_party/wiredtiger/src/docs/verbose-messaging.dox
@@ -0,0 +1,62 @@
+/*! @page verbose_messaging Verbose Messaging
+
+As part of normal operation, WiredTiger will produce verbose messages
+around various events, actions and possible issues/errors. Verbose
+messages are spread across various categories, representing different sub-systems
+throughout WiredTiger. Verbose messages can be usefully leveraged to monitor,
+debug and diagnose events across WiredTiger's runtime.
+
+@section verbosity_levels Verbosity Levels
+
+WiredTiger associates a verbosity level with each message. The verbosity
+level denotes the severity of a given message, ranging from high
+severity error messages (\c ERROR) to low severity debug informational
+messages (\c DEBUG). The full range of verbosity levels and their associated
+meanings are:
+
+<table>
+@hrow{Level, Value, Description}
+@row{\c ERROR, -3, Critical error conditions triggered in WiredTiger. Usually requiring a DB restart. }
+@row{\c WARNING, -2, Warning conditions potentially signaling non-imminent errors and behaviors. Important to be aware of and useful for diagnosing potential error states. }
+@row{\c NOTICE, -1, Messages for significant events in WiredTiger\, usually worth noting. Notice messages are associated with normal runtime operations i.e not produced from any state considered harmful or error-prone.}
+@row{\c INFO, 0, Informational style messages\, usually describing statuses and actions performed by WiredTiger. }
+@row{\c DEBUG, 1, Low severity messages\, useful for debugging purposes. }
+</table>
+
+@section verbosity_categories Verbosity Categories
+
+Each verbose message is associated with a category. Verbose categories represent a range of different
+sub-systems in WiredTiger, where messages will denote a specific operation or event under a given sub-system.
+To see the complete exhaustive list of available verbose categories, refer to the \c 'verbose' configuration option
+under ::wiredtiger_open.
+
+Each verbosity category can be individually configured with a verbosity level (as described in @ref verbosity_levels).
+This allowing the end user to fine tune and tailor the verbosity of each category to fit their use case
+e.g configuring WiredTiger's runtime for debugging/monitoring a specific sub-system.
+
+When a category is assigned a verbosity level, any associated message less than or equal to (\c <=) that level will be displayed.
+As an example, configuring the \c checkpoint category with the \c DEBUG verbosity level would display \c checkpoint related messages
+less than or equal to the \c DEBUG level.
+Any category that is not explicitly configured with a verbosity level will default to the \c NOTICE (\c -1) level, effectively masking
+\c INFO and \c DEBUG informational messages.
+
+@subsection verbosity_configuration Configuring Verbose Categories
+
+Configuration of the verbose messaging system is achieved via the \c verbose configuration option when either
+opening a wiredtiger connection (::wiredtiger_open) or re-configuring a wiredtiger connection (WT_CONNECTION::reconfigure).
+The \c verbose configuration takes in a list of categories, where each category can be optionally associated with a verbosity level.
+An example configuring a WiredTiger connection with verbosity enabled:
+
+@snippet ex_verbose.c Configure verbose_messaging
+
+In the above example:
+- \c api is configured to the \c DEBUG verbosity level.
+- \c version is configured to the \c DEBUG verbosity level. If a category is passed without a verbosity
+level (.e.g \c <code>:0</code>), the category will default to the \c DEBUG level (i.e \c <code>verbose=[version]</code> is equivalent to <code>verbose=[version:1]</code>).
+- \c write is configured to the \c INFO verbosity level.
+
+When configuring verbosity levels, the lowest value the user can associate with a category is \c 0 (\c INFO). This ensuring
+the lower verbosity levels, \c NOTICE (\c -1) and below, are unmasked. Messages with levels less than or equal to \c NOTICE are considered
+to have important diagnostic information and thus should not be hidden.
+
+*/