GLiblog_structured

Log a message with structured data.

The message will be passed through to 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 be aborted by calling G_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 GLogWriterFunc 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 g_log_structured_array(). The keys for structured data should follow the systemd journal fields 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, with the exception of "GLIB_DOMAIN" which was only fixed with GLib 2.82.3.

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, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), g_error(), etc, if the symbol 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. If adding a MESSAGE_ID, consider shipping a message 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 g_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:

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.

Available since: 2.50

This function is not directly available to language bindings.