log

Documentation

Overview

Package log implements logging analogous to the Google-internal C++ INFO/ERROR/V setup. It provides functions Info, Warning, Error, Fatal, plus formatting variants such as Infof. It also provides V-style logging and adaptions for use as a structured logging engine.

Basic examples:

	log.Info("Prepare to repel boarders")

	log.Fatal("Initialization failed", err)

 // Log with context.
 log.Infoc(context, "client error: %s", err)

See the documentation for the V function for an explanation of these examples:

if log.V(2) {
	log.Info("Starting transaction...")
}

Log output is buffered and written periodically using Flush. Programs should call Flush before exiting to guarantee all log output is written.

By default, all log statements write to files in a temporary directory. This package provides several flags that modify this behavior. These are provided via the pflags library; see InitFlags.

--logtostderr=true
	Logs are written to standard error instead of to files.
--alsologtostderr=INFO
	Logs are written to standard error as well as to files.
--log-dir=""
	Log files will be written to this directory instead of the
	default temporary directory.

Other flags provide aids to debugging.

--log-backtrace-at=""
	When set to a file and line number holding a logging statement,
	such as
		-log_backtrace_at=gopherflakes.go:234
	a stack trace will be written to the Info log whenever execution
	hits that statement. (Unlike with --vmodule, the ".go" must be
	present.)
--verbosity=0
	Enable V-leveled logging at the specified level.
--vmodule=""
	The syntax of the argument is a comma-separated list of pattern=N,
	where pattern is a literal file name (minus the ".go" suffix) or
	"glob" pattern and N is a V level. For instance,
		-vmodule=gopher*=3
	sets the V level to 3 in all Go files whose names begin "gopher".

Index

• Variables
• func Add(ctx context.Context, kvs ...interface{}) context.Context
• func DirSet() bool
• func DisableLogFileOutput()
• func EnableLogFileOutput(dir string)
• func Error(args ...interface{})
• func Errorc(ctx context.Context, format string, args ...interface{})
• func Errorf(format string, args ...interface{})
• func ErrorfDepth(depth int, format string, args ...interface{})
• func Fatal(args ...interface{})
• func FatalOnPanic()
• func Fatalc(ctx context.Context, format string, args ...interface{})
• func Fatalf(format string, args ...interface{})
• func FatalfDepth(depth int, format string, args ...interface{})
• func Flush()
• func GetLogReader(filename string, restricted bool) (io.ReadCloser, error)
• func Info(args ...interface{})
• func Infoc(ctx context.Context, format string, args ...interface{})
• func Infof(format string, args ...interface{})
• func InfofDepth(depth int, format string, args ...interface{})
• func NewStdLogger(severity Severity) *stdLog.Logger
• func Trace(ctx context.Context, msg string)
• func V(level level) bool
• func VDepth(level level, depth int) bool
• func Warning(args ...interface{})
• func Warningc(ctx context.Context, format string, args ...interface{})
• func Warningf(format string, args ...interface{})
• func WarningfDepth(depth int, format string, args ...interface{})
• type Entry
  • func FetchEntriesFromFiles(severity Severity, startTimestamp, endTimestamp int64, maxEntries int, ...) ([]Entry, error)
• type EntryDecoder
  • func NewEntryDecoder(in io.Reader) *EntryDecoder
  • func (d *EntryDecoder) Decode(entry *Entry) error
• type FileDetails
• type FileInfo
  • func ListLogFiles() ([]FileInfo, error)
• type Severity
  • func SeverityByName(s string) (Severity, bool)
  • func (s *Severity) Name() string
  • func (s *Severity) Set(value string) error
  • func (s *Severity) String() string

Variables

var (
	// NodeID is a context key identifying a node ID.
	NodeID = nodeIDField{}
	// StoreID is a context key identifying a store ID.
	StoreID = storeIDField{}
	// RangeID is a context key identifying a range ID.
	RangeID = rangeIDField{}
)

var MaxSize uint64 = 1024 * 1024 * 10

MaxSize is the maximum size of a log file in bytes.

var Stats struct {
	Info, Warning, Error outputStats
}

Stats tracks the number of lines of output and number of bytes per severity level. Values must be read with atomic.LoadInt64.

Functions

func Add

func Add(ctx context.Context, kvs ...interface{}) context.Context

