ologger Log Framework ​

Feature Introduction ​

This feature aims to design a universal, extensible log framework to uniformly support the log requirements of various community components. While providing standardized, structured basic log capabilities, the framework maintains flexible extensibility, facilitating custom adaptation by each component based on its own scenarios, achieving standardized management and personalized output of log functionality.

Application Scenarios ​

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

Capability Scope ​

Table 1 ologger Log Framework Feature Table

Highlight Features ​

• Combining standardization with extensibility: Supports structured output conforming to log specifications and user custom log levels, while simultaneously allowing runtime dynamic adjustment of log content output level, satisfying diverse log requirements.
• Security protection mechanism: Built-in log injection prevention and sensitive word filtering mechanisms, effectively defending against log forgery and information leakage risks.
• High availability of log framework: Supports dynamic rotation and real-time adjustment in special scenarios, ensuring business continuity.

Implementation Principle ​

Overall Process:

1. Import the ologger log library.
2. Write the configuration file.
3. Call the log print interface in the framework.

Relationship with Related Features ​

Each component needs to adapt to the ologger log framework.

Using the ologger Log Framework ​

Prerequisites ​

Developed components import the ologger log library.

Background Information ​

The framework provides log print interfaces and related functionalities conforming to community log specifications. If a component needs to adapt to community log specifications, it can use this framework for log-related development work.

Usage Restrictions ​

The framework only provides log-related functionalities during development. Other specification content still requires manual compliance.

Operation Steps ​

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

   go

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

2. Write the configuration file.

   The configuration file is stored by default in /etc/openFuyao/ologger/ologger.yaml. If a custom path is needed, it can be configured by modifying 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 through environment variable "OLOGGER_CONFIG"
   
   # ologger log framework configuration items
   # Log file storage path - default is /var/log/openFuyao/ologger.log
   path: /yourpath/yourfile
   # Minimum log content print level - default is INFO
   level: INFO
   # Log output format - json for JSON format, text/console for text mode
   format: json
   # Timezone - local/utc
   timezone: local
   # Whether log content includes IP
   include_ip: true
   # Log rotation - maximum size per file (MB)
   max_size_mb: max_size_num
   # Log rotation - maximum number of historical log files retained
   max_backups: max_backups_num
   # Log rotation - maximum retention days for log files
   max_age_days: max_age_num
   # Log rotation - whether to compress rotated old logs
   compress: true
   # Custom levels
   custom_levels:
     level_name: level_num
   # Custom sensitive word filtering
   sensitive_words:
     - sensitive_word
   
   # ologger log framework feature switches
   # Whether to output logs to console
   enable_console: true
   # Whether to output logs to specified file
   enable_file: true
   # Whether to enable runtime dynamic log level adjustment
   watch_level: true
   # Whether to enable sensitive word filtering
   enable_sanitize: true

   All configuration items above except custom levels (custom_levels) can be configured through environment variables, listed as follows.

   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 print interface.

   • Custom levels in the framework must be printed 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, besides the unified entry point, can also be printed through level-specific functions integrated in the framework (here using INFO level as an example).

     go

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

     Usage example is as follows.

     go

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

Next Steps ​

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

Related Operations ​

Log Framework Features ​

• Log Rotation

  The log framework configures rotation parameters and calls the lumberjack library to implement specific functionality.

  Log rotation configuration items all have reasonable configuration ranges, as follows.

  yaml

  # Log rotation - maximum size per file (MB)
  max_size_mb: 100-10240
  # Log rotation - maximum number of historical log files retained
  max_backups: 5-30
  # Log rotation - maximum retention days for log files
  max_age_days: 1-14
  # Log rotation - whether to compress rotated old logs
  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

  The watch_level configuration item determines whether to enable this feature, and the level configuration item is adjusted at runtime to adjust the minimum log output level.

  If level input is incorrect, the original configuration is not changed by default, and a warning log is printed. The default level configuration is INFO. If the first level configuration input is incorrect, level will also fall back to INFO.

  yaml

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

  Additionally, the framework provides an interface for modifying the log level for application invocation, as follows.

  go

  SetLevel(level string)

• User Custom Level

  Configure level names and levels through the custom_levels configuration item. The log framework will automatically complete registration of these levels. Example is as follows.

  yaml

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

  Default levels in the framework are as follows. When customizing levels, do not create level conflicts, otherwise original levels will be overwritten.

  yaml

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

• Log Printing

  • Print to console, configured through the enable_console configuration item.

    yaml

    # Whether to output logs to console
    enable_console: true

  • Print to file, configured through the enable_file configuration item.

    yaml

    # Whether to output logs to specified file
    enable_file: true

    Note:

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

    • If path exists, a new file will be created when the log file does not exist; otherwise, the directory and file will be automatically created.

• Printing Logs with With

  Use With to add log fields. Example is as follows.

  go

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

  Output result is as follows.

  json

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

Log Framework Security Protection ​

• Default Values of 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 switches
  enable_console: true
  enable_file: true
  watch_level: true
  enable_sanitize: true

  Configuration effective priority: Configuration file configuration > Environment variable configuration > Default values.

• File Permissions

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

  Note:

  • If the configuration file chmod execution encounters an exception, a warning log will be printed, and the configuration will completely fall back to default values (or environment variable configuration).

  • If the log file chmod execution encounters an exception, the error is ignored, logs are written normally, and program running is not affected.

• Configuration Value Exception

  warning log information is provided as follows.

  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 Mechanism

  • Default filtering of common sensitive words pwd, passwd, password, using regular expressions for matching and content cleaning.

  • Provides the sensitive word custom configuration item sensitive_words, supporting feature-specific sensitive word cleaning, which will be merged with default sensitive words for combined cleaning.

  • Sets the sensitive word filtering feature switch enable_sanitize, promptly disabling when this feature is not needed to improve log framework performance.

  • Sensitive word cleaning is case-insensitive.

    Example is as follows.

    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 closes log file writing functionality when disk is full, preventing machine restart from affecting services.

  • After log file deletion, a corresponding file should be promptly created to ensure log framework availability.

    Note:

    When restoring the log file, a log rotation will be triggered, producing an empty old log file compression package, which is expected behavior.