cockroach: github.com/cockroachdb/cockroach/pkg/util/log Index | Files | Directories

package log

import "github.com/cockroachdb/cockroach/pkg/util/log"

Package log implements logging. There are three logging styles: named, V-style, events.

Named Functions

The functions Info, Warning, Error, and Fatal log their arguments at the specified level. All include formatting variants like Infof.

Examples:

log.Info(ctx, "Prepare to repel boarders")
log.Fatal(ctx, "Initialization failed", err)
log.Infof(ctx, "client error: %s", err)

V-Style

The V functions can be used to selectively enable logging at a call site. Invoking the binary with --vmodule=*=N will enable V functions at level N or higher. Invoking the binary with --vmodule="glob=N" will enable V functions at level N or higher with a filename matching glob.

Examples:

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

Events

The Event functions log messages to an existing trace if one exists. The VEvent functions logs the message to a trace and also the log file based on the V level.

Examples:

log.VEventf(ctx, 2, "client error; %s", err)

Output

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 util/log/logflags package; 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 by the main logger
  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-group-max-size=N
  Log files are removed after the total size of all files generated
  by one logger reaches that size.

Other flags provide aids to debugging.

--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".

Protobuf

Autogenerated:

Index

Package Files

ambient_context.go clog.go crash_reporting.go doc.go every_n.go exit_override.go file.go flags.go get_stacks.go intercept.go log.go log.pb.go log_bridge.go log_buffer.go log_entry.go log_flush.go log_gc.go loggers.go no_file_log_scope.go redact.go secondary_log.go severity.go stderr_redirect.go stderr_redirect_unix.go structured.go sync_buffer.go test_log_scope.go trace.go tracebacks.go vmodule.go

Constants

const FileNamePattern = `(?P<program>[^/.]+)\.(?P<host>[^/\.]+)\.` +
    `(?P<user>[^/\.]+)\.(?P<ts>[^/\.]+)\.(?P<pid>\d+)\.log`

FileNamePattern matches log files to avoid exposing non-log files accidentally and it splits the details of the filename into groups for easy parsing. The log file format is

{program}.{host}.{username}.{timestamp}.{pid}.log
cockroach.Brams-MacBook-Pro.bram.2015-06-09T16-10-48Z.30209.log

All underscore in process, host and username are escaped to double underscores and all periods are escaped to an underscore. For compatibility with Windows filenames, all colons from the timestamp (RFC3339) are converted from underscores (see FileTimePattern). Note this pattern is unanchored and becomes anchored through its use in LogFilePattern.

const FilePattern = "^(?:.*/)?" + FileNamePattern + "$"

FilePattern matches log file paths.

const FileTimeFormat = "2006-01-02T15_04_05Z07:00"

FileTimeFormat is RFC3339 with the colons replaced with underscores. It is the format used for timestamps in log file names. This removal of colons creates log files safe for Windows file systems.

const MessageTimeFormat = "060102 15:04:05.999999"

MessageTimeFormat is the format of the timestamp in log message headers as used in time.Parse and time.Format.

Variables

var (

    // 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.
    DiagnosticsReportingEnabled = settings.RegisterPublicBoolSetting(
        "diagnostics.reporting.enabled",
        "enable reporting diagnostic metrics to cockroach labs",
        false,
    )

    // CrashReports wraps "diagnostics.reporting.send_crash_reports".
    CrashReports = settings.RegisterBoolSetting(
        "diagnostics.reporting.send_crash_reports",
        "send crash and panic reports",
        true,
    )

    // PanicOnAssertions wraps "debug.panic_on_failed_assertions"
    PanicOnAssertions = settings.RegisterBoolSetting(
        "debug.panic_on_failed_assertions",
        "panic when an assertion fails rather than reporting",
        false,
    )

    // ReportSensitiveDetails enables reporting of unanonymized data.
    //
    // This should not be used by anyone unwilling to share the whole cluster
    // data with Cockroach Labs and various cloud services.
    ReportSensitiveDetails = envutil.EnvOrDefaultBool("COCKROACH_REPORT_SENSITIVE_DETAILS", false)
)
var (
    ErrInvalidLengthLog = fmt.Errorf("proto: negative length found during unmarshaling")
    ErrIntOverflowLog   = fmt.Errorf("proto: integer overflow")
)
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 generated by one logger. Note that this is only checked when log files are created, so the total size of log files 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 Safe = redact.Safe

