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
• func Disable()
• 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) Logf(format string, args ...any)
  • func (l *Logger) PrivateID() PrivateID
  • 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() (PrivateID, error)
  • func ParsePrivateID(s string) (PrivateID, error)
• type PublicID
  • func ParsePublicID(s string) (PublicID, error)

Constants

const (
	// CollectionNode is the name of a logtail Config.Collection
	// for tailscaled (or equivalent: IPNExtension, Android app).
	CollectionNode = "tailnode.log.tailscale.io"
)

const DefaultHost = "log.tailscale.io"

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

Functions

func Disable

func Disable()

Disable disables logtail uploads for the lifetime of the process.

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 takes ownership of the provided slice.
	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        // private ID for the primary log stream
	CopyPrivateID  PrivateID        // private ID for a log stream that is a superset of this log stream
	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, substitutes 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

	// MetricsDelta, if non-nil, is a func that returns an encoding
	// delta in clientmetrics to upload alongside existing logs.
	// It can return either an empty string (for nothing) or a string
	// that's safe to embed in a JSON string literal without further escaping.
	MetricsDelta func() string

	// FlushDelay is how long to wait to accumulate logs before
	// uploading them.
	//
	// If zero, a default value is used. (currently 2 seconds)
	//
	// Negative means to upload immediately.
	FlushDelay time.Duration

	// IncludeProcID, if true, results in an ephemeral process identifier being
	// included in logs. The ID is random and not guaranteed to be globally
	// unique, but it can be used to distinguish between different instances
	// running with same PrivateID.
	IncludeProcID bool

	// IncludeProcSequence, if true, results in an ephemeral sequence number
	// being included in the logs. The sequence number is incremented for each
	// log message sent, but is not persisted across process restarts.
	IncludeProcSequence bool
}

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) Logf

func (l *Logger) Logf(format string, args ...any)

Logf logs to l using the provided fmt-style format and optional arguments.

func (*Logger) PrivateID

func (l *Logger) PrivateID() PrivateID

PrivateID returns the logger's private log ID.

It exists for internal use only.

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 = logid.PrivateID

Deprecated: Use "tailscale.com/types/logid".PrivateID instead.

func NewPrivateID

func NewPrivateID() (PrivateID, error)

Deprecated: Use "tailscale.com/types/logid".NewPrivateID instead.

func ParsePrivateID

func ParsePrivateID(s string) (PrivateID, error)

Deprecated: Use "tailscale.com/types/logid".ParsePrivateID instead.

type PublicID

type PublicID = logid.PublicID

Deprecated: Use "tailscale.com/types/logid".PublicID instead.

func ParsePublicID

func ParsePublicID(s string) (PublicID, error)

Deprecated: Use "tailscale.com/types/logid".ParsePublicID instead.