Logging

UDMG provides flexible logging capabilities that enable System Administrators to monitor system activity, troubleshoot issues, and audit operations.

This page explains how to configure logging, interpret log entries, and enable advanced features like log rotation.

info

All HCL arguments described on this page use dot notation to reference their full path from the root of the configuration file.

Logging Configuration

By default, UDMG writes logs to standard output and to a file named udmg-server.log. Logs can be formatted as plain text or JSON, recorded at different verbosity levels, and rotated to control file size and retention.

Logging settings in UDMG are configured in the Configuration File under the log block. They can also be overridden at runtime using Environment Variables.

tip

Environment variables take precedence over HCL arguments when both are provided. It is generally recommended to configure settings in HCL files to maintain clarity, consistency, and ease of management.

Use environment variable overrides sparingly (typically for temporary adjustments, containerized deployments, or sensitive values such as passwords and secrets).

Level

The log.level argument defines the verbosity of logging output.

Level	Description
ERROR	Error messages only.
WARN	Warning and error messages.
INFO (default value)	Informational, warning, and error messages.
DEBUG	All messages (ERROR, WARN, INFO, and DEBUG).

Format

The log.format argument specifies how log entries are structured, either for human readability or for automated processing by external tools.

Format	Description
plain (default value)	Human-readable text with key-value pairs. Suitable for direct inspection in files or the console.
json	Structured JSON output. Useful for parsing, log aggregation systems, and automated analysis.

File

The log.file argument defines the destination file for UDMG log entries. By default, logs are written to udmg-server.log in the current working directory, but you can specify an absolute path to store logs in a custom location (e.g., /var/opt/udmg/udmg-server.log).

Rotation

UDMG supports log rotation to control log file size, prevent disk space issues, and maintain system performance.

Rotation is configured under the log.rotate block and can be turned on or off using the log.rotate.enable argument. When enabled, UDMG always applies time-based rotation (daily by default). You can also configure an optional size threshold.

When a rotation condition is met, UDMG closes the current log file (as defined by log.file) and renames it according to the rotate.file_format pattern.

info

Old rotated log files are not automatically deleted by UDMG and must be managed externally.

Rotation Methods

UDMG supports two types of log rotation: time-based and size-based. Rotation is triggered when the first configured condition is met.

Time-Based Rotation

Time-based rotation is always active when log rotation is enabled.

The log file is rotated at fixed intervals according to the selected frequency option, and may also rotate earlier if the size limit is reached before.

Option	Rotation Time
daily (default)	Every day at 00:00:00
weekly	Every Sunday at 00:00:00
monthly	First day of each month at 00:00:00
quarterly	First day of each quarter year at 00:00:00

Size-Based Rotation

The rotate.size argument sets a maximum log file size (in MiB). At each rotation interval (every 60 minutes), UDMG checks the file size. If the file exceeds the configured limit, it is rotated. The file may temporarily grow larger than the limit between checks.

By default, rotate.size is set to 0, which disables size-based rotation.

File Format

When a rotation condition is met, UDMG renames the current log file (defined by the log.file argument) and creates a new active log file. The rotated file name is generated using the pattern specified in rotate.file_format.

This pattern may include both time-based placeholders and directory structures, allowing rotated logs to be organized into folders by date or host.

Variable	Description	Example
{YYYY}	Four-digit year	2025
{MM}	Two-digit month	05
{DD}	Two-digit day	22
{HH}	Hour (24 hr)	13
{mm}	Minute	07
{ss}	Second	45
{ns}	Nanoseconds	123456789

Configuration Example

The configuration below uses JSON formatting, enables daily rotation, and applies an additional size-based threshold. Rotated files are archived in a date-based directory structure, with the filename including the server hostname and timestamp.

/opt/udmg/etc/udmg-server.hcl

# Logging Configuration Example
log {
    level = "INFO"
    format = "json"
    # Active log file path (includes hostname)
    file = "/var/opt/udmg/udmg-server-${env("HOSTNAME", "default")}.log"  
    
    rotate {
        # Enable log rotation
        enable = true                            
        # Rotate logs daily (at 00:00)
        frequency = "daily"                      
        # Rotate if file exceeds 100 MiB
        size = 100                               
        # Naming pattern for rotated log files
        file_format = "/var/opt/udmg/archive/{YYYY}/{MM}/{DD}/udmg-server-${env("HOSTNAME", "default")}-{HH}-{mm}-{ss}-{ns}.log"                                                  
    }
  }