Safe constructs a SafeFormatter / SafeMessager. This is obsolete. Use redact.Safe directly. TODO(knz): Remove this.

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

func DirSet Uses

func DirSet() bool

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

func DisableTracebacks Uses

func DisableTracebacks() func()

DisableTracebacks turns off tracebacks for log.Fatals. Returns a function that sets the traceback settings back to where they were. Only intended for use by tests.

func DumpStacks Uses

func DumpStacks(ctx context.Context)

DumpStacks produces a dump of the stack traces in the logging output.

func Error Uses

func Error(ctx context.Context, msg string)

Error logs to the ERROR, WARNING, and INFO logs. It extracts log tags from the context and logs them along with the given message.

func Errorf Uses

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

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 Uses

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

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 Uses

func Event(ctx context.Context, msg string)

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 Uses

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

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 ExpensiveLogEnabled Uses

func ExpensiveLogEnabled(ctx context.Context, level Level) bool

ExpensiveLogEnabled is used to test whether effort should be used to produce log messages whose construction has a measurable cost. It returns true if either the current context is recording the trace, or if the caller's verbosity is above level.

NOTE: This doesn't take into consideration whether tracing is generally enabled or whether a trace.EventLog or a trace.Trace (i.e. sp.netTr) is attached to ctx. In particular, if some OpenTracing collection is enabled (e.g. LightStep), that, by itself, does NOT cause the expensive messages to be enabled. "SET tracing" and friends, on the other hand, does cause these messages to be enabled, as it shows that a user has expressed particular interest in a trace.

Usage:

if ExpensiveLogEnabled(ctx, 2) {

msg := constructExpensiveMessage()
log.VEventf(ctx, 2, msg)

}

func Fatal Uses

func Fatal(ctx context.Context, msg string)

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.

func FatalChan Uses

func FatalChan() <-chan struct{}

FatalChan is closed when Fatal is called. This can be used to make the process stop handling requests while the final log messages and crash report are being written.

func FatalOnPanic Uses

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 Uses

func Fatalf(ctx context.Context, 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). 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 Uses

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

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 Uses

func FinishEventLog(ctx context.Context)

FinishEventLog closes the event log in the context (see WithEventLog). Concurrent and subsequent calls to record events are allowed.

func Flush Uses

func Flush()

Flush explicitly flushes all pending log I/O. See also flushDaemon() that manages background (asynchronous) flushes, and signalFlusher() that manages flushes in reaction to a user signal.

func FormatWithContextTags Uses

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

FormatWithContextTags formats the string and prepends the context tags.

Redaction markers are *not* inserted. The resulting string is generally unsafe for reporting.

func GetLogReader Uses

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.

TODO(knz): make this work for secondary loggers too.

func HasSpanOrEvent Uses

func HasSpanOrEvent(ctx context.Context) bool

HasSpanOrEvent returns true if the context has a span or event that should be logged to.

func Info Uses

func Info(ctx context.Context, msg string)

Info logs to the INFO log. It extracts log tags from the context and logs them along with the given message.

func Infof Uses

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

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 Uses

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

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 Intercept Uses

func Intercept(ctx context.Context, f InterceptorFn)

Intercept diverts log traffic to the given function `f`. When `f` is not nil, the logging package begins operating at full verbosity (i.e. `V(n) == true` for all `n`) but nothing will be printed to the logs. Instead, `f` is invoked for each log entry.

To end log interception, invoke `Intercept()` with `f == nil`. Note that interception does not terminate atomically, that is, the originally supplied callback may still be invoked after a call to `Intercept` with `f == nil`.

func IsActive Uses

func IsActive() (active bool, firstUse string)

