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()
• func RegisterLogTap(dst chan<- string) (unregister func())
• type Buffer
  • func NewMemoryBuffer(numEntries int) Buffer
• type Config
• type Logger
  • func NewLogger(cfg Config, logf tslogger.Logf) *Logger
  • func (l *Logger) AppendTextOrJSONLocked(dst, src []byte) []byte
  • func (l *Logger) Close()
  • func (l *Logger) Flush() error
  • func (l *Logger) Logf(format string, args ...any)
  • func (l *Logger) PrivateID() logid.PrivateID
  • func (l *Logger) SetNetMon(lm *netmon.Monitor)
  • func (l *Logger) SetSockstatsLabel(label sockstats.Label)
  • func (l *Logger) SetVerbosityLevel(level int)
  • func (l *Logger) Shutdown(ctx context.Context) error
  • func (l *Logger) StartFlush()
  • func (l *Logger) Write(buf []byte) (int, 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.

func RegisterLogTap

func RegisterLogTap(dst chan<- string) (unregister func())

RegisterLogTap registers dst to get a copy of every log write. The caller must call unregister when done watching.

This would ideally be a method on Logger, but Logger isn't really available in most places; many writes go via stderr which filch redirects to the singleton Logger set up early. For better or worse, there's basically only one Logger within the program. This mechanism at least works well for tailscaled. It works less well for a binary with multiple tsnet.Servers. Oh well. This then subscribes to all of them.

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.
	// Implementations must not retain the provided 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      logid.PrivateID // private ID for the primary log stream
	CopyPrivateID  logid.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
	Clock          tstime.Clock    // if set, Clock.Now 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
	CompressLogs   bool            // whether to compress the log uploads

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

	// FlushDelayFn, if non-nil is a func that returns how long to wait to
	// accumulate logs before uploading them. 0 or negative means to upload
	// immediately.
	//
	// If nil, a default value is used. (currently 2 seconds)
	FlushDelayFn func() 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 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) AppendTextOrJSONLocked

func (l *Logger) AppendTextOrJSONLocked(dst, src []byte) []byte

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.

TODO(bradfitz): this apparently just returns nil, as of tailscale/corp@9c2ec35. Finish cleaning this up.

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() logid.PrivateID

PrivateID returns the logger's private log ID.

It exists for internal use only.

func (*Logger) SetNetMon

func (l *Logger) SetNetMon(lm *netmon.Monitor)

SetNetMon sets the network monitor.

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

func (*Logger) SetSockstatsLabel

func (l *Logger) SetSockstatsLabel(label sockstats.Label)

SetSockstatsLabel sets the label used in sockstat logs to identify network traffic from this logger.

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

func (l *Logger) StartFlush()

StartFlush starts a log upload, if anything is pending.

If l is nil, StartFlush is a no-op.

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.