GLib.log_structured
Description: Reference for GLib.log_structured

### Function

# GLiblog_structured

since: 2.50

#### Declaration [src]

    void
    g_log_structured (
      const gchar* log_domain,
      GLogLevelFlags log_level,
      ...
    )

#### Description [src]

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.

#### Parameters

`log_domain`

  Type: `const gchar*`

  Log domain, usually `G_LOG_DOMAIN`.

  The data is owned by the caller of the function.
  The value is a NUL terminated UTF-8 string.

`log_level`

  Type: `GLogLevelFlags`

  Log level, either from `GLogLevelFlags`, or a user-defined level.

`...`

  Type: ``

  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.