IsActive returns true iff the main logger already has some events logged, or some secondary logger was created with configuration taken from the main logger.

This is used to assert that configuration is performed before logging has been used for the first time.

func LoggingToStderr Uses

func LoggingToStderr(s Severity) bool

LoggingToStderr returns true if log messages of the given severity sent to the main logger are also visible on stderr. This is used e.g. by the startup code to announce server details both on the external stderr and to the log file.

This is also the logic used by Shout calls.

func NewStdLogger Uses

func NewStdLogger(severity Severity, prefix string) *stdLog.Logger

NewStdLogger creates a *stdLog.Logger that forwards messages to the CockroachDB logs with the specified severity.

The prefix appears at the beginning of each generated log line.

func PanicAsError Uses

func PanicAsError(depth int, r interface{}) error

PanicAsError turns r into an error if it is not one already.

func RecoverAndReportNonfatalPanic Uses

func RecoverAndReportNonfatalPanic(ctx context.Context, sv *settings.Values)

RecoverAndReportNonfatalPanic is an alternative RecoverAndReportPanic that does not re-panic in Release builds.

func RecoverAndReportPanic Uses

func RecoverAndReportPanic(ctx context.Context, sv *settings.Values)

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 RegisterTagFn Uses

func RegisterTagFn(key string, value func(context.Context) string)

RegisterTagFn adds a function for tagging crash reports based on the context. This is intended to be called by other packages at init time.

func ReportOrPanic Uses

func ReportOrPanic(
    ctx context.Context, sv *settings.Values, format string, reportables ...interface{},
)

ReportOrPanic either reports an error to sentry, if run from a release binary, or panics, if triggered in tests. This is intended to be used for failing assertions which are recoverable but serious enough to report and to cause tests to fail.

Like SendCrashReport, the format string should not contain any sensitive data, and unsafe reportables will be redacted before reporting.

func ReportPanic Uses

func ReportPanic(ctx context.Context, sv *settings.Values, r interface{}, depth int)

ReportPanic reports a panic has occurred on the real stderr.

Note that ReportPanic() does not assume that the panic object will be left uncaught to terminate the process. For example, at the time of this writing, ReportPanic() is called from RecoverAndReportNonfatalPanic() above.

func ResetExitFunc Uses

func ResetExitFunc()

ResetExitFunc undoes any prior call to SetExitFunc.

func SendReport Uses

func SendReport(
    ctx context.Context,
    crashReportType ReportType,
    event *sentry.Event,
    extraDetails map[string]interface{},
)

SendReport uploads a detailed error report to sentry. Note that there can be at most one reportable object of each type in the report. For more messages, use extraDetails. The crashReportType parameter adds a tag to the event that shows if the cluster did indeed crash or not.

func SetClusterID Uses

func SetClusterID(clusterID string)

SetClusterID stores the Cluster ID for further reference.

TODO(knz): This should not be configured per-logger. See: https://github.com/cockroachdb/cockroach/issues/40983

func SetExitFunc Uses

func SetExitFunc(hideStack bool, f func(int))

SetExitFunc allows setting a function that will be called to exit the process when a Fatal message is generated. The supplied bool, if true, suppresses the stack trace, which is useful for test callers wishing to keep the logs reasonably clean.

Use ResetExitFunc() to reset.

func SetSync Uses

func SetSync(sync bool)

SetSync configures whether logging synchronizes all writes. This overrides the synchronization setting for both primary and secondary loggers. This is used e.g. in `cockroach start` when an error occurs, to ensure that all log writes from the point the error occurs are flushed to logs (in case the error degenerates into a panic / segfault on the way out).

func SetVModule Uses

func SetVModule(value string) error

SetVModule alters the vmodule logging level to the passed in value.

func SetupCrashReporter Uses

func SetupCrashReporter(ctx context.Context, cmd string)

SetupCrashReporter sets the crash reporter info.

func SetupRedactionAndStderrRedirects Uses

func SetupRedactionAndStderrRedirects() (cleanup func(), err error)

