Lumberjack

https://pkg.go.dev/github.com/natefinch/lumberjack/v3
Admin
Lumberjack is a Go package for writing logs to rolling files, providing a pluggable component for...
Tokens:6,483
Snippets:71
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Rotate Logger on SIGHUP

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Example of how to rotate logs in response to SIGHUP signal.

```go
l := &lumberjack.Logger{}
log.SetOutput(l)
c := make(chan os.Signal, 1)
signal.Notify(c, syscall.SIGHUP)

go func() {
    for {
        <-
c
        l.Rotate()
    }
}()

```

--------------------------------

### Rotate Logger on SIGHUP

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Example of how to rotate logs in response to a SIGHUP signal using the standard library's log package and lumberjack.

```go
l := &lumberjack.Logger{}
log.SetOutput(l)
c := make(chan os.Signal, 1)
signal.Notify(c, syscall.SIGHUP)

go func() {
    for {
        <-c
        l.Rotate()
    }
}()

```

--------------------------------

### Logger.Rotate

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3

Rotate causes Logger to close the existing log file and immediately create a new one. This is a useful for manual log rotation, for example, in response to SIGHUP signals. After rotation, old log files are cleaned up according to the configured rules.

```APIDOC
## Logger.Rotate

### Description
Closes the current log file and creates a new one immediately. This method also triggers a cleanup of old log files based on the configured `MaxBackups` and `MaxAge` settings.

### Method
```
func (l *Logger) Rotate() error
```

### Parameters
This method does not take any parameters.

### Returns
- `error`: An error if the log file could not be rotated or cleaned up, otherwise nil.

### Example
Example of how to rotate in response to SIGHUP.
```go
l := &lumberjack.Logger{}
log.SetOutput(l)
c := make(chan os.Signal, 1)
signal.Notify(c, syscall.SIGHUP)

go func() {
    for {
        <-c
        l.Rotate()
    }
}()
```
```

--------------------------------

### Import Lumberjack v2.0

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Import the lumberjack v2.0 package using gopkg.in.

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

```

--------------------------------

### Logger Options Struct

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Options represents optional behavior for a new Roller, including MaxAge, MaxBackups, LocalTime, and Compress.

```go
type Options struct {
	// MaxAge is the maximum time to retain old log files based on the timestamp
	// encoded in their filename. The default is not to remove old log files
	// based on age.
	MaxAge time.Duration

	// 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.)
	MaxBackups int

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

	// Compress determines if the rotated log files should be compressed
	// using gzip. The default is not to perform compression.
	Compress bool
}

```

--------------------------------

### NewRoller

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3

Initializes a new Roller instance. It handles existing log files by appending if they are below maxSize, or rotating and creating a new file if they meet or exceed maxSize. Returns an error if file operations fail or if maxSize is invalid.

```APIDOC
## NewRoller

### Description
Initializes a new Roller instance. It handles existing log files by appending if they are below maxSize, or rotating and creating a new file if they meet or exceed maxSize. Returns an error if file operations fail or if maxSize is invalid.

### Method
`func NewRoller(filename string, maxSize int64, opt *Options) (*Roller, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Roller** (*Roller) - A pointer to the newly created Roller instance.
- **error** (error) - An error if initialization fails.

#### Response Example
None
```

--------------------------------

### Logger Options

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Represents optional configurations for a new Roller, including maximum age of old logs, maximum number of backups, local time usage, and compression.

```go
type Options struct {
	// MaxAge is the maximum time to retain old log files based on the timestamp
	// encoded in their filename. The default is not to remove old log files
	// based on age.
	MaxAge time.Duration

	// 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.)
	MaxBackups int

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

	// Compress determines if the rotated log files should be compressed
	// using gzip. The default is not to perform compression.
	Compress bool
}
```

--------------------------------

### Configure and Set Lumberjack Logger

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Integrate lumberjack with the standard library's log package by setting its output.

```go
log.SetOutput(&lumberjack.Logger{
    Filename:   "/var/log/myapp/foo.log",
    MaxSize:    500, // megabytes
    MaxBackups: 3,
    MaxAge:     28, //days
    Compress:   true, // disabled by default
})

```

--------------------------------

### Rotate Logger

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Closes the existing log file and creates a new one. Initiates cleanup of old log files.

```go
func (l *Logger) Rotate() error
```

--------------------------------

### Close method signature

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Signature for the Close method, which implements io.Closer and closes the current log file.

