logtail

README

Tailscale Logs Service

This github repository contains libraries, documentation, and examples for working with the public API of the tailscale logs service.

For a very quick introduction to the core features, read the API docs and peruse the logs reprocessing example.

For more information, write to info@tailscale.io.

Documentation

Overview

Package logtail sends logs to log.tailscale.io.

Index

• Constants
• type Buffer
  • func NewMemoryBuffer(numEntries int) Buffer
• type Config
• type Encoder
• type Logger
  • func NewLogger(cfg Config, logf tslogger.Logf) *Logger
  • func (l *Logger) Close()
  • func (l *Logger) Flush() error
  • func (l *Logger) SetLinkMonitor(lm *monitor.Mon)
  • func (l *Logger) SetVerbosityLevel(level int)
  • func (l *Logger) Shutdown(ctx context.Context) error
  • func (l *Logger) Write(buf []byte) (int, error)
• type PrivateID
  • func NewPrivateID() (id PrivateID, err error)
  • func ParsePrivateID(s string) (PrivateID, error)
  • func (id PrivateID) IsZero() bool
  • func (id PrivateID) MarshalText() ([]byte, error)
  • func (id PrivateID) Public() (pub PublicID)
  • func (id PrivateID) String() string
  • func (id *PrivateID) UnmarshalText(s []byte) error
• type PublicID
  • func ParsePublicID(s string) (PublicID, error)
  • func (id PublicID) MarshalText() ([]byte, error)
  • func (id PublicID) String() string
  • func (id *PublicID) UnmarshalText(s []byte) error

Constants

const DefaultHost = "log.tailscale.io"

DefaultHost is the default host name to upload logs to when Config.BaseURL isn't provided.

Types

type Buffer

type Buffer interface {
	// TryReadLine tries to read a log line from the ring buffer.
	// If no line is available it returns a nil slice.
	// If the ring buffer is closed it returns io.EOF.
	//
	// The returned slice may point to data that will be overwritten
	// by a subsequent call to TryReadLine.
	TryReadLine() ([]byte, error)

	// Write writes a log line into the ring buffer.
	Write([]byte) (int, error)
}

func NewMemoryBuffer

func NewMemoryBuffer(numEntries int) Buffer

type Config

type Config struct {
	Collection     string           // collection name, a domain name
	PrivateID      PrivateID        // machine-specific private identifier
	BaseURL        string           // if empty defaults to "https://log.tailscale.io"
	HTTPC          *http.Client     // if empty defaults to http.DefaultClient
	SkipClientTime bool             // if true, client_time is not written to logs
	LowMemory      bool             // if true, logtail minimizes memory use
	TimeNow        func() time.Time // if set, subsitutes uses of time.Now
	Stderr         io.Writer        // if set, logs are sent here instead of os.Stderr
	StderrLevel    int              // max verbosity level to write to stderr; 0 means the non-verbose messages only
	Buffer         Buffer           // temp storage, if nil a MemoryBuffer
	NewZstdEncoder func() Encoder   // if set, used to compress logs for transmission

	// DrainLogs, if non-nil, disables automatic uploading of new logs,
	// so that logs are only uploaded when a token is sent to DrainLogs.
	DrainLogs <-chan struct{}
}

type Encoder

type Encoder interface {
	EncodeAll(src, dst []byte) []byte
	Close() error
}

type Logger

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

Logger writes logs, splitting them as configured between local logging facilities and uploading to a log server.

func NewLogger

func NewLogger(cfg Config, logf tslogger.Logf) *Logger

func (*Logger) Close

func (l *Logger) Close()

Close shuts down this logger object, the background log uploader process, and any associated goroutines.

Deprecated: use Shutdown

func (*Logger) Flush

func (l *Logger) Flush() error

Flush uploads all logs to the server. It blocks until complete or there is an unrecoverable error.

func (*Logger) SetLinkMonitor

func (l *Logger) SetLinkMonitor(lm *monitor.Mon)

SetLinkMonitor sets the optional the link monitor.

It should not be changed concurrently with log writes and should only be set once.

func (*Logger) SetVerbosityLevel

func (l *Logger) SetVerbosityLevel(level int)

SetVerbosityLevel controls the verbosity level that should be written to stderr. 0 is the default (not verbose). Levels 1 or higher are increasingly verbose.

func (*Logger) Shutdown

func (l *Logger) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the logger while completing any remaining uploads.

It will block, continuing to try and upload unless the passed context object interrupts it by being done. If the shutdown is interrupted, an error is returned.

func (*Logger) Write

func (l *Logger) Write(buf []byte) (int, error)

Write logs an encoded JSON blob.

If the []byte passed to Write is not an encoded JSON blob, then contents is fit into a JSON blob and written.

This is intended as an interface for the stdlib "log" package.

type PrivateID

type PrivateID [32]byte

PrivateID represents an instance that write logs. Private IDs are only shared with the server when writing logs.

func NewPrivateID

func NewPrivateID() (id PrivateID, err error)

Safely generate a new PrivateId for use in Config objects. You should persist this across runs of an instance of your app, so that it can append to the same log file on each run.

func ParsePrivateID

func ParsePrivateID(s string) (PrivateID, error)

ParsePrivateID returns a PrivateID from its hex (String) representation.

func (PrivateID) IsZero

func (id PrivateID) IsZero() bool

IsZero reports whether id is the zero value.

func (PrivateID) MarshalText

func (id PrivateID) MarshalText() ([]byte, error)

func (PrivateID) Public

func (id PrivateID) Public() (pub PublicID)

func (PrivateID) String

func (id PrivateID) String() string

func (*PrivateID) UnmarshalText

func (id *PrivateID) UnmarshalText(s []byte) error

type PublicID

type PublicID [sha256.Size]byte

PublicID represents an instance in the logs service for reading and adoption. The public ID value is a SHA-256 hash of a private ID.

func ParsePublicID

func ParsePublicID(s string) (PublicID, error)

ParsePublicID returns a PublicID from its hex (String) representation.

func (PublicID) MarshalText

func (id PublicID) MarshalText() ([]byte, error)

func (PublicID) String

func (id PublicID) String() string

func (*PublicID) UnmarshalText

func (id *PublicID) UnmarshalText(s []byte) error