SetupRedactionAndStderrRedirects should be called once after command-line flags have been parsed, and before the first log entry is emitted.

The returned cleanup fn can be invoked by the caller to terminate the secondary logger. This may be useful in tests. However, for a long-running server process the cleanup function should likely not be called, to ensure that the file used to capture direct stderr writes remains open up until the process entirely terminates. This ensures that any Go runtime assertion failures on the way to termination can be properly captured.

func ShouldSendReport Uses

func ShouldSendReport(sv *settings.Values) bool

ShouldSendReport returns true iff SendReport() should be called.

func Shout Uses

func Shout(ctx context.Context, sev Severity, msg string)

Shout logs to the specified severity's log, and also to the real stderr if logging is currently redirected to a file.

func Shoutf Uses

func Shoutf(ctx context.Context, sev Severity, format string, args ...interface{})

Shoutf is like Shout but uses formatting.

func StartGCDaemon Uses

func StartGCDaemon(ctx context.Context)

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.

The logger's GC daemon stops when the provided context is canceled.

Note that secondary logger get their GC daemon started when they are allocated (NewSecondaryLogger). This assumes that secondary loggers are only allocated after command line parsing has completed too.

func TestingSetRedactable Uses

func TestingSetRedactable(redactableLogs bool) (cleanup func())

TestingSetRedactable sets the redactable flag for usage in a test. The caller is responsible for calling the cleanup function. This is exported for use in tests only -- it causes the logging configuration to be at risk of leaking unsafe information due to asynchronous direct writes to fd 2 / os.Stderr.

See the discussion on SetupRedactionAndStderrRedirects() for details.

func V Uses

func V(level Level) bool

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

See also ExpensiveLogEnabled().

TODO(andrei): Audit uses of V() and see which ones should actually use the newer ExpensiveLogEnabled().

func VDepth Uses

func VDepth(l Level, depth int) bool

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

func VErrEvent Uses

func VErrEvent(ctx context.Context, level Level, msg string)

VErrEvent either logs an error 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 VErrEventf Uses

func VErrEventf(ctx context.Context, level Level, format string, args ...interface{})

VErrEventf either logs an error 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 VErrEventfDepth Uses

func VErrEventfDepth(
    ctx context.Context, depth int, level Level, format string, args ...interface{},
)

VErrEventfDepth performs the same as VErrEventf but checks the verbosity level at the given depth in the call stack.

func VEvent Uses

func VEvent(ctx context.Context, level Level, msg string)

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 Uses

func VEventf(ctx context.Context, level Level, format string, args ...interface{})

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 VEventfDepth Uses

func VEventfDepth(ctx context.Context, depth int, level Level, format string, args ...interface{})

VEventfDepth performs the same as VEventf but checks the verbosity level at the given depth in the call stack.

func Warning Uses

func Warning(ctx context.Context, msg string)

Warning logs to the WARNING and INFO logs. It extracts log tags from the context and logs them along with the given message.

func Warningf Uses

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

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 Uses

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

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 Uses

func WithEventLog(ctx context.Context, family, title string) context.Context

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 WithNoEventLog Uses

func WithNoEventLog(ctx context.Context) context.Context

WithNoEventLog creates a context which no longer has an embedded event log.

type AmbientContext Uses

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 Uses

func (ac *AmbientContext) AddLogTag(name string, value interface{})

AddLogTag adds a tag to the ambient context.

func (*AmbientContext) AnnotateCtx Uses

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 an 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 Uses

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 Uses

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) LogTags Uses

func (ac *AmbientContext) LogTags() *logtags.Buffer

LogTags returns the tags in the ambient context.

func (*AmbientContext) ResetAndAnnotateCtx Uses

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 Uses

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 DirName Uses

type DirName struct {
    syncutil.Mutex
    // contains filtered or unexported fields
}

DirName overrides (if non-empty) the choice of directory in which to write logs. See createLogDirs for the full list of possible destinations. Note that the default is to log to stderr independent of this setting. See --logtostderr.

func (*DirName) IsSet Uses

