log_structured

Log a message with structured data.

The message will be passed through to the log writer set by the application using set_writer_func. If the message is fatal (i.e. its log level is g_log_level_error), the program will be aborted by calling breakpoint at the end of this function. If the log writer returns g_log_writer_unhandled (failure), no other fallback writers will be tried. See the documentation for 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 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.

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, debug_here, message, warning, critical, error, etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including `glib.h`.

For example:

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 log_structured_array and pass the pointer as a field with length set to zero, otherwise it will be interpreted as a string.

For example:

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 LogLevelFlags, or a user-defined level