Logging Configuration

1. Overview

The FT Device Network Service implements a comprehensive logging system to provide visibility into application behavior, aid in troubleshooting, and maintain an audit trail of important operations. The logging implementation uses Logback, which is the native logging framework for Spring Boot applications.

The logging system is designed to meet several key requirements:

  1. Operational Visibility - Provide insights into the normal operation of the service

  2. Troubleshooting - Facilitate diagnosis of issues in development and production

  3. Device-specific Logging - Maintain separate logs for each device to simplify debugging

  4. Performance Optimization - Minimize logging overhead while maximizing usefulness

  5. Log Rotation - Prevent logs from consuming excessive disk space

Logs are categorized by severity level and component, allowing for fine-grained control over what information is captured and where it is stored.

2. Configuration

The logging configuration is defined in the logback-spring.xml file, which sets up appenders, loggers, and other logging parameters:

Unresolved include directive in modules/ROOT/pages/logging.adoc - include::../src/main/resources/logback-spring.xml[]

Additional logging properties are also defined in application.yml:

logging:
  level:
    root: INFO
    com.friendly.network.wifi: INFO
    org.springframework: WARN
  pattern:
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/${spring.application.name}.log
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30

3. Log Appenders

The logging configuration defines several appenders to direct log output to appropriate destinations:

3.1. Console Appender

The standard Spring Boot console appender outputs logs to the console during development and to stdout in containerized environments:

  • Pattern: Standard Spring Boot pattern with timestamp, thread, level, logger, and message

  • Level: Determined by the logger configuration

3.2. Rolling File Appender

The RollingFile appender writes logs to a file with time-based rotation to manage disk space:

  • File: ./logs/ft-device-network-service.log

  • Pattern: ISO8601 timestamp, thread, level, logger, and message

  • Rotation: Daily with a size limit of 10MB per file

  • Retention: 30 days of history

3.3. Device-specific Sifting Appender

The DEVICE_ROLLING_FILE appender uses Logback’s sifting capability to create separate log files for each device:

  • Discriminator: deviceSerial - Determines which device log to write to

  • Default: unknown - Used when device serial is not specified

  • File: ./logs/devices/{deviceSerial}.log

  • Pattern: Same as the main rolling file appender

  • Rotation: Daily with size limit of 10MB per file

  • Retention: 10 days of history per device

4. Log Levels

The application uses different log levels for various components:

  • ROOT: INFO - Base level for all components

  • com.friendly.network.wifi: DEBUG - More detailed logging for core WiFi functionality

  • com.friendly.network.wifi.device: DEBUG - Detailed logging for device-specific operations

  • org.springframework: WARN - Only warnings and errors from the Spring framework

These levels can be adjusted at runtime through the Spring Boot Actuator logging endpoint, allowing for dynamic troubleshooting without restarting the service.

5. Device-specific Logging

A key feature of the logging system is the ability to maintain separate logs for each device, which significantly simplifies troubleshooting device-specific issues.

To log to a device-specific file, the code sets the deviceSerial Mapped Diagnostic Context (MDC) variable:

try {
    MDC.put("deviceSerial", serial);
    log.debug("Processing data from device {}", serial);
    // Device-specific operations
} finally {
    MDC.remove("deviceSerial");
}

This approach ensures that:

  1. Device-specific logs are written to dedicated files

  2. Logs can be easily filtered by device

  3. The main log file remains manageable in size

6. Logging Best Practices

The application follows these logging best practices:

6.1. Appropriate Log Levels

  • ERROR - Used for errors that prevent normal operation

  • WARN - Used for unexpected conditions that don’t prevent operation

  • INFO - Used for significant events in normal operation

  • DEBUG - Used for detailed information useful during development

  • TRACE - Used for very detailed diagnostic information

6.2. Structured Logging

Log messages use a consistent format with placeholders for variable data:

log.debug("Processing {} parameters from device {}", parameters.size(), serial);

This approach:

  1. Avoids string concatenation when logging is disabled

  2. Makes logs more consistent and readable

  3. Facilitates automated parsing and analysis

6.3. Performance Considerations

To minimize the performance impact of logging:

  1. Log level checks are performed before constructing log messages

  2. Expensive operations are only performed when the appropriate log level is enabled

  3. Structured logging avoids unnecessary string concatenation

if (log.isDebugEnabled()) {
    log.debug("Detailed stats: {}", calculateExpensiveStats());
}

6.4. Security Considerations

The logging system follows these security practices:

  1. Sensitive data (passwords, tokens, personal information) is never logged

  2. Log files are protected with appropriate file system permissions

  3. Log rotation prevents log files from growing indefinitely

← Back | Main Page