ldproxy

Audit Logging

Audit Logging can be used to automatically create and save audit logs for API requests. The configuration is split across three levels:

  • Global level, which is described here. The global configuration applies to all APIs.
  • API level, which is explained in more detail at API configuration. The API-level configuration is used to fine-tune the configuration for a specific API.
  • Provider level, which consists of the schema option audit that is described in more detail at Schema Definitions. It is used to specify which properties to log.

Below is a detailed description of the global configuration, notes on storage and an example containing the relevant pieces from all configuration levels.

Options

NameDefaultDescriptionTypeSince
enabled
false
If true, audit logging is enabled for all APIs. APIs can be explicitly disabled in the API configuration. Audit logging is globally disabled if false.
boolean
4.8
retries
3
Indicates how often the write process should be retried on errors. Should be set to 0 if no retries are desired. If writing fails after the specified number of retries, the log entry will be written to the application log.
number
4.8
pathPrefix
{api}/{date}
Specifies the path to prepend to the log file. {api} and {date} are replaced with the API ID and the request's ISO date, respectively. For example, log files for {api}/foo/{date}/bar would be stored at logs/audit/vineyards/foo/2026-06-03/bar.
string
4.8
type
JSON
Specifies the format in which logs are stored. Currently supported: JSON and JSON_PRETTY (formatted JSON).
string
4.8
headers
included: [ '*' ], excluded: []
The included list specifies which headers should be logged. The excluded list specifies which headers from included should not be logged. The special value * can be used for both lists and covers all headers. If excluded: [ '*' ], no headers are logged.
object
4.8
claims
included: [], excluded: []
Specifies which claims from the token should be logged and which should explicitly not be logged. Uses the same included/excluded logic as headers.
object
4.8
httpStatus
included: [ '200' ], excluded: []
Specifies for which HTTP status codes requests should be logged and which should explicitly not be logged. Uses the same included/excluded logic as headers.
object
4.8

Storage

The log entries are stored in the resource store in the logs/audit directory. The file name matches the request ID from the application log.

Examples

In the following, examples are shown for the global, API and provider configuration, as well as an audit log example that is produced from the configs. The Vineyardsopen in new window-API from the demosopen in new window has been used here.

Global config:


auditLog:
 enabled: true
 retries: 3
 type: JSON_PRETTY
 pathPrefix: "mysubdirectory/{api}/{date}"
 headers:
   included: [ "User-Agent", "Host" ]
   excluded: [ ]
 claims:
   included: [ "realm_access", "resource_access" ]
   excluded: [ ]
 httpStatus:
   included: [ "200" ]
   excluded: [ ]

API config:


auditLog:
 enabled: true
 operations:
   - "data:read::vineyards"
   - "write"

Provider config:


types:
 vineyards:
   sourcePath: /Weinlagen
   type: OBJECT
   properties:
     registerId:
       sourcePath: wlg_nr
       type: INTEGER
       role: ID
       label: Vineyard register number
       audit: true
     name:
       sourcePath: wlg_name
       type: STRING
       label: Vineyard name
       audit: true

As a result of the configs above, the following audit log could be produced and saved as logs/audit/mysubdirectory/vineyards/2026-06-15/48f4923c-b52c-4dfb-b45e-3e892995a473.json:


{
 "id" : "48f4923c-b52c-4dfb-b45e-3e892995a473",
 "started" : "2026-06-15T08:27:05.372819295Z",
 "finished" : "2026-06-15T08:27:05.416584477Z",
 "api" : "vineyards",
 "actor" : {
   "type" : "USER",
   "id" : "johndoe",
   "claims" : {
     "realm_access" : {
       "roles" : [
         "offline_access",
         "authorization"
       ]
     },
     "resource_access" : {
       "roles" : [
         "read",
         "manage-account",
         "manage-account-links",
         "view-profile"
       ]
     }
   }
 },
 "operation" : {
   "method" : "GET",
   "path" : "/collections/vineyards/items",
   "headers" : {
     "User-Agent" : "Mozilla/5.0 (X11; Linux x86_64; rv:140.0) Gecko/20100101 Firefox/140.0",
     "Host" : "localhost:7080"
   },
   "parameter" : {
     "f" : "json"
   },
   "status" : "200"
 },
 "target" : {
   "features" : [
     {
       "id" : "460258",
       "name" : "Kupp"
     },
     {
       "id" : "511109",
       "name" : "Höll"
     }
   ]
 }
}
Legal NoticePrivacy Notice