Logging

There are logging configurations that are not included in the sample deployment configuration files that may be relevant for some users to add. These are described in this section.

Separating event types in the audit log output

The audit logs produced by ADS contain two types of events:

• evaluation events - data regarding access requests and their responses

• administrative events - data regarding runtime changes to the configuration of ADS

Which type of event to include in the log output is controlled by the use of different loggers, so that the output contains either evaluation events only, administrative events only, both types together, or one output item for each type (either to console or file).

note

For convenience, the following focuses on the properties added by Axiomatics. For general information about logging properties, refer to the logging sectionOpens in a new tab of the Dropwizard documentation.

Both types of events in one output

In its simplest form (and the only one available prior to version 1.8) the log data is directed to a single output.

1. Open the deployment configuration file in a text editor.

2. Locate the logging section in the deployment configuration file.

3. Add the logger com.axiomatics.audit and the other properties according to the figure.

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-audit-event.log
          archivedLogFilenamePattern: ./logs/ads-audit-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB

Both types of events in one output file

This will result in an output file named ads-audit-event.log containing both evaluation events and administrative events.

note

While the property additive: is set to true, the log stream is also output to console. Set the property to false to only create the file output.

Either evaluation events or administrative events in the output

Analysis of the audit log data may be simplified by only having one type of event in the output. This is accomplished by using one of two dedicated loggers.

• com.axiomatics.audit.ads.admin - this logger will emit only administrative events to the output (in our example a file named ads-admin-event.log)

• com.axiomatics.audit.ads.eval - this logger will emit only evaluation events to the output file (for example a file named ads-eval-event.log)

1. Open the deployment configuration file in a text editor.

2. Locate the logging section in the deployment configuration file.

3. Add either the logger com.axiomatics.audit.ads.admin or com.axiomatics.audit.ads.eval according to choice, and the other properties as appropriate for the chosen logger, see the figure. (Our example uses the evaluation event logger.)

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit.ads.eval":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-eval-event.log
          archivedLogFilenamePattern: ./logs/ads-eval-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB

Evaluation events only in the output file

This will result in an output file named ads-eval-event.log containing only evaluation events.

note

While the property additive: is set to true, the log stream is also output to console. Set the property to false to only create the file output.

Important

If you edit the configuration to use the other logger, do not forget to also update the properties currentLogFilename and archivedLogFilenamePattern accordingly, for consistency and to minimize the risk of overwriting files with the wrong data.

Separate outputs for evaluation and administrative events

It may be convenient to have the log data separated, for example, into two output files, one for each type of event. This is configured by using both of the loggers described in the previous section at the same time.

1. Open the deployment configuration file in a text editor.

2. Locate the logging section in the deployment configuration file.

3. Add the loggers com.axiomatics.audit.ads.admin, and com.axiomatics.audit.ads.eval, and the other properties as shown in the figure.

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit.ads.admin":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-admin-event.log
          archivedLogFilenamePattern: ./logs/ads-admin-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB
 
    "com.axiomatics.audit.ads.eval":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-eval-event.log
          archivedLogFilenamePattern: ./logs/ads-eval-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB

Separate output files for evaluation and administrative events

This will result in one output file named ads-eval-event.log containing evaluation events and one file named ads-admin-event.log containing administrative events.

note

While the property additive: is set to true, the log streams are also output to console. Set the property to false to only create the file output. In the example above, a simple variation could be to set the property additive: to false for the administrative events logger and to true for the evaluation events logger. This would result in the evaluation events log output both to console and as a file named ads-eval-event.log, and the administrative events log only output as a file named ads-admin-event.log.

Enabling verbose audit logging

By default, the log output for evaluation events is presented in a concise format, that is, information not essential to auditing is excluded from the evaluation events. If the full, or verbose, logging information is required, you need to provide an additional property in the deployment configuration file.

audit:
  mode: verbose
 
logging:
  level: WARN
  loggers:
    "com.axiomatics.audit": INFO
  appenders:
    - type: console
      target: stdout
      timeZone: system

Verbose logging output enabled

1. Open the deployment configuration file in a text editor.

2. Add the property audit:.

3. Add the subproperty mode: and the value verbose.

The subproperty mode: can take two values, concise and verbose, with concise being the default value.

See the section Audit log message format for output examples and more information about the logging output format.

Configuring single-line per event log output

Some of the log events in ADS may generate multi-line messages. If that is a problem, for example, if you are using a log analysis tool that requires single-line log messages, a solution is to configure the logging property to use a JSON layout. This will guarantee that every event is logged using one line.

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit":
      level: INFO
      additive: false
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-audit-event.log
          archivedLogFilenamePattern: ./logs/ads-audit-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB
  appenders:
  - type: console
    target: stdout
    timeZone: system
    # Uncomment the following lines to enable JSON layout as the default.
    # layout:
    #   type: json
    #   prettyPrint: true

JSON layout enabled for audit logging

In the example, the JSON layout is enabled solely for audit logs, which are directed to a separate log file. All other log events are sent to standard output. To enable JSON layout for all logs, uncomment the section as described.

Logging enhanced with tracing information in MDC

Log entries emitted by ADS can be enhanced with trace and span identifiers as attributes in the Mapped Diagnostic Context (MDC). However, this requires that the OpenTelemetry Java agent that ADS relies on for the tracing functionality is enabled. See Tracing for more information.

When that is the case, the OpenTelemetry Java agent will inject information about the current traces and span into the MDC copy of each logging event. Refer to the OpenTelemetry MDC documentationOpens in a new tab for more on the information injected into the MDC copy.

In the JSON logging layout, the MDC value is included by default. To exclude the MDC value, the property includes: must be used.

• Add the property includes: to the JSON layout section of the deployment configuration file and exclude mdc from the list of logging event attributes.

This will prevent the MDC value from being printed in the log output.

layout:
  type: json
  timestampFormat: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
  prettyPrint: false
  appendLineSeparator: true
  includes: [timestamp, threadName, level, loggerName, message, exception]

MDC excluded from log output (excerpt)

To include it again, add mdc back to the list of logging event attributes.

layout:
  type: json
  timestampFormat: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
  prettyPrint: false
  appendLineSeparator: true
  includes: [timestamp, threadName, level, loggerName, message, mdc, exception]

MDC included in log output (excerpt)

Refer to the Dropwizard documentation for JSON layoutOpens in a new tab for more information.