```go
func (r *Roller) Close() error
```

--------------------------------

### Close Logger

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Implements io.Closer and closes the current logfile.

```go
func (l *Logger) Close() error
```

--------------------------------

### Write method signature

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Signature for the Write method, which implements io.Writer. It handles log file rotation based on MaxSize and returns an error if a single write exceeds MaxSize.

```go
func (r *Roller) Write(p []byte) (n int, err error)
```

--------------------------------

### NewRoller

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Creates a new Roller instance. It handles existing log files by appending if they are below maxSize or rotating them if they meet or exceed maxSize.

```APIDOC
## NewRoller

### Description
Creates a new Roller instance. If the log file exists and is smaller than `maxSize`, it appends to it. If the file exists and is equal to or larger than `maxSize`, it renames the file with a timestamp and creates a new one.

### Method
func NewRoller(filename string, maxSize int64, opt *Options) (*Roller, error)

### Parameters
* `filename` (string) - The name of the log file.
* `maxSize` (int64) - The maximum size of the log file in bytes. Must be greater than 0.
* `opt` (*Options) - Configuration options for the roller.

### Returns
* `(*Roller, error)` - A pointer to the new Roller instance and an error if file operations fail or `maxSize` is invalid.
```

--------------------------------

### NewRoller

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Creates a new Roller instance. It handles appending to existing log files or creating new ones based on size.

```APIDOC
## NewRoller

### Description
Creates a new Roller instance. If the log file exists and is smaller than `maxSize`, it appends to it. Otherwise, it renames the existing file with a timestamp and creates a new one.

### Function Signature
```go
func NewRoller(filename string, maxSize int64, opt *Options) (*Roller, error)
```

### Parameters
* **filename** (string) - The name of the log file.
* **maxSize** (int64) - The maximum size of the log file in bytes. Must be greater than 0.
* **opt** (*Options) - Configuration options for the roller.

### Returns
* (*Roller) - A pointer to the newly created Roller.
* (error) - An error if the file cannot be opened/created or if `maxSize` is invalid.
```

--------------------------------

### Write to Logger

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Implements io.Writer. Rotates log file if write exceeds MaxSize.

```go
func (l *Logger) Write(p []byte) (n int, err error)
```

--------------------------------

### Rotate method signature

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Signature for the Rotate method, which forces an immediate rotation of the log file and initiates cleanup of old files.

```go
func (r *Roller) Rotate() error
```

--------------------------------

### Logger.Write

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3

Write implements io.Writer. When a write operation would exceed the MaxSize, the current log file is closed, timestamped, and a new file is created. Writes larger than MaxSize will result in an error.

```APIDOC
## Logger.Write

### Description
Writes data to the logger. If writing the data would exceed the `MaxSize` of the current log file, the file is rotated before writing. If a single write operation exceeds `MaxSize`, an error is returned.

### Method
```
func (l *Logger) Write(p []byte) (n int, err error)
```

### Parameters
- **p** ([]byte) - The data to be written to the log file.

### Returns
- **n** (int) - The number of bytes written.
- **err** (error) - An error if the write operation failed or if the write size exceeded `MaxSize`.
```

--------------------------------

### Lumberjack Error Constant

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

ErrWriteTooLong indicates that a single write is longer than the max size allowed in a single file.

```go
const ErrWriteTooLong = constError("write exceeds max file length")
```

--------------------------------

### Roller.Write

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3

Implements the io.Writer interface. Writes data to the log file. If the write operation would exceed the MaxSize, the current file is rotated before writing. Writes larger than MaxSize will result in an error.

