package logpolicy

import "tailscale.com/logpolicy"

Package logpolicy manages the creation or reuse of logtail loggers, caching collection instance state on disk for use on future runs of programs on the same machine.

Index ¶

• func LogHost() string
• func LogURL() string
• func LogsDir(logf logger.Logf) string
• func MakeDialFunc(netMon *netmon.Monitor, logf logger.Logf) netx.DialFunc
• func NewLogtailTransport(host string, netMon *netmon.Monitor, health *health.Tracker, logf logger.Logf) http.RoundTripper
• type Config
• func ConfigFromBytes(jsonEnc []byte) (*Config, error)
• func ConfigFromFile(statefile string) (*Config, error)
• func NewConfig(collection string) *Config
• func (c *Config) Save(stateFile string) error
• func (c *Config) ToBytes() []byte
• func (c *Config) Validate(collection string) error
• type Options
• func (opts Options) New() *Policy
• type Policy
• func New(collection string, netMon *netmon.Monitor, health *health.Tracker, logf logger.Logf) *Policy
• func NewWithConfigPath(collection, dir, cmdName string, netMon *netmon.Monitor, health *health.Tracker, logf logger.Logf) *Policy
• func (p *Policy) Close()
• func (p *Policy) SetVerbosityLevel(level int)
• func (p *Policy) Shutdown(ctx context.Context) error
• type TransportOptions
• func (opts TransportOptions) New() http.RoundTripper

Functions ¶

func LogHost ¶

func LogHost() string

LogHost returns the hostname only (without port) of the configured logtail server, or the default.

Deprecated: Use LogURL instead.

func LogURL ¶

func LogURL() string

LogURL is the base URL for the configured logtail server, or the default. It is guaranteed to not terminate with any forward slashes.

func LogsDir ¶

func LogsDir(logf logger.Logf) string

LogsDir returns the directory to use for log configuration and buffer storage.

func MakeDialFunc ¶

func MakeDialFunc(netMon *netmon.Monitor, logf logger.Logf) netx.DialFunc

MakeDialFunc creates a net.Dialer.DialContext function specialized for use by logtail. It does the following:

• If DNS lookup fails, consults the bootstrap DNS list of Tailscale hostnames.
• If TLS connection fails, try again using LetsEncrypt's built-in root certificate, for the benefit of older OS platforms which might not include it.

The netMon parameter is optional. It should be specified in environments where Tailscaled is manipulating the routing table.

func NewLogtailTransport ¶

func NewLogtailTransport(host string, netMon *netmon.Monitor, health *health.Tracker, logf logger.Logf) http.RoundTripper

Deprecated: Use TransportOptions.New instead.

Types ¶

type Config ¶

type Config struct {
	Collection string
	PrivateID  logid.PrivateID
	PublicID   logid.PublicID
}

Config represents an instance of logs in a collection.

func ConfigFromBytes ¶

func ConfigFromBytes(jsonEnc []byte) (*Config, error)

ConfigFromBytes parses a Config from its JSON encoding.

func ConfigFromFile ¶

func ConfigFromFile(statefile string) (*Config, error)

ConfigFromFile reads a Config from a JSON file.

func NewConfig ¶

func NewConfig(collection string) *Config

NewConfig creates a Config with collection and a newly generated PrivateID.

func (*Config) Save ¶

func (c *Config) Save(stateFile string) error

Save writes the JSON representation of c to stateFile.

func (*Config) ToBytes ¶

func (c *Config) ToBytes() []byte

ToBytes returns the JSON representation of c.

func (*Config) Validate ¶

func (c *Config) Validate(collection string) error

Validate verifies that the Config matches the collection, and that the PrivateID and PublicID pair are sensible.

type Options ¶

type Options struct {
	// Collection is a required collection to upload logs under.
	// Collection is a namespace for the type logs.
	// For example, logs for a node use "tailnode.log.tailscale.io".
	Collection string

	// Dir is an optional directory to store the log configuration.
	// If empty, [LogsDir] is used.
	Dir string

	// CmdName is an optional name of the current binary.
	// If empty, [version.CmdName] is used.
	CmdName string

	// NetMon is an optional parameter for monitoring.
	// If non-nil, it's used to do faster interface lookups.
	NetMon *netmon.Monitor

	// Health is an optional parameter for health status.
	// If non-nil, it's used to construct the default HTTP client.
	Health *health.Tracker

	// Logf is an optional logger to use.
	// If nil, [log.Printf] will be used instead.
	Logf logger.Logf

	// HTTPC is an optional client to use upload logs.
	// If nil, [TransportOptions.New] is used to construct a new client
	// with that particular transport sending logs to the default logs server.
	HTTPC *http.Client

	// MaxBufferSize is the maximum size of the log buffer.
	// This controls the amount of logs that can be temporarily stored
	// before the logs can be successfully upload.
	// If zero, a default buffer size is chosen.
	MaxBufferSize int

	// MaxUploadSize is the maximum size per upload.
	// This should only be set by clients that have been authenticated
	// with the logging service as having a higher upload limit.
	// If zero, a default upload size is chosen.
	MaxUploadSize int
}

Options is used to construct a Policy.

func (Options) New ¶

func (opts Options) New() *Policy

New returns a new log policy (a logger and its instance ID).

type Policy ¶

type Policy struct {
	// Logtail is the logger.
	Logtail *logtail.Logger
	// PublicID is the logger's instance identifier.
	PublicID logid.PublicID
	// Logf is where to write informational messages about this Logger.
	Logf logger.Logf
}

Policy is a logger and its public ID.

func New ¶

func New(collection string, netMon *netmon.Monitor, health *health.Tracker, logf logger.Logf) *Policy

Deprecated: Use Options.New instead.

func NewWithConfigPath ¶

func NewWithConfigPath(collection, dir, cmdName string, netMon *netmon.Monitor, health *health.Tracker, logf logger.Logf) *Policy

Deprecated: Use Options.New instead.

func (*Policy) Close ¶

func (p *Policy) Close()

Close immediately shuts down the logger.

func (*Policy) SetVerbosityLevel ¶

func (p *Policy) 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.

It should not be changed concurrently with log writes.

func (*Policy) Shutdown ¶

func (p *Policy) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the logger, finishing any current log upload if it can be done before ctx is canceled.

type TransportOptions ¶

type TransportOptions struct {
	// Host is the optional hostname of the logs server.
	// If empty, then [logtail.DefaultHost] is used.
	Host string

	// NetMon is an optional parameter for monitoring.
	// If non-nil, it's used to do faster interface lookups.
	NetMon *netmon.Monitor

	// Health is an optional parameter for health status.
	// If non-nil, it's used to construct the default HTTP client.
	Health *health.Tracker

	// Logf is an optional logger to use.
	// If nil, [log.Printf] will be used instead.
	Logf logger.Logf

	// TLSClientConfig is an optional TLS configuration to use.
	// If non-nil, the configuration will be cloned.
	TLSClientConfig *tls.Config
}

TransportOptions is used to construct an http.RoundTripper.

func (TransportOptions) New ¶

func (opts TransportOptions) New() http.RoundTripper

New returns an HTTP Transport particularly suited to uploading logs to the given host name. See [DialContext] for details on how it works.

Source Files ¶

logpolicy.go