ologger Log Framework ​

Feature Introduction ​

This feature is designed to create a general-purpose, extensible log framework to uniformly support the logging needs of various components in the community. While providing standardized and structured basic logging capabilities, the framework maintains flexible extensibility to allow each component to customize it for its own scenarios, enabling standardized log management and personalized output.

Application Scenarios ​

Use the ologger log framework to implement standardized log printing for developed components.

Capability Scope ​

Table 1 ologger Log Framework Features

Key Features ​

• Standardization with Extensibility: Supports structured output compliant with logging specifications, user-defined log levels, and dynamic runtime adjustment of log output levels to meet diverse logging needs.
• Security Protection Mechanisms: Built-in log injection prevention and sensitive word filtering mechanisms effectively defend against log forgery and information leakage risks.
• High Availability: Supports dynamic rotation and real-time adjustment for special scenarios, ensuring business continuity.

Implementation Principle ​

Overall Process:

1. Reference the ologger log library.
2. Write the configuration file.
3. Call the log printing interface in the framework.

Relationship with Related Features ​

Each component needs to adapt to the ologger log framework.

Using the ologger Log Framework ​

Prerequisites ​

The developed component references the ologger log library.

Background Information ​

The framework provides log printing interfaces and related features that comply with the community logging specification. If a component needs to comply with the community logging specification, this framework can be used for log-related development.

Usage Restrictions ​

The framework only provides log-related features during development. Other specification-related content still needs to be followed manually.

Procedure ​

1. Run the following command to reference the ologger log library.

   go

   import "gitcode.com/openFuyao/common-modules/ologger"

2. Write the configuration file.

   The configuration file is stored by default at /etc/openFuyao/ologger/ologger.yaml. To customize the path, set the environment variable OLOGGER_CONFIG.

   bash

   export OLOGGER_CONFIG="/etc/openFuyao/ologger/config.yaml"

   The configuration file template is as follows.

   yaml

   # ologger log framework configuration file template - copy this file and fill in actual values
   # Refresh log framework configuration items via the environment variable "OLOGGER_CONFIG"
   
   # ologger log framework configuration items
   # Log file storage path - default: /var/log/openFuyao/ologger.log
   path: /yourpath/yourfile
   # Minimum log output level - default: INFO
   level: INFO
   # Log output format - json: JSON format, text/console: text mode
   format: json
   # Timezone - local/utc
   timezone: local
   # Whether log content includes IP
   include_ip: true
   # Log rotation - maximum size of a single file (MB)
   max_size_mb: max_size_num
   # Log rotation - maximum number of historical log files to retain
   max_backups: max_backups_num
   # Log rotation - maximum number of days to retain log files
   max_age_days: max_age_num
   # Log rotation - whether to compress old logs after rotation
   compress: true
   # Custom levels
   custom_levels:
     level_name: level_num
   # Custom sensitive word filtering
   sensitive_words:
     - sensitive_word
   
   # ologger log framework feature toggles
   # Whether to output logs to the console
   enable_console: true
   # Whether to output logs to the specified file
   enable_file: true
   # Whether to enable dynamic log level adjustment at runtime
   watch_level: true
   # Whether to enable sensitive word filtering
   enable_sanitize: true

   All configuration items above (except custom levels custom_levels) can also be configured via environment variables, as listed below.

   bash

   export OLOGGER_PATH="/var/log/openFuyao/xxx.log"
   export OLOGGER_LEVEL="INFO"
   export OLOGGER_FORMAT="json"
   export OLOGGER_TZ="utc"
   export OLOGGER_INCLUDE_IP="true"
   export OLOGGER_MAX_SIZE_MB="100"
   export OLOGGER_MAX_BACKUPS="5"
   export OLOGGER_MAX_AGE_DAYS="1"
   export OLOGGER_COMPRESS="true"
   export OLOGGER_SENSITIVE_WORDS="secret,token"
   
   export OLOGGER_CONSOLE="true"
   export OLOGGER_ENABLE_FILE="true"
   export OLOGGER_WATCH_LEVEL="true"
   export OLOGGER_ENABLE_SANITIZE="true"

3. Call the log printing interface.

   • Custom levels in the framework must print logs through the unified entry point.

     go

     log.Log(levelName string, msg string, args ...any)
     
     log.Logf(levelName string, template string, args ...any)

   • Default levels in the framework can also use level-specific functions integrated into the framework in addition to the unified entry point (using INFO level as an example).

     go

     log.Info(msg string, args ...any)
     
     log.Infof(template string, args ...any)

     Example usage:

     go

     log.Info("This is msg!", "key", "value")

Follow-up Operations ​

Log analysis tools can be used to analyze the formatted log content.

