Skip to main content
Version: 3.3

Logging

USP offers configurable logging features that enable administrators to monitor each Component's behavior, diagnose issues, and maintain audit trails. Logs can be directed to standard output or log files, which can be rotated based on size or time policies.

This page explains how to configure logging for each USP Component (USP Manager, USP Server, and USP Client).

Overview​

All USP components support configurable logging. Logging is configured in the .hcl configuration file for each component:

  • usp-manager.hcl for USP Manager.
  • usp-server.hcl for USP Server.
  • usp-client.hcl for USP Client.
info

While environment variables can override values in the configuration file, we recommend defining all settings in the .hcl file to ensure clear visibility and reproducibility across environments.

Logging Configuration Fields​

log.level​

Controls the verbosity of logs.

Options (every option contains the messages from the ones below it):

  • TRACE: The most detailed logging level, used to record fine-grained information about internal operations (e.g., database queries).
  • DEBUG: Detailed internal information for troubleshooting.
  • INFO: General operational messages.
  • WARN: Unexpected errors that are not critical.
  • ERROR: Critical errors.
tip

Use INFO for normal operation and DEBUG when troubleshooting.

Type: string

Default: "INFO"

log.max_age​

Rotates logs that are older than a specified number of days.

Each Component checks the age of each log file every time a log message is written, and when the configured threshold is reached, it archives the current log as the original log file plus the time at which the log was rotated (name-timestamp.extension).

For example: if manager.log is the original log file and a rotation happens at 3:00pm on May 10th 2025, the archived file would be named: manager-2025-05-10-T15-00-00.000.log.

Type: number

Default: 0 (disabled)

log.max_backups​

Defines how many rotated log files must be kept. Once the number is exceeded, the older log file gets deleted when a new log rotation takes effect.

Type: number

Default: 0 (disabled)

log.max_size​

Rotates logs when the log file grows beyond a threshold measured (in MB).

Type: number

Default: 0 (disabled)

log.path​

The path to the log file. If no value is set, logs are written to standard output.

Type: string

Default: "" (standard output)

Configuration Example With Default Values​

log {
  level       = "info"
  path        = "/var/log/usp-server.log" # Example with USP Server
  max_age     = 3
  max_size    = 100
  max_backups = 15
}