```APIDOC
## Roller.Write

### Description
Implements the io.Writer interface. Writes data to the log file. If the write operation would exceed the MaxSize, the current file is rotated before writing. Writes larger than MaxSize will result in an error.

### Method
`func (r *Roller) Write(p []byte) (n int, err error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **p** ([]byte) - The byte slice containing the data to write to the log.

### Request Example
None

### Response
#### Success Response (200)
- **n** (int) - The number of bytes written.
- **err** (error) - nil if the write was successful, otherwise an error.

#### Response Example
None
```

--------------------------------

### Roller.Rotate

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Manually triggers a log file rotation, closing the current file and creating a new one, then cleaning up old files.

```APIDOC
## (*Roller) Rotate

### Description
Causes the logger to close the existing log file and immediately create a new one. This is useful for applications that need to initiate log rotation outside of the automatic rules (e.g., in response to SIGHUP). After rotation, it also triggers the compression and removal of old log files based on the configured `MaxBackups` and `MaxAge`.

### Method
```go
func (r *Roller) Rotate() error
```

### Returns
* (error) - An error if the rotation process fails.
```

--------------------------------

### Logger.Close

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3

Close implements io.Closer, and closes the current logfile. This method is used to gracefully shut down the logger and ensure all buffered logs are written.

```APIDOC
## Logger.Close

### Description
Closes the current log file. This method implements the io.Closer interface.

### Method
```
func (l *Logger) Close() error
```

### Parameters
This method does not take any parameters.

### Returns
- `error`: An error if the log file could not be closed, otherwise nil.
```

--------------------------------

### Roller.Rotate

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Manually triggers a log file rotation, closing the current file and creating a new one. It also initiates cleanup of old log files based on configuration.

```APIDOC
## Roller.Rotate

### Description
Forces the logger to close the current log file and immediately create a new one. This is useful for manual rotation triggers, such as in response to SIGHUP signals. After rotation, it cleans up old log files according to the `MaxBackups` and `MaxAge` settings.

### Method
func (r *Roller) Rotate() error

### Returns
* `error` - An error if the rotation process fails.
```

--------------------------------

### Roller.Write

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Writes data to the log file. If the write exceeds `MaxSize`, the file is rotated before writing.

```APIDOC
## (*Roller) Write

### Description
Implements the `io.Writer` interface. Writes data to the current log file. If the write operation would cause the file to exceed `MaxSize`, the current file is closed, renamed with a timestamp, and a new file is created before the write occurs. If the data to be written is larger than `MaxSize`, an error is returned.

### Method
```go
func (r *Roller) Write(p []byte) (n int, err error)
```

### Parameters
* **p** ([]byte) - The data to write to the log file.

### Returns
* (int) - The number of bytes written.
* (error) - An error if the write fails or if the data size exceeds `MaxSize`.
```

--------------------------------

### Logger Struct Definition

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Defines the configuration options for the lumberjack Logger, including file naming, size, age, and compression settings.

```go
type Logger struct {
    // 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.
    Filename string `json:"filename" yaml:"filename"`

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

    // 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.
    MaxAge int `json:"maxage" yaml:"maxage"`

    // 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.)
    MaxBackups int `json:"maxbackups" yaml:"maxbackups"`

    // 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.
    LocalTime bool `json:"localtime" yaml:"localtime"`

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

```

--------------------------------

### NewRoller function signature

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Signature for the NewRoller function, which creates and returns a new Roller instance. It handles file existence and size checks, renaming existing files if necessary.

```go
func NewRoller(filename string, maxSize int64, opt *Options) (*Roller, error)
```

--------------------------------

### Roller.Write

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Writes data to the log file. If the write operation would exceed the `maxSize`, the current log file is rotated before writing.

```APIDOC
## Roller.Write

### Description
Implements the `io.Writer` interface. Writes data to the current log file. If the write would exceed `maxSize`, the file is rotated first. If the data to be written is larger than `maxSize`, an error is returned.

### Method
func (r *Roller) Write(p []byte) (n int, err error)

### Parameters
* `p` ([]byte) - The data to write to the log file.

### Returns
* `(n int, err error)` - The number of bytes written and an error if the write fails or the data exceeds `maxSize`.
```

--------------------------------

### Roller.Close

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Closes the current log file, implementing the `io.Closer` interface.

```APIDOC
## (*Roller) Close

### Description
Closes the current log file. This method implements the `io.Closer` interface.

### Method
```go
func (r *Roller) Close() error
```

### Returns
* (error) - An error if closing the file fails.
```

--------------------------------

### Roller.Close

Source: https://pkg.go.dev/github.com/natefinch/lumberjack/v3%40v3.0.0-alpha

Closes the current log file, implementing the `io.Closer` interface.

```APIDOC
## Roller.Close

### Description
Closes the current log file. This method implements the `io.Closer` interface.

### Method
func (r *Roller) Close() error

### Returns
* `error` - An error if the log file cannot be closed.
```

--------------------------------

### Roller struct definition

Source: https://pkg.go.dev/gopkg.in/natefinch/lumberjack.v3

Defines the Roller struct used for log file management.

```go
type Roller struct {
	// contains filtered or unexported fields
}
```
Tokens:
Raw