log_structured

Log a message with structured data.

The message will be passed through to the log writer set by the application using [func@GLib.log_set_writer_func]. If the message is fatal ( i.e. its log level is [flags@GLib.LogLevelFlags.LEVEL_ERROR]), the program will be aborted by calling [func@GLib.BREAKPOINT] at the end of this function. If the log writer returns [enum@GLib.LogWriterOutput.UNHANDLED] (failure), no other fallback writers will be tried. See the documentation for [type@GLib.LogWriterFunc] for information on chaining writers.

The structured data is provided as key–value pairs, where keys are UTF-8 strings, and values are arbitrary pointers — typically pointing to UTF-8 strings, but that is not a requirement. To pass binary (non-nul-terminated) structured data, use [func@GLib.log_structured_array]. The keys for structured data should follow the [systemd journal fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html ) specification. It is suggested that custom keys are namespaced according to the code which sets them. For example, custom keys from GLib all have a `GLIB_` prefix.

Note that keys that expect UTF-8 strings (specifically `"MESSAGE"` and `"GLIB_DOMAIN"`) must be passed as nul-terminated UTF-8 strings until GLib version 2.74.1 because the default log handler did not consider the length of the `GLogField`. Starting with GLib 2.74.1 this is fixed and non-nul-terminated UTF-8 strings can be passed with their correct length.

The log_domain will be converted into a `GLIB_DOMAIN` field. log_level will be converted into a `PRIORITY` field. The format string will have its placeholders substituted for the provided values and be converted into a `MESSAGE` field.

Other fields you may commonly want to pass into this function:

* `MESSAGE_ID` * `CODE_FILE` * `CODE_LINE` * `CODE_FUNC` * `ERRNO`

Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by the logging macros, [func@GLib.DEBUG_HERE], [func@GLib.message], [ func@GLib.warning], [func@GLib.critical], [func@GLib.error], etc, if the symbol `G_LOG_USE_STRUCTURED` is defined before including `glib.h`.

For example:

```c g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", "MY_APPLICATION_CUSTOM_FIELD", "some debug string", "MESSAGE", "This is a debug message about pointer p and integer u.", some_pointer, some_integer); ```

Note that each `MESSAGE_ID` must be [uniquely and randomly generated]( https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). If adding a `MESSAGE_ID`, consider shipping a [message catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with your software.

To pass a user data pointer to the log writer function which is specific to this logging call, you must use [func@GLib.log_structured_array] and pass the pointer as a field with `GLogField.length` set to zero, otherwise it will be interpreted as a string.

For example:

```c const GLogField fields[] = { { "MESSAGE", "This is a debug message.", -1 }, { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 }, { "MY_APPLICATION_STATE", state_object, 0 }, }; g_log_structured_array ( G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); ```

Note also that, even if no other structured fields are specified, there must always be a `MESSAGE` key before the format string. The `MESSAGE`-format pair has to be the last of the key-value pairs, and `MESSAGE` is the only field for which `printf()`-style formatting is supported.

The default writer function for `stdout` and `stderr` will automatically append a new-line character after the message, so you should not add one manually to the format string.

Parameters:

log_domain	log domain, usually `G_LOG_DOMAIN`
...	key-value pairs of structured data to add to the log entry, followed by the key `MESSAGE`, followed by a `printf()`-style message format, followed by parameters to insert in the format string
log_level	log level, either from [type@GLib.LogLevelFlags], or a user-defined level