logger

Documentation

Overview

Package logger defines a type for writing to logs. It's just a convenience type so that we don't have to pass verbose func(...) types around.

Index

• func AsJSON(v any) fmt.Formatter
• func Discard(string, ...any)
• func FuncWriter(f Logf) io.Writer
• func StdLogger(f Logf) *log.Logger
• type ArgWriter
  • func (fn ArgWriter) Format(f fmt.State, _ rune)
• type Context
  • func Ctx(ctx context.Context, fn Logf) Context
• type Logf
  • func Filtered(logf Logf, allow func(s string) bool) Logf
  • func FromContext(ctx Context) Logf
  • func LogOnChange(logf Logf, maxInterval time.Duration, timeNow func() time.Time) Logf
  • func LogfCloser(logf Logf) (newLogf Logf, close func())
  • func RateLimitedFn(logf Logf, f time.Duration, burst int, maxCache int) Logf
  • func RateLimitedFnWithClock(logf Logf, f time.Duration, burst int, maxCache int, timeNow func() time.Time) Logf
  • func RusagePrefixLog(logf Logf) Logf
  • func SlowLoggerWithClock(ctx context.Context, logf Logf, f time.Duration, burst int, ...) Logf
  • func TestLogger(tb TBLogger) Logf
  • func WithPrefix(f Logf, prefix string) Logf
  • func (logf Logf) JSON(level int, recType string, v any)
• type TBLogger

Functions

func AsJSON

func AsJSON(v any) fmt.Formatter

AsJSON returns a formatter that formats v as JSON. The value is suitable to passing to a regular %v printf argument. (%s is not required)

If json.Marshal returns an error, the output is "%%!JSON-ERROR:" followed by the error string.

func Discard

func Discard(string, ...any)

Discard is a Logf that throws away the logs given to it.

func FuncWriter

func FuncWriter(f Logf) io.Writer

FuncWriter returns an io.Writer that writes to f.

func StdLogger

func StdLogger(f Logf) *log.Logger

StdLogger returns a standard library logger from a Logf.

Types

type ArgWriter

type ArgWriter func(*bufio.Writer)

ArgWriter is a fmt.Formatter that can be passed to any Logf func to efficiently write to a %v argument without allocations.

func (ArgWriter) Format

func (fn ArgWriter) Format(f fmt.State, _ rune)

type Context

type Context context.Context

A Context is a context.Context that should contain a custom log function, obtainable from FromContext. If no log function is present, FromContext will return log.Printf. To construct a Context, use Add

func Ctx

func Ctx(ctx context.Context, fn Logf) Context

Ctx constructs a Context from ctx with fn as its custom log function.

type Logf

type Logf func(format string, args ...any)

Logf is the basic Tailscale logger type: a printf-like func. Like log.Printf, the format need not end in a newline. Logf functions must be safe for concurrent use.

func Filtered

func Filtered(logf Logf, allow func(s string) bool) Logf

Filtered returns a Logf that silently swallows some log lines. Each inbound format and args is evaluated and printed to a string s. The original format and args are passed to logf if and only if allow(s) returns true.

func FromContext

func FromContext(ctx Context) Logf

FromContext extracts a log function from ctx.

func LogOnChange

func LogOnChange(logf Logf, maxInterval time.Duration, timeNow func() time.Time) Logf

LogOnChange logs a given line only if line != lastLine, or if maxInterval has passed since the last time this identical line was logged.

func LogfCloser

func LogfCloser(logf Logf) (newLogf Logf, close func())

LogfCloser wraps logf to create a logger that can be closed. Calling close makes all future calls to newLogf into no-ops.

func RateLimitedFn

func RateLimitedFn(logf Logf, f time.Duration, burst int, maxCache int) Logf

RateLimitedFn is a wrapper for RateLimitedFnWithClock that includes the current time automatically. This is mainly for backward compatibility.

func RateLimitedFnWithClock

func RateLimitedFnWithClock(logf Logf, f time.Duration, burst int, maxCache int, timeNow func() time.Time) Logf

RateLimitedFnWithClock returns a rate-limiting Logf wrapping the given logf. Messages are allowed through at a maximum of one message every f (where f is a time.Duration), in bursts of up to burst messages at a time. Up to maxCache format strings will be tracked separately. timeNow is a function that returns the current time, used for calculating rate limits.

func RusagePrefixLog

func RusagePrefixLog(logf Logf) Logf

RusagePrefixLog returns a Logf func wrapping the provided logf func that adds a prefixed log message to each line with the current binary memory usage and max RSS.

func SlowLoggerWithClock

func SlowLoggerWithClock(ctx context.Context, logf Logf, f time.Duration, burst int, timeNow func() time.Time) Logf

SlowLoggerWithClock is a logger that applies rate limits similar to RateLimitedFnWithClock, but instead of dropping logs will sleep until they can be written. This should only be used for debug logs, and not in a hot path.

The provided context, if canceled, will cause all logs to be dropped and prevent any sleeps.

func TestLogger

func TestLogger(tb TBLogger) Logf

TestLogger returns a logger that logs to tb.Logf with a prefix to make it easier to distinguish spam from explicit test failures.

func WithPrefix

func WithPrefix(f Logf, prefix string) Logf

WithPrefix wraps f, prefixing each format with the provided prefix.

func (Logf) JSON

func (logf Logf) JSON(level int, recType string, v any)

JSON marshals v as JSON and writes it to logf formatted with the annotation to make logtail treat it as a structured log.

The recType is the record type and becomes the key of the wrapper JSON object that is logged. That is, if recType is "foo" and v is 123, the value logged is {"foo":123}.

Do not use recType "logtail", "v", "text", or "metrics", with any case. Those are reserved for the logging system.

The level can be from 0 to 9. Levels from 1 to 9 are included in the logged JSON object, like {"foo":123,"v":2}.

type TBLogger

type TBLogger interface {
	Helper()
	Logf(format string, args ...any)
}

TBLogger is the testing.TB subset needed by TestLogger.