Skip to main content
Version: 2.x (upcoming)

Logging and auditing

OpenCDMP's backend services share one logging setup built on Logback (SLF4J). Each service writes two files: a troubleshooting log, logging.log, for diagnostics, and an audit log, auditing.log, with one line per audited API call. The two share a request id, so the audit line of a call and the troubleshooting lines it produced can be matched.

  • Running an installation? Logging and monitoring explains where each service writes its logs, how to change the log levels, the format of both files, how to follow a request through them, and the health and metrics endpoints.
  • Looking up an audit event? The audit event reference lists every event the API service records, with its id and trigger.

Writing log entries​

These conventions apply to code that runs in the OpenCDMP services or in a plugin built on the same libraries.

Application code uses the LoggerService wrapper (from gr.cite.tools.logging) around a standard SLF4J logger. The following levels are used:

LevelWhen used
DEBUGEntry into a service method or controller action, with the entity type, id, and requested fields. Not written by default: OpenCDMP's own code (org.opencdmp) logs at INFO unless an operator raises it.
INFONotable events, such as startup, migrations, and the summaries of background tasks.
WARNUnexpected but recoverable conditions.
ERRORUnhandled exceptions and critical failures.

LOGGING_DEFAULT_LOG_LEVEL sets the level of the framework loggers only; see Log levels.

Structured log entries are produced using MapLogEntry to attach key-value context:

// Simple string message
logger.debug("querying {}", Plan.class.getSimpleName());

// Structured entry with key-value pairs
logger.debug(new MapLogEntry("retrieving " + Plan.class.getSimpleName())
    .And("id", id)
    .And("fields", fieldSet));

Do not log secrets or whole request bodies at any level: deposit requests carry decrypted credentials, and plans carry personal data.

Audit event reference​

Controllers record an audit event at the end of each successful call. The events, their ids, and how they are recorded are listed in Audit events.

See also​