rotatefile

README

rotatefile

支持：全默认配置接入、按天滚动、按大小滚动、过期删除、日志总大小控制、磁盘空余控制、日志锁定（防止并发写日志）

rotatefile a Go package for writing logs to rolling files.

package rotatefile provides a rolling rotatefile.File.

rotatefile is intended to be one part of a logging infrastructure. It is not an all-in-one solution, but instead is a pluggable component at the bottom of the logging stack that simply controls the files to which logs are written.

rotatefile plays well with any logging package that can write to an io.Writer, including the standard library's log package.

rotatefile assumes that only one process is writing to the output files. Using the same rotatefile configuration from multiple processes on the same machine will result in improper behavior.

Example

To use rotatefile with the standard library's log package, just pass it into the SetOutput function when your application starts.

Code:

package main

import (
	"log"

	"github.com/bingoohuang/rotatefile"
)

func init() {
	log.SetOutput(rotatefile.NewFile(
		// rotatefile.WithFilename("/var/log/myapp/foo.log"), // 指定日志文件完整路径, 默认值见 Config.Filename 说明
		// rotatefile.WithMaxSize(100*1024),      // 单个日志文件最大大小，默认 100M
		// rotatefile.WithMaxDays(30),            // 最多保留天数，默认值30
		// rotatefile.WithTotalSizeCap(1024*1024*1024), // 最大总大小，默认 1G
		// rotatefile.WithMinDiskFree(300*1024),  // 最少磁盘空余，默认 100M
		// 以上默认值，还可以通过环境变量设置，参照环境变量说明
	))
}

环境变量

序号	变量名	默认值	含义
1	LOG_APPNAME	filepath.Base(os.Args[0])	日志基础文件名
2	LOG_FILENAME	见下面 Config.Filename 说明	日志文件完整路径
3	LOG_ROTATE_SIGNALS	SIGHUP	强制当前日志滚动信号
4	LOG_MAX_SIZE	100M	单个日志文件最大大小
5	LOG_MAX_DAYS	30	最多保留天数
6	LOG_MAX_BACKUPS	0	最大历史文件个数
7	LOG_TOTAL_SIZE_CAP	1G	最大总大小
8	LOG_MIN_DISK_FREE	100M	最少磁盘空余
9	LOG_UTCTIME	0	是否使用 UTC 时间
10	LOG_COMPRESS	1	是否启用gzip 压缩历史文件
11	LOG_PRINT_TERM	根据进程是否有终端	同时在终端打印

type rotatefile.Config

type Config struct {
    // Filename is the file to write logs to. Backup log files will be retained
    // in the same directory.  
    // 如果设置为空，则自动按顺序在以下目录中写入（找到第一个可用目录为止)，具体位置可以见 $TMPDIR/{pid}.logfile 文件
    // 1. $HOME/log/{appName}/{appName}_{appWorkDirBase}.log
    // 2. $PWD/log/{appName}_{appWorkDirBase}.log
    // 3. /var/log/apps/{appName}/{appName}_{appWorkDirBase}.log
    // 4. $TMPDIR/{appName}/{appName}_{appWorkDirBase}.log
    Filename string `json:"filename" yaml:"filename"`

    // MaxSize is the maximum size of the log file before it gets
    // rotated. It defaults to 100 megabytes.
    MaxSize int `json:"maxSize" yaml:"maxSize"`

    // MaxDays is the maximum number of days to retain old log files based on the
    // timestamp encoded in their filename.  Note that a day is defined as 24
    // hours and may not exactly correspond to calendar days due to daylight
    // savings, leap seconds, etc. The default is not to remove old log files
    // based on age.
    MaxDays int `json:"maxDays" yaml:"maxDays"`

	
    // MaxBackups is the maximum number of old log files to retain.  The default
    // is to retain all old log files (though MaxDays may still cause them to get
    // deleted.)
    MaxBackups int `json:"maxBackups" yaml:"maxBackups"`

	// TotalSizeCap 控制所有文件累积总大小
	// 如果超过该大小，则从最早的文件开始删除，直到删除到当前文件为止
	// 当前日志文件大小可以超过 TotalSizeCap
	// 0 不控制
	TotalSizeCap int64 `json:"totalSizeCap" yaml:"totalSizeCap"`

    // UtcTime determines if the time used for formatting the timestamps in
    // backup files is the computer's local time. The default is to use local time.
    UtcTime bool `json:"utcTime" yaml:"utcTime"`

    // Compress determines if the rotated log files should be compressed
    // using gzip. The default is not to perform compression.
    Compress bool `json:"compress" yaml:"compress"`
   
    // contains filtered or unexported fields
}

