logtail

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

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.com"
	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
	Bus            *eventbus.Bus   // if set, uses the eventbus for awaitInternetUp instead of callback
	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
	MaxUploadSize  int             // maximum upload size; 0 means using the default

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

	// Disabled, if true, causes the returned [Logger] to start in the
	// disabled state, dropping entries without buffering or uploading
	// (equivalent to calling [Logger.SetEnabled] with false immediately).
	// It applies before the internal startup banner is written, so no
	// log entries are emitted until [Logger.SetEnabled] is called with
	// true. The process-wide [Disable] kill switch still takes precedence.
	Disabled bool
}

type LogEntry[T any] struct {
	Logtail Logtail `json:"logtail,omitzero"`
	// The `inline` tag option was renamed to `embed` in Go 1.27's
	// encoding/json/v2, but the pinned go-json-experiment module
	// (used on older Go versions) only knows `inline`. Each
	// implementation ignores the option it doesn't know, so specify
	// both until we require Go 1.27 and drop `inline`.
	//
	//lint:ignore SA5008 staticcheck doesn't know Go 1.27's `embed` option yet
	Value T `json:",inline,embed"`
}

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

type Logtail struct {
	// ClientTime is the time the entry was generated. If zero, [UploadLogs]
	// fills it with the current time unless Config.SkipClientTime is set.
	ClientTime time.Time `json:"client_time,omitzero"`
	// ProcID is an ephemeral process identifier; see Config.IncludeProcID.
	ProcID uint32 `json:"proc_id,omitzero"`
	// ProcSeq is an ephemeral per-process sequence number; see
	// Config.IncludeProcSequence.
	ProcSeq uint64 `json:"proc_seq,omitzero"`
}