func (l *DirName) IsSet() bool

IsSet returns true iff the directory name is set.

func (*DirName) Set Uses

func (l *DirName) Set(dir string) error

Set implements the flag.Value interface.

func (*DirName) String Uses

func (l *DirName) String() string

String implements the flag.Value interface.

func (*DirName) Type Uses

func (l *DirName) Type() string

Type implements the flag.Value interface.

type EditSensitiveData Uses

type EditSensitiveData int

EditSensitiveData describes how the messages in log entries should be edited through the API.

const (

    // WithMarkedSensitiveData is the "raw" log with sensitive data markers included.
    WithMarkedSensitiveData EditSensitiveData
    // WithFlattenedSensitiveData is the log with markers stripped.
    WithFlattenedSensitiveData
    // WithoutSensitiveData is the log with the sensitive data redacted.
    WithoutSensitiveData
)

func SelectEditMode Uses

func SelectEditMode(redact, keepRedactable bool) EditSensitiveData

SelectEditMode returns an EditSensitiveData value that's suitable for use with NewDecoder depending on client-side desired "redact" and "keep redactable" flags. (See the documentation for the Logs and LogFile RPCs and that of the 'merge-logs' CLI command.)

type Entry Uses

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"`
    // tags contains the context tags available in the context where the
    // entry was created.
    Tags string `protobuf:"bytes,7,opt,name=tags,proto3" json:"tags,omitempty"`
    // counter is an entry counter, meant for use in audit logs as an
    // instrument against log repudiation.
    // See: https://en.wikipedia.org/wiki/Non-repudiation
    //
    // It is incremented for every use of the logger where the entry was
    // produced.
    Counter uint64 `protobuf:"varint,8,opt,name=counter,proto3" json:"counter,omitempty"`
    // redactable is true if the message and tags fields include markers
    // to delineate sensitive information. In that case, confidentiality
    // can be obtained by only stripping away the data within this
    // marker. If redactable is false or unknown, the message should be
    // considered to only contain sensitive information, and should be
    // stripped away completely for confidentiality.
    Redactable bool `protobuf:"varint,9,opt,name=redactable,proto3" json:"redactable,omitempty"`
}

Entry represents a cockroach structured log entry.

func FetchEntriesFromFiles Uses

func FetchEntriesFromFiles(
    startTimestamp, endTimestamp int64,
    maxEntries int,
    pattern *regexp.Regexp,
    editMode EditSensitiveData,
) ([]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 MakeEntry Uses

func MakeEntry(
    ctx context.Context,
    s Severity,
    lc *EntryCounter,
    depth int,
    redactable bool,
    format string,
    args ...interface{},
) (res Entry)

MakeEntry creates an Entry.

func (*Entry) Descriptor Uses

func (*Entry) Descriptor() ([]byte, []int)

func (Entry) Format Uses

func (e Entry) Format(w io.Writer) error

Format writes the log entry to the specified writer.

func (*Entry) Marshal Uses

func (m *Entry) Marshal() (dAtA []byte, err error)

func (*Entry) MarshalTo Uses

func (m *Entry) MarshalTo(dAtA []byte) (int, error)

func (*Entry) ProtoMessage Uses

func (*Entry) ProtoMessage()

func (*Entry) Reset Uses

func (m *Entry) Reset()

func (*Entry) Size Uses

func (m *Entry) Size() (n int)

func (*Entry) String Uses

func (m *Entry) String() string

func (*Entry) Unmarshal Uses

func (m *Entry) Unmarshal(dAtA []byte) error

func (*Entry) XXX_DiscardUnknown Uses

func (m *Entry) XXX_DiscardUnknown()

func (*Entry) XXX_Marshal Uses

func (m *Entry) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Entry) XXX_Merge Uses

func (dst *Entry) XXX_Merge(src proto.Message)

func (*Entry) XXX_Size Uses

func (m *Entry) XXX_Size() int

func (*Entry) XXX_Unmarshal Uses

func (m *Entry) XXX_Unmarshal(b []byte) error

type EntryCounter Uses

