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.
Log output is encoded using the proto.LogEntry message format. Each log entry is preceded by a 32-bit encoded length. Use the log command to display logs in human-readable form:
% cockroach log <log1> [<log2> ...]
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=false 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 AddStructured(ctx context.Context, s severity, depth int, format string, args []interface{})
- func Caller(depth int) (string, int)
- func CopyStandardLogTo(name string)
- func DisableLogFileOutput()
- func EnableLogFileOutput(dir string)
- func Error(args ...interface{})
- func ErrorDepth(depth int, args ...interface{})
- func Errorc(ctx context.Context, format string, args ...interface{})
- func Errorf(format string, args ...interface{})
- func Fatal(args ...interface{})
- func FatalDepth(depth int, args ...interface{})
- func FatalOnPanic()
- func Fatalc(ctx context.Context, format string, args ...interface{})
- func Fatalf(format string, args ...interface{})
- func Flush()
- func GetLogReader(filename string, allowAbsolute bool) (io.ReadCloser, error)
- func Info(args ...interface{})
- func InfoDepth(depth int, args ...interface{})
- func Infoc(ctx context.Context, format string, args ...interface{})
- func Infof(format string, args ...interface{})
- func NewJSONEntryReader(reader io.Reader) io.Reader
- func NewTermEntryReader(reader io.Reader) io.Reader
- func V(level level) bool
- func VDepth(level level, depth int) bool
- func Warning(args ...interface{})
- func WarningDepth(depth int, args ...interface{})
- func Warningc(ctx context.Context, format string, args ...interface{})
- func Warningf(format string, args ...interface{})
- type EntryDecoder
- type Field
- type FileInfo
Constants ¶
This section is empty.
Variables ¶
var MaxSize uint64 = 1024 * 1024 * 1800
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 ¶
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 AddStructured ¶
AddStructured creates a structured log entry to be written to the specified facility of the logger.
func Caller ¶
Caller returns the file and line of the Caller or, in case of error, the placeholder ('???', 1).
func CopyStandardLogTo ¶
func CopyStandardLogTo(name string)
CopyStandardLogTo arranges for messages written to the Go "log" package's default logs to also appear in the Google logs for the named and lower severities. Subsequent changes to the standard log's default output location or format may break this behavior.
Valid names are "INFO", "WARNING", "ERROR", and "FATAL". If the name is not recognized, CopyStandardLogTo panics.
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 ErrorDepth ¶
func ErrorDepth(depth int, args ...interface{})
ErrorDepth logs to the ERROR, WARNING, and INFO logs, offsetting the caller's stack frame by 'depth'.
func Errorc ¶
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 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 FatalDepth ¶
func FatalDepth(depth int, args ...interface{})
FatalDepth 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'.
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 ¶
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 GetLogReader ¶
func GetLogReader(filename string, allowAbsolute bool) (io.ReadCloser, error)
GetLogReader returns a reader for the specified filename. Any external requests (say from the admin UI via HTTP) must specify allowAbsolute as false to prevent leakage of non-log files. Absolute filenames are allowed for the case of the cockroach "log" command, which provides human readable output from an arbitrary file, and is intended to be run locally in a terminal.
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 InfoDepth ¶
func InfoDepth(depth int, args ...interface{})
InfoDepth logs to the INFO log, offsetting the caller's stack frame by 'depth'.
func Infoc ¶
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 NewJSONEntryReader ¶
NewJSONEntryReader returns a reader for log files containing encoded entries in JSON format.
func NewTermEntryReader ¶
NewTermEntryReader returns a reader for log files containing encoded entries for use from a terminal. If the --color flag is set, and the terminal supports colors, then log output will be colorized.
func V ¶
func V(level level) bool
V returns true if the logging verbosity is set to the specified level or higher.
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 WarningDepth ¶
func WarningDepth(depth int, args ...interface{})
WarningDepth logs to the WARNING and INFO logs, offsetting the caller's stack frame by 'depth'.
Types ¶
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.
type Field ¶
type Field int
A Field is an integer used to enumerate allowed field names in structured log output.
type FileInfo ¶
type FileInfo struct {
Name string // base name
SizeBytes int64
ModTimeNanos int64 // most recent mode time in unix nanos
}
A FileInfo holds the filename and size of a log file.
func ListLogFiles ¶
ListLogFiles returns a slice of FileInfo structs for each log file on the local node, in any of the configured log directories.
Source Files