rotatefile.File is an io.WriteCloser that writes to the specified filename.

rotatefile.File opens or creates the logfile on first Write. If the file exists and is less than MaxSize megabytes, rotatefile will open and append to that file. If the file exists and its size is >= MaxSize megabytes, the file is renamed by putting the current time in a timestamp in the name immediately before the file's extension (or the end of the filename if there's no extension). A new log file is then created using original filename.

Whenever a write would cause the current log file exceed MaxSize megabytes, the current file is closed, renamed, and a new log file created with the original name. Thus, the filename you give rotatefile.File is always the "current" log file.

Backups use the log file name given to rotatefile.File, in the form name.timestamp.ext where name is the filename without the extension, timestamp is the time at which the log was rotated formatted with the time.Time format of 20060102T150405.000 and the extension is the original extension. For example, if your rotatefile.File.Filename is /var/log/foo/server.log, a backup created at 6:30pm on Nov 11 2016 would use the filename /var/log/foo/server.20161104T183000.000.log

Cleaning Up Old Log Files

Whenever a new logfile gets created, old log files may be deleted. The most recent files according to the encoded timestamp will be retained, up to a number equal to MaxBackups (or all of them if MaxBackups is 0). Any files with an encoded timestamp older than MaxDays days are deleted, regardless of MaxBackups. Note that the time encoded in the timestamp is the rotation time, which may differ from the last time that file was written to.

If MaxBackups and MaxDays are both 0, no old log files will be deleted.

Documentation

Overview

Package rotatefile provides a rolling logger.

rotatefile is intended to be one part of a logging infrastructure. It is not an all-in-one solution, but instead is a pluggable component at the bottom of the logging stack that simply controls the files to which logs are written.

rotatefile plays well with any logging package that can write to an io.Writer, including the standard library's log package.

rotatefile assumes that only one process is writing to the output files. Using the same rotatefile configuration from multiple processes on the same machine will result in improper behavior.

Example

To use rotatefile with the standard library's log package, just pass it into the SetOutput function when your application starts.

log.SetOutput(New())

Index

• Constants
• Variables
• func Debugf(format string, a ...interface{})
• func Env(envName, defaultValue string) string
• func EnvBool(envName string, defaultValue bool) bool
• func EnvInt(envName string, defaultValue int) int
• func EnvSignals(envName string, defaultValue []os.Signal) []os.Signal
• func EnvSize(envName string, defaultValue uint64) uint64
• func FindLogDir(appName, logDir string) string
• func GenerateFilename(appName, prefix, filename string, tryLock bool) (string, *flock.Flock)
• func GetFilename() string
• func HomeDir() (string, error)
• func IsDirWritable(dir string) bool
• func MkdirAll(dir string, mod os.FileMode) error
• func ParseBytes(s string) (uint64, error)
• type Config
• type ConfigFn
  • func WithAppName(v string) ConfigFn
  • func WithCompress(v bool) ConfigFn
  • func WithConfig(v Config) ConfigFn
  • func WithFilename(v string) ConfigFn
  • func WithMaxBackups(v int) ConfigFn
  • func WithMaxDays(v int) ConfigFn
  • func WithMaxSize(v uint64) ConfigFn
  • func WithMinDiskFree(v uint64) ConfigFn
  • func WithPrefix(v string) ConfigFn
  • func WithPrintTerm(v bool) ConfigFn
  • func WithRotateSignals(v ...os.Signal) ConfigFn
  • func WithTotalSizeCap(v uint64) ConfigFn
  • func WithUtcTime(v bool) ConfigFn
