blob: 073cf62386656ecd748ad1abf5447a5d9c621fba [file] [log] [blame]
// Copyright 2018 The gVisor Authors.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// Package log implements a library for logging.
// This is separate from the standard logging package because logging may be a
// high-impact activity, and therefore we wanted to provide as much flexibility
// as possible in the underlying implementation.
// Note that logging should still be considered high-impact, and should not be
// done in the hot path. If necessary, logging statements should be protected
// with guards regarding the logging level. For example,
// if log.IsLogging(log.Debug) {
// log.Debugf(...)
// }
// This is because the log.Debugf(...) statement alone will generate a
// significant amount of garbage and churn in many cases, even if no log
// message is ultimately emitted.
package log
import (
stdlog "log"
// Level is the log level.
type Level uint32
// The following levels are fixed, and can never be changed. Since some control
// RPCs allow for changing the level as an integer, it is only possible to add
// additional levels, and the existing one cannot be removed.
const (
// Warning indicates that output should always be emitted.
Warning Level = iota
// Info indicates that output should normally be emitted.
// Debug indicates that output should not normally be emitted.
func (l Level) String() string {
switch l {
case Warning:
return "Warning"
case Info:
return "Info"
case Debug:
return "Debug"
return fmt.Sprintf("Invalid level: %d", l)
// Emitter is the final destination for logs.
type Emitter interface {
// Emit emits the given log statement. This allows for control over the
// timestamp used for logging.
Emit(depth int, level Level, timestamp time.Time, format string, v ...interface{})
// Writer writes the output to the given writer.
type Writer struct {
// Next is where output is written.
Next io.Writer
// mu protects fields below.
mu sync.Mutex
// errors counts failures to write log messages so it can be reported
// when writer start to work again. Needs to be accessed using atomics
// to make race detector happy because it's read outside the mutex.
errors int32
// Write writes out the given bytes, handling non-blocking sockets.
func (l *Writer) Write(data []byte) (int, error) {
n := 0
for n < len(data) {
w, err := l.Next.Write(data[n:])
n += w
// Is it a non-blocking socket?
if pathErr, ok := err.(*os.PathError); ok && pathErr.Timeout() {
// Some other error?
if err != nil {
atomic.AddInt32(&l.errors, 1)
return n, err
// Do we need to end with a '\n'?
if len(data) == 0 || data[len(data)-1] != '\n' {
// Dirty read in case there were errors (rare).
if atomic.LoadInt32(&l.errors) > 0 {
// Recheck condition under lock.
if e := atomic.LoadInt32(&l.errors); e > 0 {
msg := fmt.Sprintf("\n*** Dropped %d log messages ***\n", e)
if _, err := l.Next.Write([]byte(msg)); err == nil {
atomic.StoreInt32(&l.errors, 0)
return n, nil
// Emit emits the message.
func (l *Writer) Emit(_ int, _ Level, _ time.Time, format string, args ...interface{}) {
fmt.Fprintf(l, format, args...)
// MultiEmitter is an emitter that emits to multiple Emitters.
type MultiEmitter []Emitter
// Emit emits to all emitters.
func (m *MultiEmitter) Emit(depth int, level Level, timestamp time.Time, format string, v ...interface{}) {
for _, e := range *m {
e.Emit(1+depth, level, timestamp, format, v...)
// TestLogger is implemented by testing.T and testing.B.
type TestLogger interface {
Logf(format string, v ...interface{})
// TestEmitter may be used for wrapping tests.
type TestEmitter struct {
// Emit emits to the TestLogger.
func (t *TestEmitter) Emit(_ int, level Level, timestamp time.Time, format string, v ...interface{}) {
t.Logf(format, v...)
// Logger is a high-level logging interface. It is in fact, not used within the
// log package. Rather it is provided for others to provide contextual loggers
// that may append some addition information to log statement. BasicLogger
// satisfies this interface, and may be passed around as a Logger.
type Logger interface {
// Debugf logs a debug statement.
Debugf(format string, v ...interface{})
// Infof logs at an info level.
Infof(format string, v ...interface{})
// Warningf logs at a warning level.
Warningf(format string, v ...interface{})
// IsLogging returns true iff this level is being logged. This may be
// used to short-circuit expensive operations for debugging calls.
IsLogging(level Level) bool
// BasicLogger is the default implementation of Logger.
type BasicLogger struct {
// Debugf implements logger.Debugf.
func (l *BasicLogger) Debugf(format string, v ...interface{}) {
l.DebugfAtDepth(1, format, v...)
// Infof implements logger.Infof.
func (l *BasicLogger) Infof(format string, v ...interface{}) {
l.InfofAtDepth(1, format, v...)
// Warningf implements logger.Warningf.
func (l *BasicLogger) Warningf(format string, v ...interface{}) {
l.WarningfAtDepth(1, format, v...)
// DebugfAtDepth logs at a specific depth.
func (l *BasicLogger) DebugfAtDepth(depth int, format string, v ...interface{}) {
if l.IsLogging(Debug) {
l.Emit(1+depth, Debug, time.Now(), format, v...)
// InfofAtDepth logs at a specific depth.
func (l *BasicLogger) InfofAtDepth(depth int, format string, v ...interface{}) {
if l.IsLogging(Info) {
l.Emit(1+depth, Info, time.Now(), format, v...)
// WarningfAtDepth logs at a specific depth.
func (l *BasicLogger) WarningfAtDepth(depth int, format string, v ...interface{}) {
if l.IsLogging(Warning) {
l.Emit(1+depth, Warning, time.Now(), format, v...)
// IsLogging implements logger.IsLogging.
func (l *BasicLogger) IsLogging(level Level) bool {
return atomic.LoadUint32((*uint32)(&l.Level)) >= uint32(level)
// SetLevel sets the logging level.
func (l *BasicLogger) SetLevel(level Level) {
atomic.StoreUint32((*uint32)(&l.Level), uint32(level))
// logMu protects Log below. We use atomic operations to read the value, but
// updates require logMu to ensure consistency.
var logMu sync.Mutex
// log is the default logger.
var log atomic.Value
// Log retrieves the global logger.
func Log() *BasicLogger {
return log.Load().(*BasicLogger)
// SetTarget sets the log target.
// This is not thread safe and shouldn't be called concurrently with any
// logging calls.
func SetTarget(target Emitter) {
defer logMu.Unlock()
oldLog := Log()
log.Store(&BasicLogger{Level: oldLog.Level, Emitter: target})
// SetLevel sets the log level.
func SetLevel(newLevel Level) {
// Debugf logs to the global logger.
func Debugf(format string, v ...interface{}) {
Log().DebugfAtDepth(1, format, v...)
// Infof logs to the global logger.
func Infof(format string, v ...interface{}) {
Log().InfofAtDepth(1, format, v...)
// Warningf logs to the global logger.
func Warningf(format string, v ...interface{}) {
Log().WarningfAtDepth(1, format, v...)
// DebugfAtDepth logs to the global logger.
func DebugfAtDepth(depth int, format string, v ...interface{}) {
Log().DebugfAtDepth(1+depth, format, v...)
// InfofAtDepth logs to the global logger.
func InfofAtDepth(depth int, format string, v ...interface{}) {
Log().InfofAtDepth(1+depth, format, v...)
// WarningfAtDepth logs to the global logger.
func WarningfAtDepth(depth int, format string, v ...interface{}) {
Log().WarningfAtDepth(1+depth, format, v...)
// defaultStackSize is the default buffer size to allocate for stack traces.
const defaultStackSize = 1 << 16 // 64KB
// maxStackSize is the maximum buffer size to allocate for stack traces.
const maxStackSize = 1 << 26 // 64MB
// Stacks returns goroutine stacks, like panic.
func Stacks(all bool) []byte {
var trace []byte
for s := defaultStackSize; s <= maxStackSize; s *= 4 {
trace = make([]byte, s)
nbytes := runtime.Stack(trace, all)
if nbytes == s {
return trace[:nbytes]
trace = append(trace, []byte("\n\n...<too large, truncated>")...)
return trace
// Traceback logs the given message and dumps a stacktrace of the current
// goroutine.
// This will be print a traceback, tb, as Warningf(format+":\n%s", v..., tb).
func Traceback(format string, v ...interface{}) {
v = append(v, Stacks(false))
Warningf(format+":\n%s", v...)
// TracebackAll logs the given message and dumps a stacktrace of all goroutines.
// This will be print a traceback, tb, as Warningf(format+":\n%s", v..., tb).
func TracebackAll(format string, v ...interface{}) {
v = append(v, Stacks(true))
Warningf(format+":\n%s", v...)
// IsLogging returns whether the global logger is logging.
func IsLogging(level Level) bool {
return Log().IsLogging(level)
// CopyStandardLogTo redirects the stdlib log package global output to the global
// logger for the specified level.
func CopyStandardLogTo(l Level) error {
var f func(string, ...interface{})
switch l {
case Debug:
f = Debugf
case Info:
f = Infof
case Warning:
f = Warningf
return fmt.Errorf("unknown log level %v", l)
stdlog.SetOutput(linewriter.NewWriter(func(p []byte) {
// We must not retain p, but log formatting is not required to
// be synchronous (though the in-package implementations are),
// so we must make a copy.
b := make([]byte, len(p))
copy(b, p)
f("%s", b)
return nil
func init() {
// Store the initial value for the log.
log.Store(&BasicLogger{Level: Info, Emitter: GoogleEmitter{&Writer{Next: os.Stderr}}})