# Resulting Directory Structure
└── var/
    └── opt/
        └── udmg/
            ├── udmg-server-node1.log
            └── archive/
                └── 2025/
                    └── 09/
                        └── 08/
                            └── udmg-server-node1-13-14-00-000981528.log

info

The hostname placeholder allows you to easily keep or collect files from multiple UDMG Server instances in a common location.

Log Entries

UDMG log entries capture both system activity and API interactions. Each entry includes metadata for traceability and is written in either plain text or JSON format, depending on your configuration.

File Organization

Every log entry is enriched with contextual metadata to make troubleshooting and auditing easier. Common identifiers include:

• Request ID: unique identifier for each API request.
• Session UUID / Transfer ID: identifiers for data transfers.

Messages

Log messages are generated by the UDMG REST, providing a complete picture of system activity, including:

• Details for incoming API requests.
• Results of API request processing.
• Scheduled or other operations.
• File transfer actions.

Message Examples

Plain Text

time=2025-05-30T13:22:52.364+03:00 level=INFO msg="domain config retrieve" service=api api.requestId=66e263e5-d416-4c90-ac4e-1c5647422e5d api.domainUUID=4caef316-fa27-4f4a-8b23-23ff4ab7326a api.domainName=primary api.userUUID=0fae92b1-8147-4a4d-a1d4-86d5254eace0 api.userName=udmg.sys-admin api.message="domain configuration get all"

JSON Format

{
  "time":"2025-05-30T13:27:06.175248205+03:00",
  "level":"INFO",
  "msg":"domain config retrieve",
  "service":"api",
  "api": {
    "requestId":"65776665-9726-4988-a9c2-5320d536a798","domainUUID":"4caef316-fa27-4f4a-8b23-23ff4ab7326a",
    "domainName":"primary",
    "userUUID":"0fae92b1-8147-4a4d-a1d4-86d5254eace0",
    "userName":"udmg.sys-admin",
    "message":"domain configuration get all"
    }
}

Log Message Codes

UDMG standardizes HTTP response messages with unique codes for consistency across logs and troubleshooting.

HTTP Status Code	Message Code	Message
200	UDMGxAPI200	Ok
201	UDMGxAPI201	Created
202	UDMGxAPI202	Accepted
400	UDMGxAPI400	Bad Request
401	UDMGxAPI401	Unauthorized
403	UDMGxAPI403	Forbidden
404	UDMGxAPI404	Not Found
405	UDMGxAPI405	Method Not Allowed
409	UDMGxAPI409	Conflict
500	UDMGxAPI500	Internal Server Error

HCL Log Block

The table below lists the configuration arguments available in the log block:

HCL Argument Name	Description	Value Type	Default Value
log.level	Configures the log level. Options: "debug" "info" "warn" "error"	string	"info"
log.format	Format of the log output. Options: "plain" "json"	string	"plain"
log.file	Log file name. Supports environment variable expansion.	string	udmg-server.log
log.rotate.enable	Enables or disables the log rotation feature. When enabled, log files are rotated as soon as one of the configured rotation conditions is met: The defined log.rotate.frequency interval has elapsed. The log file reaches the configured log.rotate.size. Only the size-based condition can be disabled.	bool	false
log.rotate.frequency	Time interval that triggers log rotation. Rotation occurs when this interval is reached, unless rotation is disabled. Options: "daily" "weekly" "monthly" "quarterly"	string	"daily"
log.rotate.size	Maximum log file size (in megabytes) before rotation is triggered. Checked every hour.	number	5
log.rotate.file_format	Format for rotated log filenames. It can include directory structure and the following placeholders: {YYYY} (year) {MM} (month) {DD} (day) {HH} (hour) {mm} (minute) {ss} (second) {ns} (nanosecond)	string	"{YYYY}-{MM}-{DD}-{HH}-{mm}-{ss}-{ns}"