• type RotateFile
  • func New(fns ...ConfigFn) RotateFile

Examples

• Package

Constants

const (

	// Byte 1个字节
	Byte = 1 << (iota * 10)
	KiByte
	MiByte
	GiByte
	TiByte
	PiByte
	EiByte

	IByte = 1
	KByte = IByte * 1000
	MByte = KByte * 1000
	GByte = MByte * 1000
	TByte = GByte * 1000
	PByte = TByte * 1000
	EByte = PByte * 1000
)

const (
	// MB is mega
	MB = 1024 * 1024
	// GB is giga
	GB = 1024 * MB
)

const DAY = 24 * time.Hour

Variables

var ErrMismatched = errors.New("mismatched extension/prefix/backup time format")

ErrMismatched defines the error type for mismatched time format.

var IsTerminal = term.IsTerminal(1)

IsTerminal tell is if it is on a terminal.

Functions

func Debugf

func Debugf(format string, a ...interface{})

Debugf print debug info.

func Env

func Env(envName, defaultValue string) string

Env 解析环境变量设置的 string 类型变量

func EnvBool

func EnvBool(envName string, defaultValue bool) bool

EnvBool 解析环境变量设置的 bool 类型变量

func EnvInt

func EnvInt(envName string, defaultValue int) int

EnvInt 解析环境变量设置的 int 类型变量

func EnvSignals

func EnvSignals(envName string, defaultValue []os.Signal) []os.Signal

EnvSignals 解析环境变量设置的信号

func EnvSize

func EnvSize(envName string, defaultValue uint64) uint64

EnvSize 解析环境变量设置的字节大小类型的变量

func FindLogDir

func FindLogDir(appName, logDir string) string

FindLogDir 寻找日志合理的写入目录 0. 配置指定目录 /var/log/xxx/ 1. $HOME/log/{appName}/{appName}_{appWorkDirBase}.log 2. $PWD/log/{appName}_{appWorkDirBase}.log 3. /var/log/apps/{appName}/{appName}_{appWorkDirBase}.log 4. $TMPDIR/{appName}/{appName}_{appWorkDirBase}.log

func GenerateFilename

func GenerateFilename(appName, prefix, filename string, tryLock bool) (string, *flock.Flock)

GenerateFilename 根据 filename 生成完整的 1. filename 为 /some/path/xxx.log, 则继续保持 2. filename 为 /some/path/, 则补齐日志文件名为: {appName}{currentDirBase}.log 3. filename 为 空, 则根据 FindLogDir 生成指定的日志目录，日志文件名见上

func GetFilename

func GetFilename() string

GetFilename 获得当前进程的日志文件路径

func HomeDir

func HomeDir() (string, error)

HomeDir 返回当前用户的主目录 注意：有可能有的Linux用户没有主目录，此时，日志文件可能需要产生在 /var/log 目录下

func IsDirWritable

func IsDirWritable(dir string) bool

IsDirWritable 测试目录是否可写

func MkdirAll

func MkdirAll(dir string, mod os.FileMode) error

MkdirAll mkdir all.

func ParseBytes

func ParseBytes(s string) (uint64, error)

ParseBytes parses a string representation of bytes into the number of bytes it represents.

See Also: Bytes, IBytes.

ParseBytes("42 MB") -> 42000000, nil ParseBytes("42 mib") -> 44040192, nil

Types

type Config