type EntryCounter struct {
    // EnableMsgCount, if true, enables the production of entry
    // counters.
    EnableMsgCount bool
    // contains filtered or unexported fields
}

EntryCounter supports the generation of a per-entry log entry counter. This is needed in audit logs to hinder malicious repudiation of log events by manually erasing log files or log entries.

type EntryDecoder Uses

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 Uses

func NewEntryDecoder(in io.Reader, editMode EditSensitiveData) *EntryDecoder

NewEntryDecoder creates a new instance of EntryDecoder.

func (*EntryDecoder) Decode Uses

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

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

type EveryN Uses

type EveryN struct {
    util.EveryN
}

EveryN provides a way to rate limit spammy log messages. It tracks how recently a given log message has been emitted so that it can determine whether it's worth logging again.

func Every Uses

func Every(n time.Duration) EveryN

Every is a convenience constructor for an EveryN object that allows a log message every n duration.

func (*EveryN) ShouldLog Uses

func (e *EveryN) ShouldLog() bool

ShouldLog returns whether it's been more than N time since the last event.

type FileDetails Uses

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"`
    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 ParseLogFilename Uses

func ParseLogFilename(filename string) (FileDetails, error)

ParseLogFilename parses a filename into FileDetails if it matches the pattern for log files. If the filename does not match the log file pattern, an error is returned.

func (*FileDetails) Descriptor Uses

func (*FileDetails) Descriptor() ([]byte, []int)

func (*FileDetails) Marshal Uses

func (m *FileDetails) Marshal() (dAtA []byte, err error)

func (*FileDetails) MarshalTo Uses

func (m *FileDetails) MarshalTo(dAtA []byte) (int, error)

func (*FileDetails) ProtoMessage Uses

func (*FileDetails) ProtoMessage()

func (*FileDetails) Reset Uses

func (m *FileDetails) Reset()

func (*FileDetails) Size Uses

func (m *FileDetails) Size() (n int)

func (*FileDetails) String Uses

func (m *FileDetails) String() string

func (*FileDetails) Unmarshal Uses

func (m *FileDetails) Unmarshal(dAtA []byte) error

func (*FileDetails) XXX_DiscardUnknown Uses

func (m *FileDetails) XXX_DiscardUnknown()

func (*FileDetails) XXX_Marshal Uses

func (m *FileDetails) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*FileDetails) XXX_Merge Uses

func (dst *FileDetails) XXX_Merge(src proto.Message)

func (*FileDetails) XXX_Size Uses

func (m *FileDetails) XXX_Size() int

func (*FileDetails) XXX_Unmarshal Uses

func (m *FileDetails) XXX_Unmarshal(b []byte) error

type FileInfo Uses

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,proto3" json:"details"`
}

func ListLogFiles Uses

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.

func MakeFileInfo Uses

func MakeFileInfo(details FileDetails, info os.FileInfo) FileInfo

MakeFileInfo constructs a FileInfo from FileDetails and os.FileInfo.

func (*FileInfo) Descriptor Uses

func (*FileInfo) Descriptor() ([]byte, []int)

func (*FileInfo) Marshal Uses

func (m *FileInfo) Marshal() (dAtA []byte, err error)

func (*FileInfo) MarshalTo Uses

func (m *FileInfo) MarshalTo(dAtA []byte) (int, error)

func (*FileInfo) ProtoMessage Uses

func (*FileInfo) ProtoMessage()

func (*FileInfo) Reset Uses

func (m *FileInfo) Reset()

func (*FileInfo) Size Uses

func (m *FileInfo) Size() (n int)

func (*FileInfo) String Uses

func (m *FileInfo) String() string

func (*FileInfo) Unmarshal Uses

func (m *FileInfo) Unmarshal(dAtA []byte) error

func (*FileInfo) XXX_DiscardUnknown Uses

func (m *FileInfo) XXX_DiscardUnknown()

func (*FileInfo) XXX_Marshal Uses

func (m *FileInfo) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*FileInfo) XXX_Merge Uses

