ologger日志框架 ​

特性介绍 ​

本特性旨在设计一个通用化、可拓展的日志框架，以统一支持社区各类组件的日志需求。在提供标准化、结构化的日志基础能力的同时，框架将保持灵活的扩展性，便于各组件根据自身场景进行定制化适配，实现日志功能的规范化管理与个性化输出。

应用场景 ​

使用ologger日志框架，完成对开发组件的规范化日志打印。

能力范围 ​

表1 ologger日志框架功能表

亮点特征 ​

• 兼备标准化与可拓展性：支持符合日志规范的结构化输出、用户自定义日志级别，同时允许用户运行时动态调整日志内容输出级别， 满足多样化日志需求。
• 提供安全防护机制：内置日志防注入与敏感词过滤机制，有效防御日志伪造与信息泄露风险。
• 日志框架高可用：支持动态轮转与特殊场景实时调整，确保业务连续性。

实现原理 ​

总体流程：

1. 引用ologger日志库。
2. 编写配置文件。
3. 调用框架中日志打印接口。

与相关特性的关系 ​

各组件需适配ologger日志框架。

使用ologger日志框架 ​

前提条件 ​

开发组件引用ologger日志库。

背景信息 ​

框架提供符合社区日志规范的日志打印接口及相关各项功能，若组件需适配社区日志规范，可采用本框架进行日志相关开发工作。

使用限制 ​

框架仅提供开发过程中日志相关功能，其他规范涉及内容仍需人为遵守。

操作步骤 ​

1. 执行如下命令，引用ologger日志库。

   go

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

2. 编写配置文件。

   配置文件默认存放于/etc/openFuyao/ologger/ologger.yaml中，若需要自定义路径，可以通过修改环境变量OLOGGER_CONFIG来进行配置。

   bash

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

   配置文件模板如下。

   yaml

   # ologger 日志框架配置文件模板，复制此文件并填写实际值
   # 通过环境变量"OLOGGER_CONFIG"刷新日志框架配置项
   
   # ologger日志框架配置项
   # 日志文件存储路径 - 默认为 /var/log/openFuyao/ologger.log
   path: /yourpath/yourfile
   # 日志内容打印最低级别 - 默认为 INFO
   level: INFO
   # 日志输出格式 - json-json格式，text/console-文本模式
   format: json
   # 时区 - local/utc
   timezone: local
   # 日志内容是否包含 IP
   include_ip: true
   # 日志轮转 - 单个文件最大大小（MB）
   max_size_mb: max_size_num
   # 日志轮转 - 保留的历史日志文件数量上限
   max_backups: max_backups_num
   # 日志轮转 - 日志文件的最大保留天数
   max_age_days: max_age_num
   # 日志轮转 - 轮转后的旧日志是否压缩
   compress: true
   # 自定义级别
   custom_levels:
     level_name: level_num
   # 自定义清洗敏感词
   sensitive_words:
     - sensitive_word
   
   # ologger日志框架功能开关
   # 日志是否输出至控制台
   enable_console: true
   # 日志是否输出至指定文件
   enable_file: true
   # 是否开启运行时动态调整日志级别
   watch_level: true
   # 是否开启敏感词清洗
   enable_sanitize: true

   上述配置项除自定义级别（custom_levels）外，均可以通过环境变量方式进行配置，列举如下。

   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. 调用日志打印接口。

   • 框架中自定义级别需通过统一入口打印日志。

     go

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

   • 框架中默认级别除统一入口外，还可以通过框架中集成的各级别特有的函数打印日志内容（此处以INFO级别为例）。

     go

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

     使用示例如下。

     go

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

后续操作 ​

可采用日志分析工具，对格式化日志内容进行分析。

相关操作 ​

日志框架功能 ​

• 日志轮转

  日志框架配置轮转参数，并调用lumberjack库实现具体功能。

  日志轮转配置项均有合理配置范围，具体如下。

  yaml

  # 日志轮转-单个文件最大大小（MB）
  max_size_mb: 100-10240
  # 日志轮转-保留的历史日志文件数量上限
  max_backups: 5-30
  # 日志轮转-日志文件的最大保留天数
  max_age_days: 1-14
  # 日志轮转-轮转后的旧日志是否压缩
  compress: true/false

  说明：

  若compress设定为true，每一个旧日志文件都会被压缩成.gz文件，以减少磁盘空间占用。

• 运行时调整级别

  通过watch_level配置项决定是否开启此功能，并在运行时通过调整level配置项来调整日志输出最低级别。

  如果level输入错误，默认不改变原配置，并打印warning日志；level默认配置为INFO级别，若首次配置level输入错误，level也会回退到INFO级别。

  yaml

  # 日志输出最低级别-默认为INFO
  level: INFO
  # 是否开启运行时动态调整日志级别
  watch_level: true

  同时，框架提供修改日志level的接口，供应用程序调用，接口如下。

  go

  SetLevel(level string)

• 用户自定义级别

  通过custom_levels配置项配置级别名称和等级，日志框架将自动完成对这些级别的注册，示例如下。

  yaml

  # 自定义级别
  custom_levels:
    HINT: 1
    NIL: -9
    Fatal: 16

  框架中默认级别如下，在自定义级别时不要发生等级冲突，否则会覆盖原级别。

  yaml

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

• 日志打印

  • 打印至控制台，通过enable_console配置项配置。

    yaml

    # 日志是否输出至控制台
    enable_console: true

  • 打印至文件，通过enable_file配置项配置。

    yaml

    # 日志是否输出至指定文件
    enable_file: true

    说明：

    • 若开启打印至文件，但path为空，则回退至默认配置，输出至/var/log/openFuyao/ologger.log文件中。

    • 若path存在，则在日志文件不存在时会新建文件，否则自动创建目录和文件。

• 通过With打印日志

  使用With添加日志字段，示例如下。

  go

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

  输出结果如下。

  json

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

日志框架安全防护 ​

• 日志框架各配置项默认值

  yaml

  # ologger日志框架配置项
  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日志框架功能开关
  enable_console: true
  enable_file: true
  watch_level: true
  enable_sanitize: true

  配置生效级别：配置文件配置 > 环境变量配置 > 默认值。

• 文件权限

  配置文件权限为644，日志文件权限也为644，新建日志文件目录权限为755。

  说明：

  • 若配置文件chmod执行异常，则会打印一条warning日志，配置将完全回退至默认值（或环境变量配置）。

  • 若日志文件chmod执行异常，错误将被忽略，日志正常写入，不影响程序运行。

• 配置项值异常

  提供warning日志信息如下。

  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"}

• 敏感词过滤机制

  • 默认过滤常见敏感词pwd、passwd、password，采用正则表达式进行匹配和内容清洗。

  • 提供敏感词自定义配置项sensitive_words，支持特性敏感词清洗，会与默认敏感词合并后一同清洗。

  • 设置敏感词过滤功能开关enable_sanitize，在不需要该功能时及时关闭，提高日志框架性能。

  • 敏感词清洗大小写不敏感。

    示例如下。

    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":"******"}

• 其他注意事项

  • 在磁盘满的场景下自动关闭日志写入文件功能，防止机器重启影响业务。

  • 日志文件删除后，应及时新建对应文件，保证日志框架可用性。

    说明：

    恢复日志文件时，会触发一次日志轮转产生空的旧日志文件压缩包，属于预期行为。