log Action

Used to augment the access log with custom fields.

Syntax

<log>
{
  "field1": "value1",
  "field2": "value2"
}
</log>

The action takes a JSON object as its argument. The object may contain nested fields. A JSON template may be used for dynamic fields. (The recipe has plenty examples for that.)

Usage

All name/value pairs of the object are registered for logging. When the system writes the flat_access event the registered fields are included in that log line.

System log fields like timestamp cannot be overriden.

You can call the action multiple times. Fields of the same name are overwritten. However, nested fields are merged into the previously registered log fields. The order of fields is maintained.

<log>
{
  "user": {
    "name": "alice"
  }
}
</log>
<log>
{
  "user": {
    "role": "admin"
  }
}
</log>

The merged custom log fields are:

{
  "user": {
    "name": "alice",
    "role": "admin"
  }
}

They would appear in the access log like this:

{"timestamp": …,"user":{"name":"alice","role":"admin"}}

Fields with null values are not included in the log event. In order to remove a previously registered field, you can unset it with null value.

The user field of the previous example can be unregistered like this:

<log>
{
  "user": null
}
</log>

See also

• Logging (Administration)
• Custom Logging (Cookbook)
• get-log() function (Reference)