func (dst *FileInfo) XXX_Merge(src proto.Message)

func (*FileInfo) XXX_Size Uses

func (m *FileInfo) XXX_Size() int

func (*FileInfo) XXX_Unmarshal Uses

func (m *FileInfo) XXX_Unmarshal(b []byte) error

type InterceptorFn Uses

type InterceptorFn func(entry Entry)

InterceptorFn is the type of function accepted by Intercept().

type Level Uses

type Level int32

Level specifies a level of verbosity for V logs. *Level implements flag.Value; the --verbosity flag is of type Level and should be modified only through the flag.Value interface.

func (*Level) Set Uses

func (l *Level) Set(value string) error

Set is part of the flag.Value interface.

func (*Level) String Uses

func (l *Level) String() string

String is part of the flag.Value interface.

type NoFileLogScope Uses

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

NoFileLogScope represents the lifetime of a logging output with logging to file being disabled. It is used for e.g. in-memory only demo clusters.

func ScopeWithoutFiles Uses

func ScopeWithoutFiles() (s NoFileLogScope)

ScopeWithoutFiles starts a logging environment where logging to files is disabled. This is used for e.g. in-memory only demo clusters.

func (NoFileLogScope) Close Uses

func (s NoFileLogScope) Close()

Close finalizes the given scope.

type ReportType Uses

type ReportType int

ReportType is used to differentiate between an actual crash/panic and just reporting an error. This data is useful for stability purposes.

const (
    // ReportTypePanic signifies that this is an actual panic.
    ReportTypePanic ReportType = iota
    // ReportTypeError signifies that this is just a report of an error but it
    // still may include an exception and stack trace.
    ReportTypeError
)

type SecondaryLogger Uses

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

SecondaryLogger represents a secondary / auxiliary logging channel whose logging events go to a different file than the main logging facility.

func NewSecondaryLogger Uses

func NewSecondaryLogger(
    ctx context.Context,
    dirName *DirName,
    fileNamePrefix string,
    enableGc bool,
    forceSyncWrites bool,
    enableMsgCount bool,
) *SecondaryLogger

NewSecondaryLogger creates a secondary logger.

The given directory name can be either nil or empty, in which case the global logger's own dirName is used; or non-nil and non-empty, in which case it specifies the directory for that new logger.

The logger's GC daemon stops when the provided context is canceled.

The caller is responsible for ensuring the Close() method is eventually called.

func (*SecondaryLogger) Close Uses

func (l *SecondaryLogger) Close()

Close implements the stopper.Closer interface.

func (*SecondaryLogger) LogSev Uses

func (l *SecondaryLogger) LogSev(ctx context.Context, sev Severity, args ...interface{})

LogSev logs an event at the specified severity on a secondary logger.

func (*SecondaryLogger) Logf Uses

func (l *SecondaryLogger) Logf(ctx context.Context, format string, args ...interface{})

Logf logs an event on a secondary logger.

func (*SecondaryLogger) LogfDepth Uses

func (l *SecondaryLogger) LogfDepth(
    ctx context.Context, depth int, format string, args ...interface{},
)

LogfDepth logs an event on a secondary logger, offsetting the caller's stack frame by 'depth'

type Severity Uses

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 Uses

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) EnumDescriptor Uses

func (Severity) EnumDescriptor() ([]byte, []int)

func (*Severity) Name Uses

func (s *Severity) Name() string

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

func (*Severity) Set Uses

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

Set is part of the flag.Value interface.

func (Severity) String Uses

func (x Severity) String() string

type TestLogScope Uses

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 Uses

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.

func ScopeWithoutShowLogs Uses

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 Uses

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.

func (*TestLogScope) Rotate Uses

func (l *TestLogScope) Rotate(t tShim)

Rotate closes the current log files so that the next log call will reopen them with current settings. This is useful when e.g. a test changes the logging configuration after opening a test log scope.

Directories

PathSynopsis
logflags

Package log imports 44 packages (graph) and is imported by 1835 packages. Updated 2020-08-05. Refresh now. Tools for package owners.