Update structured logging docs a bit

Remove references to removed macros, add some more links
to standard journal fields.
This commit is contained in:
Matthias Clasen
2016-07-20 20:38:46 -04:00
parent 4643cadc17
commit 849599671c

View File

@@ -1302,8 +1302,8 @@ color_reset (gboolean use_color)
* by the key "MESSAGE", followed by a printf()-style message format, * by the key "MESSAGE", followed by a printf()-style message format,
* followed by parameters to insert in the format string * followed by parameters to insert in the format string
* *
* Log a message with structured data. The message will be passed through to the * Log a message with structured data. The message will be passed through to
* log writer set by the application using g_log_set_writer_func(). If the * the log writer set by the application using g_log_set_writer_func(). If the
* message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
* be aborted at the end of this function. * be aborted at the end of this function.
* *
@@ -1318,8 +1318,12 @@ color_reset (gboolean use_color)
* `GLIB_` prefix. * `GLIB_` prefix.
* *
* The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will * The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will
* be converted into a `PRIORITY` field. @format will have its placeholders * be converted into a
* substituted for the provided values and be converted into a `MESSAGE` field. * [`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=)
* field. The format string will have its placeholders substituted for the provided
* values and be converted into a
* [`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=)
* field.
* *
* Other fields you may commonly want to pass into this function: * Other fields you may commonly want to pass into this function:
* *
@@ -1330,20 +1334,20 @@ color_reset (gboolean use_color)
* * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) * * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=)
* *
* Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by
* the logging macros, g_debug_structured(), G_DEBUG_HERE(), * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(),
* g_message_structured(), g_warning_structured(), g_critical_structured() and * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
* g_error_structured(). * glib.h.
* *
* For example: * For example:
* ``` * |[<!-- language="C" -->
* g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
* "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
* "MY_APPLICATION_CUSTOM_FIELD", "some debug string", * "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
* "MESSAGE", "This is a debug message about pointer %p and integer %u.", * "MESSAGE", "This is a debug message about pointer %p and integer %u.",
* some_pointer, some_integer); * some_pointer, some_integer);
* ``` * ]|
* *
* Note that each `MESSAGE_ID` **must** be [uniquely and randomly * Note that each `MESSAGE_ID` must be [uniquely and randomly
* generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). * generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=).
* If adding a `MESSAGE_ID`, consider shipping a [message * If adding a `MESSAGE_ID`, consider shipping a [message
* catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with * catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with
@@ -1355,7 +1359,7 @@ color_reset (gboolean use_color)
* interpreted as a string. * interpreted as a string.
* *
* For example: * For example:
* ``` * |[<!-- language="C" -->
* const GLogField fields[] = { * const GLogField fields[] = {
* { "MESSAGE", "This is a debug message.", -1 }, * { "MESSAGE", "This is a debug message.", -1 },
* { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, * { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
@@ -1363,14 +1367,14 @@ color_reset (gboolean use_color)
* { "MY_APPLICATION_STATE", state_object, 0 }, * { "MY_APPLICATION_STATE", state_object, 0 },
* }; * };
* g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); * g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));
* ``` * ]|
* *
* Note also that, even if no structured fields are specified, the key-value part * Note also that, even if no structured fields are specified, the key-value
* of the argument list **must** be %NULL-terminated. * part of the argument list must be %NULL-terminated.
* *
* The default writer function for `stdout` and `stderr` will automatically * The default writer function for `stdout` and `stderr` will automatically
* append a new-line character to the @format, so you should not add one * append a new-line character after the message, so you should not add one
* manually. * manually to the format string.
* *
* Since: 2.50 * Since: 2.50
*/ */