type Config struct {
	// AppName 定义日志文件的基础文件名，默认  filepath.Base(os.Args[0])
	AppName string `json:"appName" yaml:"appName"`
	// Filename is the file to write logs to.  Backup log files will be retained
	// in the same directory.  It uses <processname>.log in os.TempDir() if empty.
	Filename string `json:"filename" yaml:"filename"`
	// Prefix 是日志基本文件名前缀，在 Filename 不指定的情况下，可以使用本字段给自动生成的日志文件名添加此前缀
	Prefix string `json:"prefix" yaml:"prefix"`

	// RotateSignals 设置滚动日志的信号
	RotateSignals []os.Signal `json:"-" yaml:"-"`

	// MaxSize is the maximum size of the log file before it gets
	// rotated. It defaults to 100 megabytes.
	MaxSize uint64 `json:"maxSize" yaml:"maxSize"`

	// MaxDays is the maximum number of days to retain old log files based on the
	// timestamp encoded in their filename.  Note that a day is defined as 24
	// hours and may not exactly correspond to calendar days due to daylight
	// savings, leap seconds, etc. The default is not to remove old log files
	// based on age.
	MaxDays int `json:"maxDays" yaml:"maxDays"`

	// MaxBackups is the maximum number of old log files to retain.  The default
	// is to retain all old log files (though MaxDays may still cause them to get
	// deleted.)
	MaxBackups int `json:"maxBackups" yaml:"maxBackups"`

	// TotalSizeCap 控制所有文件累积总大小
	// 如果超过该大小，则从最早的文件开始删除，直到删除到当前文件为止
	// 当前日志文件大小可以超过 TotalSizeCap
	// 0 不控制
	TotalSizeCap uint64 `json:"totalSizeCap" yaml:"totalSizeCap"`

	// MinDiskFree 日志文件所在磁盘分区最少空余
	MinDiskFree uint64 `json:"minDiskFree" yaml:"minDiskFree"`

	// UtcTime determines if the time used for formatting the timestamps in
	// backup files is the computer's local time.  The default is to use UTC
	// time.
	UtcTime bool `json:"utcTime" yaml:"utcTime"`

	// Compress determines if the rotated log files should be compressed
	// using gzip. The default is not to perform compression.
	Compress bool `json:"compress" yaml:"compress"`

	// PrintTerm 是否同时在终端上输出，只有在终端可用时输出
	PrintTerm bool `json:"printTerm" yaml:"printTerm"`
}

Config 包括一些滚动文件的配置参数，所有参数，均有默认值，方便无脑集成

type ConfigFn

type ConfigFn func(*Config)

ConfigFn 选项模式函数

func WithAppName

func WithAppName(v string) ConfigFn

WithAppName 指定日志文件基础文件名

func WithCompress

func WithCompress(v bool) ConfigFn

WithCompress 指定是否开启压缩

func WithConfig

func WithConfig(v Config) ConfigFn

WithConfig 指定 Config 参数对象

func WithFilename

func WithFilename(v string) ConfigFn

WithFilename 指定日志文件名字

func WithMaxBackups

func WithMaxBackups(v int) ConfigFn

WithMaxBackups 指定最大备份文件数量

func WithMaxDays

func WithMaxDays(v int) ConfigFn

WithMaxDays 指定最大保存天数

func WithMaxSize

func WithMaxSize(v uint64) ConfigFn

WithMaxSize 指定日志文件最大大小

func WithMinDiskFree

func WithMinDiskFree(v uint64) ConfigFn

WithMinDiskFree 指定最小磁盘可用大小

func WithPrefix

func WithPrefix(v string) ConfigFn

WithPrefix 指定日志基本文件名前缀，在 Filename 不指定的情况下，可以使用本字段给自动生成的日志文件名添加此前缀

func WithPrintTerm

func WithPrintTerm(v bool) ConfigFn

WithPrintTerm 指定是否同时打印到控制台

func WithRotateSignals

func WithRotateSignals(v ...os.Signal) ConfigFn

WithRotateSignals 指定强制滚动信号

func WithTotalSizeCap

func WithTotalSizeCap(v uint64) ConfigFn

WithTotalSizeCap 指定日志总和大小上限

func WithUtcTime

func WithUtcTime(v bool) ConfigFn

WithUtcTime 指定是否使用 UTC 时间

type RotateFile

type RotateFile interface {
	io.WriteCloser

	Rotate() error
	Flush() error

	// GetFilename 取得日志文件的距离路径
	GetFilename() string
}

RotateFile 滚动文件大小

func New

func New(fns ...ConfigFn) RotateFile

New 创建新一个新的滚动文件对象