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=LEVEL Logs are written to standard error as well as to files. Entries with severity below LEVEL are not written to stderr. "true" and "false" are also supported (everything / nothing). --log-dir="..." Log files will be written to this directory instead of the default target directory. --log-file-verbosity=LEVEL Entries with severity below LEVEL are not written to the log file. "true" and "false" are also supported (everything / nothing). --log-file-max-size=N Log files are rotated after reaching that size. --log-dir-max-size=N Log files are removed after log directory reaches that size. 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". Package log is a generated protocol buffer package. It is generated from these files: cockroach/pkg/util/log/log.proto It has these top-level messages: Entry FileDetails FileInfo
Index ¶
- Variables
- func DirSet() bool
- func ErrEvent(ctx context.Context, msg string)
- func ErrEventf(ctx context.Context, format string, args ...interface{})
- func Error(ctx context.Context, args ...interface{})
- func Errorf(ctx context.Context, format string, args ...interface{})
- func ErrorfDepth(ctx context.Context, depth int, format string, args ...interface{})
- func Event(ctx context.Context, msg string)
- func Eventf(ctx context.Context, format string, args ...interface{})
- func Fatal(ctx context.Context, args ...interface{})
- func FatalOnPanic()
- func Fatalf(ctx context.Context, format string, args ...interface{})
- func FatalfDepth(ctx context.Context, depth int, format string, args ...interface{})
- func FinishEventLog(ctx context.Context)
- func Flush()
- func GetLogReader(filename string, restricted bool) (io.ReadCloser, error)
- func HasSpanOrEvent(ctx context.Context) bool
- func Info(ctx context.Context, args ...interface{})
- func Infof(ctx context.Context, format string, args ...interface{})
- func InfofDepth(ctx context.Context, depth int, format string, args ...interface{})
- func LoggingToStderr(s Severity) bool
- func MakeMessage(ctx context.Context, format string, args []interface{}) string
- func NewStdLogger(severity Severity) *stdLog.Logger
- func RecoverAndReportPanic(ctx context.Context)
- func ReportPanic(ctx context.Context, r interface{}, depth int)
- func SetExitFunc(f func(int))
- func SetSync(sync bool)
- func SetupCrashReporter(ctx context.Context, cmd string)
- func Shout(ctx context.Context, sev Severity, args ...interface{})
- func StartGCDaemon()
- func V(level level) bool
- func VDepth(level level, depth int) bool
- func VEvent(ctx context.Context, level level, msg string)
- func VEventf(ctx context.Context, level level, format string, args ...interface{})
- func Warning(ctx context.Context, args ...interface{})
- func Warningf(ctx context.Context, format string, args ...interface{})
- func WarningfDepth(ctx context.Context, depth int, format string, args ...interface{})
- func WithEventLog(ctx context.Context, family, title string) context.Context
- func WithLogTag(ctx context.Context, name string, value interface{}) context.Context
- func WithLogTagInt(ctx context.Context, name string, value int) context.Context
- func WithLogTagInt64(ctx context.Context, name string, value int64) context.Context
- func WithLogTagStr(ctx context.Context, name string, value string) context.Context
- func WithNoEventLog(ctx context.Context) context.Context
- type AmbientContext
- func (ac *AmbientContext) AddLogTag(name string, value interface{})
- func (ac *AmbientContext) AddLogTagInt(name string, value int)
- func (ac *AmbientContext) AddLogTagInt64(name string, value int64)
- func (ac *AmbientContext) AddLogTagStr(name string, value string)
- func (ac *AmbientContext) AnnotateCtx(ctx context.Context) context.Context
- func (ac *AmbientContext) AnnotateCtxWithSpan(ctx context.Context, opName string) (context.Context, opentracing.Span)
- func (ac *AmbientContext) FinishEventLog()
- func (ac *AmbientContext) ResetAndAnnotateCtx(ctx context.Context) context.Context
- func (ac *AmbientContext) SetEventLog(family, title string)
- type Entry
- func (*Entry) Descriptor() ([]byte, []int)
- func (e Entry) Format(w io.Writer) error
- func (m *Entry) Marshal() (dAtA []byte, err error)
- func (m *Entry) MarshalTo(dAtA []byte) (int, error)
- func (*Entry) ProtoMessage()
- func (m *Entry) Reset()
- func (m *Entry) Size() (n int)
- func (m *Entry) String() string
- func (m *Entry) Unmarshal(dAtA []byte) error
- type EntryDecoder
- type FileDetails
- func (*FileDetails) Descriptor() ([]byte, []int)
- func (m *FileDetails) Marshal() (dAtA []byte, err error)
- func (m *FileDetails) MarshalTo(dAtA []byte) (int, error)
- func (*FileDetails) ProtoMessage()
- func (m *FileDetails) Reset()
- func (m *FileDetails) Size() (n int)
- func (m *FileDetails) String() string
- func (m *FileDetails) Unmarshal(dAtA []byte) error
- type FileInfo
- func (*FileInfo) Descriptor() ([]byte, []int)
- func (m *FileInfo) Marshal() (dAtA []byte, err error)
- func (m *FileInfo) MarshalTo(dAtA []byte) (int, error)
- func (*FileInfo) ProtoMessage()
- func (m *FileInfo) Reset()
- func (m *FileInfo) Size() (n int)
- func (m *FileInfo) String() string
- func (m *FileInfo) Unmarshal(dAtA []byte) error
- type Safe
- type Severity
- type TestLogScope
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidLengthLog = fmt.Errorf("proto: negative length found during unmarshaling") ErrIntOverflowLog = fmt.Errorf("proto: integer overflow") )
var DiagnosticsReportingEnabled = settings.RegisterBoolSetting( "diagnostics.reporting.enabled", "enable reporting diagnostic metrics to cockroach labs", false, )
DiagnosticsReportingEnabled wraps "diagnostics.reporting.enabled".
"diagnostics.reporting.enabled" enables reporting of metrics related to a node's storage (number, size and health of ranges) back to CockroachDB. Collecting this data from production clusters helps us understand and improve how our storage systems behave in real-world use cases.
Note: while the setting itself is actually defined with a default value of `false`, it is usually automatically set to `true` when a cluster is created (or is migrated from a earlier beta version). This can be prevented with the env var COCKROACH_SKIP_ENABLING_DIAGNOSTIC_REPORTING.
Doing this, rather than just using a default of `true`, means that a node will not errantly send a report using a default before loading settings.
var LogFileMaxSize int64 = 10 << 20 // 10MiB
LogFileMaxSize is the maximum size of a log file in bytes.
var LogFilesCombinedMaxSize = LogFileMaxSize * 10 // 100MiB
LogFilesCombinedMaxSize is the maximum total size in bytes for log files. Note that this is only checked when log files are created, so the total size of log files per severity might temporarily be up to LogFileMaxSize larger.
var OrigStderr = func() *os.File { fd, err := dupFD(os.Stderr.Fd()) if err != nil { panic(err) } return os.NewFile(fd, os.Stderr.Name()) }()
OrigStderr points to the original stderr stream.
var Severity_name = map[int32]string{
0: "UNKNOWN",
1: "INFO",
2: "WARNING",
3: "ERROR",
4: "FATAL",
5: "NONE",
6: "DEFAULT",
}
var Severity_value = map[string]int32{
"UNKNOWN": 0,
"INFO": 1,
"WARNING": 2,
"ERROR": 3,
"FATAL": 4,
"NONE": 5,
"DEFAULT": 6,
}
Functions ¶
func DirSet ¶
func DirSet() bool
DirSet returns true of the log directory has been changed from its default.
func ErrEvent ¶
ErrEvent looks for an opentracing.Trace in the context and logs the given message to it. If no Trace is found, it looks for an EventLog in the context and logs the message to it (as an error). If neither is found, does nothing.
func ErrEventf ¶
ErrEventf looks for an opentracing.Trace in the context and formats and logs the given message to it. If no Trace is found, it looks for an EventLog in the context and formats and logs the message to it (as an error). If neither is found, does nothing.
func Error ¶
Error logs to the ERROR, WARNING, and INFO logs. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Print; a newline is appended.
func Errorf ¶
Errorf logs to the ERROR, WARNING, and INFO logs. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func ErrorfDepth ¶
ErrorfDepth logs to the ERROR, WARNING, and INFO logs, offsetting the caller's stack frame by 'depth'. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func Event ¶
Event looks for an opentracing.Trace in the context and logs the given message to it. If no Trace is found, it looks for an EventLog in the context and logs the message to it. If neither is found, does nothing.
func Eventf ¶
Eventf looks for an opentracing.Trace in the context and formats and logs the given message to it. If no Trace is found, it looks for an EventLog in the context and logs the message to it. If neither is found, does nothing.
func Fatal ¶
Fatal logs to the INFO, WARNING, ERROR, and FATAL logs, including a stack trace of all running goroutines, then calls os.Exit(255). It extracts log tags from the context and logs them along with the given message. 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 Fatalf ¶
Fatalf logs to the INFO, WARNING, ERROR, and FATAL logs, including a stack trace of all running goroutines, then calls os.Exit(255). It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func FatalfDepth ¶
FatalfDepth logs to the INFO, WARNING, ERROR, and FATAL logs (offsetting the caller's stack frame by 'depth'), including a stack trace of all running goroutines, then calls os.Exit(255). It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func FinishEventLog ¶
FinishEventLog closes the event log in the context (see WithEventLog). Concurrent and subsequent calls to record events are allowed.
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, relative to the current directory, with the added feature that simple (base name) file names will be searched in this process's log directory if not found in the current directory.
func HasSpanOrEvent ¶
HasSpanOrEvent returns true if the context has a span or event that should be logged to.
func Info ¶
Info logs to the INFO log. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Print; a newline is appended.
func Infof ¶
Infof logs to the INFO log. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func InfofDepth ¶
InfofDepth logs to the INFO log, offsetting the caller's stack frame by 'depth'. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func LoggingToStderr ¶
LoggingToStderr returns true if log messages of the given severity are visible on stderr.
func MakeMessage ¶
MakeMessage creates a structured log entry.
func NewStdLogger ¶
NewStdLogger creates a *stdLog.Logger that forwards messages to the CockroachDB logs with the specified severity.
func RecoverAndReportPanic ¶
RecoverAndReportPanic can be invoked on goroutines that run with stderr redirected to logs to ensure the user gets informed on the real stderr a panic has occurred.
func ReportPanic ¶
ReportPanic reports a panic has occurred on the real stderr.
func SetExitFunc ¶
func SetExitFunc(f func(int))
SetExitFunc allows setting a function that will be called to exit the process when a Fatal message is generated.
func SetupCrashReporter ¶
SetupCrashReporter sets the crash reporter info.
func Shout ¶
Shout logs to the specified severity's log, and also to the real stderr if logging is currently redirected to a file.
func StartGCDaemon ¶
func StartGCDaemon()
StartGCDaemon starts the log file GC -- this must be called after command-line parsing has completed so that no data is lost when the user configures larger max sizes than the defaults.
func V ¶
func V(level level) bool
V returns true if the logging verbosity is set to the specified level or higher.
func VEvent ¶
VEvent either logs a message to the log files (which also outputs to the active trace or event log) or to the trace/event log alone, depending on whether the specified verbosity level is active.
func VEventf ¶
VEventf either logs a message to the log files (which also outputs to the active trace or event log) or to the trace/event log alone, depending on whether the specified verbosity level is active.
func Warning ¶
Warning logs to the WARNING and INFO logs. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Print; a newline is appended.
func Warningf ¶
Warningf logs to the WARNING and INFO logs. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func WarningfDepth ¶
WarningfDepth logs to the WARNING and INFO logs, offsetting the caller's stack frame by 'depth'. It extracts log tags from the context and logs them along with the given message. Arguments are handled in the manner of fmt.Printf; a newline is appended.
func WithEventLog ¶
WithEventLog creates and embeds a trace.EventLog in the context, causing future logging and event calls to go to the EventLog. The current context must not have an existing open span.
func WithLogTag ¶
WithLogTag returns a context (derived from the given context) which when used with a logging function results in the given name and value being printed in the message.
The value is stored and passed to fmt.Fprint when the log message is constructed. A fmt.Stringer can be passed which allows the value to be "dynamic".
If the value is nil, just the name shows up.
func WithLogTagInt ¶
WithLogTagInt is a variant of WithLogTag that avoids the allocation associated with boxing the value in an interface{}.
func WithLogTagInt64 ¶
WithLogTagInt64 is a variant of WithLogTag that avoids the allocation associated with boxing the value in an interface{}.
func WithLogTagStr ¶
WithLogTagStr is a variant of WithLogTag that avoids the allocation associated with boxing the value in an interface{}.
Types ¶
type AmbientContext ¶
type AmbientContext struct { // Tracer is used to open spans (see AnnotateCtxWithSpan). Tracer opentracing.Tracer // contains filtered or unexported fields }
AmbientContext is a helper type used to "annotate" context.Contexts with log tags and a Tracer or EventLog. It is intended to be embedded into various server components.
Example:
type SomeServer struct { log.AmbientContext ... } ac := AmbientContext{Tracer: tracing.NewTracer()} ac.AddLogTag("n", 1) s := &SomeServer{ AmbientContext: ac ... } // on an operation with context ctx ctx = s.AnnotateCtx(ctx) ... // run a worker s.stopper.RunWorker(func() { ctx := s.AnnotateCtx(context.Background()) ... }) // start a background operation ctx, span := s.AnnotateCtxWithSpan(context.Background(), "some-op") defer span.Finish() ...
func (*AmbientContext) AddLogTag ¶
func (ac *AmbientContext) AddLogTag(name string, value interface{})
AddLogTag adds a tag; see WithLogTag.
func (*AmbientContext) AddLogTagInt ¶
func (ac *AmbientContext) AddLogTagInt(name string, value int)
AddLogTagInt adds an integer tag; see WithLogTagInt.
func (*AmbientContext) AddLogTagInt64 ¶
func (ac *AmbientContext) AddLogTagInt64(name string, value int64)
AddLogTagInt64 adds an integer tag; see WithLogTagInt64.
func (*AmbientContext) AddLogTagStr ¶
func (ac *AmbientContext) AddLogTagStr(name string, value string)
AddLogTagStr adds a string tag; see WithLogTagStr.
func (*AmbientContext) AnnotateCtx ¶
func (ac *AmbientContext) AnnotateCtx(ctx context.Context) context.Context
AnnotateCtx annotates a given context with the information in AmbientContext:
- the EventLog is embedded in the context if the context doesn't already have en event log or an open trace.
- the log tags in AmbientContext are added (if ctx doesn't already have them). If the tags already exist, the values from the AmbientContext overwrite the existing values, but the order of the tags might change.
For background operations, context.Background() should be passed; however, in that case it is strongly recommended to open a span if possible (using AnnotateCtxWithSpan).
func (*AmbientContext) AnnotateCtxWithSpan ¶
func (ac *AmbientContext) AnnotateCtxWithSpan( ctx context.Context, opName string, ) (context.Context, opentracing.Span)
AnnotateCtxWithSpan annotates the given context with the information in AmbientContext (see AnnotateCtx) and opens a span.
If the given context has a span, the new span is a child of that span. Otherwise, the Tracer in AmbientContext is used to create a new root span.
The caller is responsible for closing the span (via Span.Finish).
func (*AmbientContext) FinishEventLog ¶
func (ac *AmbientContext) FinishEventLog()
FinishEventLog closes the event log. Concurrent and subsequent calls to record events from contexts that use this event log embedded are allowed.
func (*AmbientContext) ResetAndAnnotateCtx ¶
func (ac *AmbientContext) ResetAndAnnotateCtx(ctx context.Context) context.Context
ResetAndAnnotateCtx annotates a given context with the information in AmbientContext, but unlike AnnotateCtx, it drops all log tags in the supplied context before adding the ones from the AmbientContext.
func (*AmbientContext) SetEventLog ¶
func (ac *AmbientContext) SetEventLog(family, title string)
SetEventLog sets up an event log. Annotated contexts log into this event log (unless there's an open Span).
type Entry ¶
type Entry struct { Severity Severity `protobuf:"varint,1,opt,name=severity,proto3,enum=cockroach.util.log.Severity" json:"severity,omitempty"` // Nanoseconds since the epoch. Time int64 `protobuf:"varint,2,opt,name=time,proto3" json:"time,omitempty"` Goroutine int64 `protobuf:"varint,6,opt,name=goroutine,proto3" json:"goroutine,omitempty"` File string `protobuf:"bytes,3,opt,name=file,proto3" json:"file,omitempty"` Line int64 `protobuf:"varint,4,opt,name=line,proto3" json:"line,omitempty"` Message string `protobuf:"bytes,5,opt,name=message,proto3" json:"message,omitempty"` }
Entry represents a cockroach structured log entry.
func FetchEntriesFromFiles ¶
func FetchEntriesFromFiles( startTimestamp, endTimestamp int64, maxEntries int, pattern *regexp.Regexp, ) ([]Entry, error)
FetchEntriesFromFiles fetches all available log entries on disk that 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.
func (*Entry) Descriptor ¶
func (*Entry) ProtoMessage ¶
func (*Entry) ProtoMessage()
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 `protobuf:"bytes,1,opt,name=program,proto3" json:"program,omitempty"` Host string `protobuf:"bytes,2,opt,name=host,proto3" json:"host,omitempty"` UserName string `protobuf:"bytes,3,opt,name=user_name,json=userName,proto3" json:"user_name,omitempty"` Severity Severity `protobuf:"varint,4,opt,name=severity,proto3,enum=cockroach.util.log.Severity" json:"severity,omitempty"` Time int64 `protobuf:"varint,5,opt,name=time,proto3" json:"time,omitempty"` PID int64 `protobuf:"varint,6,opt,name=pid,proto3" json:"pid,omitempty"` }
A FileDetails holds all of the particulars that can be parsed by the name of a log file.
func (*FileDetails) Descriptor ¶
func (*FileDetails) Descriptor() ([]byte, []int)
func (*FileDetails) Marshal ¶
func (m *FileDetails) Marshal() (dAtA []byte, err error)
func (*FileDetails) ProtoMessage ¶
func (*FileDetails) ProtoMessage()
func (*FileDetails) Reset ¶
func (m *FileDetails) Reset()
func (*FileDetails) Size ¶
func (m *FileDetails) Size() (n int)
func (*FileDetails) String ¶
func (m *FileDetails) String() string
func (*FileDetails) Unmarshal ¶
func (m *FileDetails) Unmarshal(dAtA []byte) error
type FileInfo ¶
type FileInfo struct { Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` SizeBytes int64 `protobuf:"varint,2,opt,name=size_bytes,json=sizeBytes,proto3" json:"size_bytes,omitempty"` ModTimeNanos int64 `protobuf:"varint,3,opt,name=mod_time_nanos,json=modTimeNanos,proto3" json:"mod_time_nanos,omitempty"` Details FileDetails `protobuf:"bytes,4,opt,name=details" json:"details"` }
func ListLogFiles ¶
ListLogFiles returns a slice of FileInfo structs for each log file on the local node, in any of the configured log directories.
func (*FileInfo) Descriptor ¶
func (*FileInfo) ProtoMessage ¶
func (*FileInfo) ProtoMessage()
type Safe ¶
type Safe struct {
V interface{}
}
A Safe panic can be reported verbatim, i.e. does not leak information.
TODO(dt): flesh out, see #15892.
type Severity ¶
type Severity int32
const ( Severity_UNKNOWN Severity = 0 Severity_INFO Severity = 1 Severity_WARNING Severity = 2 Severity_ERROR Severity = 3 Severity_FATAL Severity = 4 // NONE is used to specify when no messages // should be printed to the log file or stderr. Severity_NONE Severity = 5 // DEFAULT is the end sentinel. It is used during command-line // handling to indicate that another value should be replaced instead // (depending on which command is being run); see cli/flags.go for // details. Severity_DEFAULT Severity = 6 )
func SeverityByName ¶
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) EnumDescriptor ¶
type TestLogScope ¶
type TestLogScope struct {
// contains filtered or unexported fields
}
TestLogScope represents the lifetime of a logging output. It ensures that the log files are stored in a directory specific to a test, and asserts that logging output is not written to this directory beyond the lifetime of the scope.
func Scope ¶
func Scope(t tShim) *TestLogScope
Scope creates a TestLogScope which corresponds to the lifetime of a logging directory. The logging directory is named after the calling test. It also disables logging to stderr for severity levels below ERROR.
func ScopeWithoutShowLogs ¶
func ScopeWithoutShowLogs(t tShim) *TestLogScope
ScopeWithoutShowLogs ignores the -show-logs flag and should be used for tests that require the logs go to files.
func (*TestLogScope) Close ¶
func (l *TestLogScope) Close(t tShim)
Close cleans up a TestLogScope. The directory and its contents are deleted, unless the test has failed and the directory is non-empty.