Add takes a context and an additional even number of arguments, interpreted as key-value pairs. These are added on top of the supplied context and the resulting context returned.

func DirSet

func DirSet() bool

DirSet returns true of the log directory has been changed from its default.

func DisableLogFileOutput

func DisableLogFileOutput()

DisableLogFileOutput turns off logging. For unittesting only.

func EnableLogFileOutput

func EnableLogFileOutput(dir string)

EnableLogFileOutput turns on logging using the specified directory. For unittesting only.

func Error

func Error(args ...interface{})

Error logs to the ERROR, WARNING, and INFO logs. Arguments are handled in the manner of fmt.Print; a newline is appended.

func Errorc

func Errorc(ctx context.Context, format string, args ...interface{})

Errorc logs to the ERROR, WARNING, and INFO logs. It extracts values from Field keys specified in this package and logs them along with the given message and any additional pairs specified as consecutive elements in kvs.

func Errorf

func Errorf(format string, args ...interface{})

Errorf logs to the ERROR, WARNING, and INFO logs. Don't use it; use Error Info or Errorc instead. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func ErrorfDepth

func ErrorfDepth(depth int, format string, args ...interface{})

ErrorfDepth logs to the ERROR, WARNING, and INFO logs, offsetting the caller's stack frame by 'depth'. Passing an empty string for `format` causes this method to naturally format `args`.

func Fatal

func Fatal(args ...interface{})

Fatal logs to the INFO, WARNING, ERROR, and FATAL logs, including a stack trace of all running goroutines, then calls os.Exit(255). Arguments are handled in the manner of fmt.Print; a newline is appended.

func FatalOnPanic

func FatalOnPanic()

FatalOnPanic recovers from a panic and exits the process with a Fatal log. This is useful for avoiding a panic being caught through a CGo exported function or preventing HTTP handlers from recovering panics and ignoring them.

func Fatalc

func Fatalc(ctx context.Context, format string, args ...interface{})

Fatalc logs to the INFO, WARNING, ERROR, and FATAL logs, including a stack trace of all running goroutines, then calls os.Exit(255). It extracts values from the context using the Field keys specified in this package and logs them along with the given message and any additional pairs specified as consecutive elements in kvs.

func Fatalf

func Fatalf(format string, args ...interface{})

Fatalf logs to the INFO, WARNING, ERROR, and FATAL logs, including a stack trace of all running goroutines, then calls os.Exit(255). Arguments are handled in the manner of fmt.Printf; a newline is appended.

func FatalfDepth

func FatalfDepth(depth int, format string, args ...interface{})

FatalfDepth logs to the INFO, WARNING, ERROR, and FATAL logs, including a stack trace of all running goroutines, then calls os.Exit(255), offsetting the caller's stack frame by 'depth'. Passing an empty string for `format` causes this method to naturally format `args`.

func Flush

func Flush()

Flush flushes all pending log I/O.

func GetLogReader

func GetLogReader(filename string, restricted bool) (io.ReadCloser, error)

GetLogReader returns a reader for the specified filename. In restricted mode, the filename must be the base name of a file in this process's log directory (this is safe for cases when the filename comes from external sources, such as the admin UI via HTTP). In unrestricted mode any path is allowed, with the added feature that relative paths will be searched in both the current directory and this process's log directory.

func Info

func Info(args ...interface{})

Info logs to the INFO log. Arguments are handled in the manner of fmt.Print; a newline is appended.

func Infoc

func Infoc(ctx context.Context, format string, args ...interface{})

Infoc logs to the WARNING and INFO logs. It extracts values from the context using the Field keys specified in this package and logs them along with the given message and any additional pairs specified as consecutive elements in kvs.

func Infof

func Infof(format string, args ...interface{})

Infof logs to the INFO log. Don't use it; use Info or Infoc instead. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func InfofDepth

func InfofDepth(depth int, format string, args ...interface{})

InfofDepth logs to the INFO log, offsetting the caller's stack frame by 'depth'. Passing an empty string for `format` causes this method to naturally format `args`.

func NewStdLogger

func NewStdLogger(severity Severity) *stdLog.Logger

NewStdLogger creates a *stdLog.Logger that forwards messages to the Google logs for the specified severity.

func Trace

func Trace(ctx context.Context, msg string)

