tail

README

tail functionality in Go

nxadm/tail provides a Go library that emulates the features of the BSD tail program. The library comes with full support for truncation/move detection as it is designed to work with log rotation tools. The library works on all operating systems supported by Go, including POSIX systems like Linux, *BSD, MacOS, and MS Windows. Go 1.12 is the oldest compiler release supported.

A simple example:

// Create a tail
t, err := tail.TailFile(
	"/var/log/nginx.log", tail.Config{Follow: true, ReOpen: true})
if err != nil {
    panic(err)
}

// Print the text of each received line
for line := range t.Lines {
    fmt.Println(line.Text)
}

See API documentation.

Installing

go get github.com/nxadm/tail/...

History

This project is an active, drop-in replacement for the abandoned Go tail library at hpcloud. Next to addressing open issues/PRs of the original project, nxadm/tail continues the development by keeping up to date with the Go toolchain (e.g. go modules) and dependencies, completing the documentation, adding features and fixing bugs.

Examples

Examples, e.g. used to debug an issue, are kept in the examples directory.

Documentation

Overview

nxadm/tail provides a Go library that emulates the features of the BSD `tail` program. The library comes with full support for truncation/move detection as it is designed to work with log rotation tools. The library works on all operating systems supported by Go, including POSIX systems like Linux and *BSD, and MS Windows. Go 1.9 is the oldest compiler release supported.

Index

• Variables
• func OpenFile(name string) (file *os.File, err error)
• type Config
• type Line
  • func NewLine(text string, lineNum int) *Line
• type SeekInfo
• type Tail
  • func TailFile(filename string, config Config) (*Tail, error)
  • func (tail *Tail) Cleanup()
  • func (tail *Tail) Stop() error
  • func (tail *Tail) StopAtEOF() error
  • func (tail *Tail) Tell() (offset int64, err error)

Examples

• TailFile

Variables

var (
	// DefaultLogger logs to os.Stderr and it is used when Config.Logger == nil
	DefaultLogger = log.New(os.Stderr, "", log.LstdFlags)
	// DiscardingLogger can be used to disable logging output
	DiscardingLogger = log.New(ioutil.Discard, "", 0)
)

var (
	// ErrStop is returned when the tail of a file has been marked to be stopped.
	ErrStop = errors.New("tail should now stop")
)

Functions

func OpenFile

func OpenFile(name string) (file *os.File, err error)

Deprecated: this function is only useful internally and, as such, it will be removed from the API in a future major release.

OpenFile proxies a os.Open call for a file so it can be correctly tailed on POSIX and non-POSIX OSes like MS Windows.

Types

type Config

type Config struct {
	// File-specifc
	Location       *SeekInfo // Tail from this location. If nil, start at the beginning of the file
	ReOpen         bool      // Reopen recreated files (tail -F)
	MustExist      bool      // Fail early if the file does not exist
	Poll           bool      // Poll for file changes instead of using the default inotify
	Pipe           bool      // The file is a named pipe (mkfifo)
	OpenReaderFunc func(rd io.Reader) io.Reader

	// Generic IO
	Follow        bool // Continue looking for new lines (tail -f)
	MaxLineSize   int  // If non-zero, split longer lines into multiple lines
	CompleteLines bool // Only return complete lines (that end with "\n" or EOF when Follow is false)

	// Optionally, use a ratelimiter (e.g. created by the ratelimiter/NewLeakyBucket function)
	RateLimiter *ratelimiter.LeakyBucket

	// Optionally use a Logger. When nil, the Logger is set to tail.DefaultLogger.
	// To disable logging, set it to tail.DiscardingLogger
	Logger logger
}

Config is used to specify how a file must be tailed.

type Line

type Line struct {
	Text     string    // The contents of the file
	Num      int       // The line number
	SeekInfo SeekInfo  // SeekInfo
	Time     time.Time // Present time
	Err      error     // Error from tail
}

func NewLine

func NewLine(text string, lineNum int) *Line

Deprecated: this function is no longer used internally and it has little of no use in the API. As such, it will be removed from the API in a future major release.

NewLine returns a * pointer to a Line struct.

type SeekInfo

type SeekInfo struct {
	Offset int64
	Whence int
}

SeekInfo represents arguments to io.Seek. See: https://golang.org/pkg/io/#SectionReader.Seek

type Tail

type Tail struct {
	Filename string     // The filename
	Lines    chan *Line // A consumable channel of *Line
	Config              // Tail.Configuration

	tomb.Tomb // provides: Done, Kill, Dying
	// contains filtered or unexported fields
}

func TailFile

func TailFile(filename string, config Config) (*Tail, error)

TailFile begins tailing the file. And returns a pointer to a Tail struct and an error. An output stream is made available via the Tail.Lines channel (e.g. to be looped and printed). To handle errors during tailing, after finishing reading from the Lines channel, invoke the `Wait` or `Err` method on the returned *Tail.

Example

// Keep tracking a file even when recreated.
// /var/log/messages is typically continuously written and rotated daily.
testFileName := "/var/log/messages"
// ReOpen when truncated, Follow to wait for new input when EOL is reached
tailedFile, err := TailFile(testFileName, Config{ReOpen: true, Follow: true})
if err != nil {
	panic(err)
}

for line := range tailedFile.Lines {
	fmt.Println(line.Text)
}
// Prints all the lines in the logfile and keeps printing new input

func (*Tail) Cleanup

func (tail *Tail) Cleanup()

Cleanup removes inotify watches added by the tail package. This function is meant to be invoked from a process's exit handler. Linux kernel may not automatically remove inotify watches after the process exits. If you plan to re-read a file, don't call Cleanup in between.

func (*Tail) Stop

func (tail *Tail) Stop() error

Stop stops the tailing activity.

func (*Tail) StopAtEOF

func (tail *Tail) StopAtEOF() error

StopAtEOF stops tailing as soon as the end of the file is reached. The function returns an error,

func (*Tail) Tell

func (tail *Tail) Tell() (offset int64, err error)

Tell returns the file's current position, like stdio's ftell() and an error. Beware that this value may not be completely accurate because one line from the chan(tail.Lines) may have been read already.