tail

README

Tail

Package tail implements file tailing with fsnotify.

Fork of nxadm/tail, simplified, reworked and optimized. Currently, supports only Linux.

go get github.com/go-faster/tail

package main

import (
	"context"
	"fmt"
	"io"
	"os"
	"time"

	"github.com/go-faster/tail"
)

func main() {
	t := tail.File("/var/log/application.txt", tail.Config{
		Follow:        true,        // tail -f
		BufferSize:    1024 * 128,  // 128 kb for internal reader buffer

		// Force polling if zero events are observed for longer than a minute.
		// Optional, just a safeguard to be sure that we are not stuck forever
		// if we miss inotify event.
		NotifyTimeout: time.Minute,

		// You can specify position to start tailing, same as Seek arguments.
		// For example, you can use the latest processed Line.Location() value.
		Location: &tail.Location{Whence: io.SeekStart, Offset: 0},
	})
	ctx := context.Background()
	// Enjoy zero allocation fast tailing with context support.
	if err := t.Tail(ctx, func(ctx context.Context, l *tail.Line) error {
		_, _ = fmt.Fprintln(os.Stdout, string(l.Data))
		return nil
	}); err != nil {
		panic(err)
	}
}

TODO

• Decide on ergonomics of ErrStop
• Tests for removing, tailing and creating events
• Benchmarks
• Decide how to deal with partial lines (i.e. EOF, but without \n)
• Decide on Windows support

Documentation

Overview

Package tail implements file tailing with fsnotify.

Index

• Variables
• type Config
• type Handler
• type Line
  • func (l *Line) Location() Location
• type Location
• type Tailer
  • func File(filename string, cfg Config) *Tailer
  • func (t *Tailer) Tail(ctx context.Context, h Handler) error
• type Tracker
  • func NewTracker(log *zap.Logger) *Tracker

Variables

var ErrStop = errors.New("tail should now stop")

ErrStop is returned when the tail of a file has been marked to be stopped.

Types

type Config

type Config struct {
	// Location sets starting file location.
	Location *Location
	// NotifyTimeout enables additional timeout for file changes waiting.
	// Can be used to ensure that we never miss event even if newWatcher fails to
	// deliver event.
	// Optional.
	NotifyTimeout time.Duration
	// Follow file after reaching io.EOF, waiting for new lines.
	Follow bool
	// BufferSize for internal reader, optional.
	BufferSize int
	// Logger to use, optional.
	Logger *zap.Logger
	// Tracker is optional custom *Tracker.
	Tracker *Tracker
}

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

type Handler

type Handler func(ctx context.Context, l *Line) error

Handler is called on each log line.

Implementation should not retain Line or Line.Data.

type Line

type Line struct {
	Data   []byte // do not retain, reused while reading file
	Offset int64  // is always the offset from start
}

Line of file.

func (*Line) Location

func (l *Line) Location() Location

Location returns corresponding Location for Offset.

Mostly convenience helper for using as Config.Location.

type Location

type Location struct {
	Offset int64
	Whence int
}

Location represents arguments to io.Seek.

See https://golang.org/pkg/io/#SectionReader.Seek

type Tailer

type Tailer struct {
	// contains filtered or unexported fields
}

Tailer implements file tailing.

Use Tail() to start.

func File

func File(filename string, cfg Config) *Tailer

File configures and creates new unstarted *Tailer.

Use Tailer.Tail() to start tailing file.

func (*Tailer) Tail

func (t *Tailer) Tail(ctx context.Context, h Handler) error

Tail opens file and starts tailing it, reporting observed lines to Handler.

Tail is blocking while calling Handler to reuse internal buffer and reduce allocations. Tail will call Handler in same sequence as lines are observed. See Handler for more info.

Can be called multiple times, but not concurrently.

type Tracker

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker multiplexes fsnotify events.

func NewTracker

func NewTracker(log *zap.Logger) *Tracker

NewTracker creates new custom *Tracker with provided logger.

It is recommended to use it as singleton and create only once.