package lumberjack

Import Path
	gopkg.in/natefinch/lumberjack.v2 (on go.dev)

Dependency Relation
	imports 12 packages, and imported by one package

Involved Source Files

	      chown_linux.go
	   d➜ lumberjack.go
		Package lumberjack provides a rolling logger.

		Note that this is v2.0 of lumberjack, and should be imported using gopkg.in
		thusly:

		  import "gopkg.in/natefinch/lumberjack.v2"

		The package name remains simply lumberjack, and the code resides at
		https://github.com/natefinch/lumberjack under the v2.0 branch.

		Lumberjack 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.

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

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

	
	  {
	  	log.SetOutput(&lumberjack.Logger{
	  		Filename:   "/var/log/myapp/foo.log",
	  		MaxSize:    500,
	  		MaxBackups: 3,
	  		MaxAge:     28,
	  		Compress:   true,
	  	})
	  }

Package-Level Type Names (total 3, in which 1 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Logger (struct)
		Logger is an io.WriteCloser that writes to the specified filename.

		Logger opens or creates the logfile on first Write.  If the file exists and
		is less than MaxSize megabytes, lumberjack 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 Logger is always the "current" log
		file.

		Backups use the log file name given to Logger, 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 `2006-01-02T15-04-05.000` and the extension is the
		original extension.  For example, if your Logger.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-2016-11-04T18-30-00.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 MaxAge 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 MaxAge are both 0, no old log files will be deleted.

		Fields (total 11, in which 6 are exported)
			Compress bool
				Compress determines if the rotated log files should be compressed
				using gzip. The default is not to perform compression.

			Filename string
				Filename is the file to write logs to.  Backup log files will be retained
				in the same directory.  It uses <processname>-lumberjack.log in
				os.TempDir() if empty.

			LocalTime bool
				LocalTime 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.

			MaxAge int
				MaxAge 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.

			MaxBackups int
				MaxBackups is the maximum number of old log files to retain.  The default
				is to retain all old log files (though MaxAge may still cause them to get
				deleted.)

			MaxSize int
				MaxSize is the maximum size in megabytes of the log file before it gets
				rotated. It defaults to 100 megabytes.

			/* 5 unexporteds ... *//* 5 unexporteds: */
			file *os.File
			millCh chan bool
			mu sync.Mutex
			size int64
			startMill sync.Once
		Methods (total 16, in which 3 are exported)
			(*T) Close() error
				Close implements io.Closer, and closes the current logfile.

			(*T) Rotate() error
				Rotate causes Logger to close the existing log file and immediately create a
				new one.  This is a helper function for applications that want to initiate
				rotations outside of the normal rotation rules, such as in response to
				SIGHUP.  After rotating, this initiates compression and removal of old log
				files according to the configuration.

			(*T) Write(p []byte) (n int, err error)
				Write implements io.Writer.  If a write would cause the log file to be larger
				than MaxSize, the file is closed, renamed to include a timestamp of the
				current time, and a new log file is created using the original log file name.
				If the length of the write is greater than MaxSize, an error is returned.

			/* 13 unexporteds ... *//* 13 unexporteds: */
			(*T) close() error
				close closes the file if it is open.

			(*T) dir() string
				dir returns the directory for the current filename.

			(*T) filename() string
				genFilename generates the name of the logfile from the current time.

			(*T) max() int64
				max returns the maximum size in bytes of log files before rolling.

			(*T) mill()
				mill performs post-rotation compression and removal of stale log files,
				starting the mill goroutine if necessary.

			(*T) millRun()
				millRun runs in a goroutine to manage post-rotation compression and removal
				of old log files.

			(*T) millRunOnce() error
				millRunOnce performs compression and removal of stale log files.
				Log files are compressed if enabled via configuration and old log
				files are removed, keeping at most l.MaxBackups files, as long as
				none of them are older than MaxAge.

			(*T) oldLogFiles() ([]logInfo, error)
				oldLogFiles returns the list of backup log files stored in the same
				directory as the current log file, sorted by ModTime

			(*T) openExistingOrNew(writeLen int) error
				openExistingOrNew opens the logfile if it exists and if the current write
				would not put it over MaxSize.  If there is no such file or the write would
				put it over the MaxSize, a new file is created.

			(*T) openNew() error
				openNew opens a new log file for writing, moving any old log file out of the
				way.  This methods assumes the file has already been closed.

			(*T) prefixAndExt() (prefix, ext string)
				prefixAndExt returns the filename part and extension part from the Logger's
				filename.

			(*T) rotate() error
				rotate closes the current file, moves it aside with a timestamp in the name,
				(if it exists), opens a new file with the original filename, and then runs
				post-rotation processing and removal.

			(*T) timeFromName(filename, prefix, ext string) (time.Time, error)
				timeFromName extracts the formatted time from the filename by stripping off
				the filename's prefix and extension. This prevents someone's filename from
				confusing time.parse.

		Implements (at least 3, all are exported)
			*T : io.Closer
			*T : io.WriteCloser
			*T : io.Writer

	/* 2 unexporteds ... *//* 2 unexporteds: */
	 type byFormatTime ([]T)
		byFormatTime sorts by newest time formatted in the name.

		Methods (total 3, all are exported)
			( T) Len() int
			( T) Less(i, j int) bool
			( T) Swap(i, j int)
		Implements (at least one exported)
			 T : sort.Interface

	 type logInfo (struct)
		logInfo is a convenience struct to return the filename and its embedded
		timestamp.

		Fields (total 2, in which 1 are exported)
			FileInfo os.FileInfo
			/* one unexported ... *//* one unexported: */
			timestamp time.Time
		Methods (total 6, all are exported)
			( T) IsDir() bool
				// abbreviation for Mode().IsDir()

			( T) ModTime() time.Time
				// modification time

			( T) Mode() fs.FileMode
				// file mode bits

			( T) Name() string
				// base name of the file

			( T) Size() int64
				// length in bytes for regular files; system-dependent for others

			( T) Sys() interface{}
				// underlying data source (can return nil)

		Implements (at least one exported)
			 T : io/fs.FileInfo
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func (*Logger).oldLogFiles() ([]logInfo, error)


Package-Level Functions (total 3, none are exported)

	/* 3 unexporteds ... *//* 3 unexporteds: */
	 func backupName(name string, local bool) string
		backupName creates a new filename from the given name, inserting a timestamp
		between the filename and the extension, using the local time if requested
		(otherwise UTC).

	 func chown(name string, info os.FileInfo) error
	 func compressLogFile(src, dst string) (err error)
		compressLogFile compresses the given log file, removing the
		uncompressed log file if successful.


Package-Level Variables (total 4, none are exported)

	/* 4 unexporteds ... *//* 4 unexporteds: */
	  var currentTime func() time.Time
		currentTime exists so it can be mocked out by tests.

	  var megabyte int
		megabyte is the conversion factor between MaxSize and bytes.  It is a
		variable so tests can mock it out and not need to write megabytes of data
		to disk.

	  var os_Chown func(name string, uid int, gid int) error
		os_Chown is a var so we can mock it out during tests.

	  var os_Stat func(name string) (fs.FileInfo, error)
		os_Stat exists so it can be mocked out by tests.


Package-Level Constants (total 3, none are exported)

	/* 3 unexporteds ... *//* 3 unexporteds: */
	const backupTimeFormat = "2006-01-02T15-04-05.000"
	const compressSuffix = ".gz"
	const defaultMaxSize = 100

The pages are generated with Golds v0.3.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.