Related Operations ​

Log Framework Features ​

• Log Rotation

  The log framework configures rotation parameters and uses the lumberjack library to implement the feature.

  Log rotation configuration items all have a reasonable configuration range, as follows.

  yaml

  # Log rotation - maximum size of a single file (MB)
  max_size_mb: 100-10240
  # Log rotation - maximum number of historical log files to retain
  max_backups: 5-30
  # Log rotation - maximum number of days to retain log files
  max_age_days: 1-14
  # Log rotation - whether to compress old logs after rotation
  compress: true/false

  Note:

  If compress is set to true, each old log file will be compressed into a .gz file to reduce disk space usage.

• Runtime Level Adjustment

  Use the watch_level configuration item to decide whether to enable this feature, and adjust the minimum log output level at runtime by modifying the level configuration item.

  If an invalid level is entered, the original configuration is kept unchanged by default and a warning log is printed. The default level is INFO; if an invalid level is entered during the first configuration, level will also fall back to INFO.

  yaml

  # Minimum log output level - default: INFO
  level: INFO
  # Whether to enable dynamic log level adjustment at runtime
  watch_level: true

  The framework also provides an interface for modifying the log level for applications to call:

  go

  SetLevel(level string)

• User-Defined Levels

  Configure the level name and numeric value using the custom_levels configuration item. The log framework will automatically register these levels. Example:

  yaml

  # Custom levels
  custom_levels:
    HINT: 1
    NIL: -9
    Fatal: 16

  The default levels in the framework are as follows. When defining custom levels, avoid level conflicts as they will overwrite existing levels.

  yaml

  TRACE      →     -8
  DEBUG      →     -4
  INFO       →      0
  WARNING    →      4
  ERROR      →      8
  CRITICAL   →      12

• Log Printing

  • Print to console, configured via enable_console.

    yaml

    # Whether to output logs to the console
    enable_console: true

  • Print to file, configured via enable_file.

    yaml

    # Whether to output logs to the specified file
    enable_file: true

    Note:

    • If file printing is enabled but path is empty, the configuration falls back to the default and logs are written to /var/log/openFuyao/ologger.log.

    • If path exists, a new file is created if the log file does not exist; otherwise, the directory and file are created automatically.

• Logging with With

  Use With to add log fields. Example:

  go

  log.With("with_key", "with_value").Info("msg")

  Output:

  json

  {xxx,"msg":"msg",xxx,"with_key":"with_value"}

Log Framework Security ​

• Default Values for Log Framework Configuration Items

  yaml

  # ologger log framework configuration items
  path: /var/log/openFuyao/ologger.log
  level: INFO
  format: json
  timezone: local
  include_ip: true
  max_size_mb: 100
  max_backups: 30
  max_age_days: 14
  compress: true
  custom_levels: {}
  sensitive_words: []
  
  # ologger log framework feature toggles
  enable_console: true
  enable_file: true
  watch_level: true
  enable_sanitize: true

  Configuration precedence: configuration file > environment variable > default value.

• File Permissions

  Configuration file permissions are set to 644, log file permissions are also 644, and newly created log file directory permissions are 755.

  Note:

  • If chmod execution fails for the configuration file, a warning log is printed and the configuration fully falls back to the default value (or environment variable configuration).

  • If chmod execution fails for the log file, the error is ignored and logs are written normally without affecting program execution.

• Abnormal Configuration Values

  The following warning log information is provided:

  json

  {"time":"2026-02-03T15:12:03+08:00","level":"WARNING","source":{"function":"doSlow","file":"C:/Program Files/Go/src/sync/once.go","line":78},"msg":"ologger config invalid, using default value","pid":104256,"ip":"192.168.105.9","item":"format","default":"json"}

• Sensitive Word Filtering

  • By default, common sensitive words pwd, passwd, and password are filtered using regular expression matching and content sanitization.

  • Provides the sensitive_words custom configuration item to support filtering of specific sensitive words, which are merged with the default sensitive words for sanitization.

  • Sets the sensitive word filtering toggle enable_sanitize to disable the feature when not needed, improving log framework performance.

  • Sensitive word filtering is case-insensitive.

    Example:

    json

    {"time":"2026-02-02T19:45:42+08:00","level":"INFO","source":{"function":"main","file":"main.go","line":48},"msg":"the PassWord=****** is correct","pid":136360,"ip":"192.168.105.9","Secret":"******"}

• Other Notes

  • Automatically disables log file writing when disk is full, preventing machine restarts from affecting services.

  • When a log file is deleted, a new file should be created promptly to ensure log framework availability.

    Note:

    When recovering a log file, a log rotation event is triggered and an empty old log file compressed package is generated. This is expected behavior.