Trace looks for an opentracing.Trace in the context and logs the given message to it on success.

func V

func V(level level) bool

V returns true if the logging verbosity is set to the specified level or higher.

func VDepth

func VDepth(level level, depth int) bool

VDepth reports whether verbosity at the call site is at least the requested level.

func Warning

func Warning(args ...interface{})

Warning logs to the WARNING and INFO logs. Warningf logs to the WARNING and INFO logs. Don't use it; use Warning or Arguments are handled in the manner of fmt.Print; a newline is appended.

func Warningc

func Warningc(ctx context.Context, format string, args ...interface{})

Warningc logs to the WARNING and INFO logs. It extracts values from the context using the Field keys specified in this package and logs them along with the given message and any additional pairs specified as consecutive elements in kvs.

func Warningf

func Warningf(format string, args ...interface{})

Warningf logs to the WARNING and INFO logs. Don't use it; use Warning or Warningc instead. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func WarningfDepth

func WarningfDepth(depth int, format string, args ...interface{})

WarningfDepth logs to the WARNING and INFO logs, offsetting the caller's stack frame by 'depth'. Passing an empty string for `format` causes this method to naturally format `args`.

Types

type Entry

type Entry struct {
	Severity int    `json:"severity"` // Log message severity.
	Time     int64  `json:"time"`     // Time, measured in nanoseconds since the epoch.
	File     string `json:"file"`     // File which generated log statement.
	Line     int    `json:"line"`     // Line in file which generated log statement.
	// TODO(pmattis): The json output should be called `message` as well. Need to
	// fix the UI.
	Message string `json:"format"` // Log message.
}

Entry represents a cockroach structured log entry.

func FetchEntriesFromFiles

func FetchEntriesFromFiles(severity Severity, startTimestamp, endTimestamp int64, maxEntries int,
	pattern *regexp.Regexp) ([]Entry, error)

FetchEntriesFromFiles fetches all available log entires on disk that match the log 'severity' (or worse) and are between the 'startTimestamp' and 'endTimestamp'. It will stop reading new files if the number of entries exceeds 'maxEntries'. Log entries are further filtered by the regexp 'pattern' if provided. The logs entries are returned in reverse chronological order.

type EntryDecoder

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

EntryDecoder reads successive encoded log entries from the input buffer. Each entry is preceded by a single big-ending uint32 describing the next entry's length.

func NewEntryDecoder

func NewEntryDecoder(in io.Reader) *EntryDecoder

NewEntryDecoder creates a new instance of EntryDecoder.

func (*EntryDecoder) Decode

func (d *EntryDecoder) Decode(entry *Entry) error

Decode decodes the next log entry into the provided protobuf message.

type FileDetails

type FileDetails struct {
	Program  string
	Host     string
	UserName string
	Severity Severity
	Time     time.Time
	PID      uint
}

A FileDetails holds all of the particulars that can be parsed by the name of a log file.

type FileInfo

type FileInfo struct {
	Name         string // base name
	SizeBytes    int64
	ModTimeNanos int64 // most recent mode time in unix nanos
	Details      FileDetails
}

A FileInfo holds the filename and size of a log file.

func ListLogFiles

func ListLogFiles() ([]FileInfo, error)

ListLogFiles returns a slice of FileInfo structs for each log file on the local node, in any of the configured log directories.

type Severity

type Severity int32 // sync/atomic int32

Severity identifies the sort of log: info, warning etc. It also implements the flag.Value interface. The -stderrthreshold flag is of type Severity and should be modified only through the flag.Value interface. The values match the corresponding constants in C++.

const (
	InfoLog Severity = iota
	WarningLog
	ErrorLog
	FatalLog
	NumSeverity = 4
)

These constants identify the log levels in order of increasing Severity. A message written to a high-Severity log file is also written to each lower-Severity log file.

func SeverityByName

func SeverityByName(s string) (Severity, bool)

SeverityByName attempts to parse the passed in string into a severity. (i.e. ERROR, INFO). If it succeeds, the returned bool is set to true.

func (*Severity) Name

func (s *Severity) Name() string

Name returns the string representation of the severity (i.e. ERROR, INFO).

func (*Severity) Set

func (s *Severity) Set(value string) error

Set is part of the flag.Value interface.

func (*Severity) String

func (s *Severity) String() string

String is part of the flag.Value interface.