log

README

github.com/sourcegraph/log

OpenTelemetry-compatible Zap logger for Sourcegraph (formerly lib/log)

Learn more:

• Adminstration: Logging
• Development: How to add logging
• Package docs

Documentation

Overview

Package log provides an OpenTelemetry-compatible logging library for Sourcegraph. Subpackages are available that provide adapters, testing utilities, and additional log sinks.

It encourages certain practices by design, such as by not having a global logger available, disallowing the use of compile-time loggers, and re-exporting a limited number of field types.

Learn more: https://docs.sourcegraph.com/dev/how-to/add_logging

Index

• Variables
• type Field
  • func Error(err error) Field
  • func NamedError(key string, err error) Field
  • func Object(key string, fields ...Field) Field
• type Level
  • func (l Level) Parse() zapcore.Level
• type Logger
  • func NoOp() Logger
  • func Scoped(scope string) Logger
• type PostInitCallbacks
  • func Init(r Resource, s ...Sink) *PostInitCallbacks
• type Resource
• type SentrySink
• type Sink
  • func NewSentrySink() Sink
  • func NewSentrySinkWith(s SentrySink) Sink
• type SinksConfig
• type SinksConfigGetter
• type TraceContext

Variables

var (
	// String constructs a field with the given key and value.
	String = zap.String
	// Stringp constructs a field that carries a *string. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Stringp = zap.Stringp
	// Strings constructs a field that carries a slice of strings.
	Strings = zap.Strings

	// Int constructs a field with the given key and value.
	Int = zap.Int
	// Intp constructs a field that carries a *int. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Intp = zap.Intp
	// Int32 constructs a field with the given key and value.
	Int32 = zap.Int32
	// Int32p constructs a field that carries a *int32. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Int32p = zap.Int32p
	// Int64 constructs a field with the given key and value.
	Int64 = zap.Int64
	// Int64p constructs a field that carries a *int64. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Int64p = zap.Int64p
	// Ints constructs a field that carries a slice of integers.
	Ints = zap.Ints
	// Int32s constructs a field that carries a slice of 32 bit integers.
	Int32s = zap.Int32s
	// Int64s constructs a field that carries a slice of integers.
	Int64s = zap.Int64s

	// Uint constructs a field with the given key and value.
	Uint = zap.Uint
	// Uintp constructs a field that carries a *uint. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Uintp = zap.Uintp
	// Uint32 constructs a field with the given key and value.
	Uint32 = zap.Uint32
	// Uint32p constructs a field that carries a *uint32. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Uint32p = zap.Uint32p
	// Uint64 constructs a field with the given key and value.
	Uint64 = zap.Uint64
	// Uint64p constructs a field that carries a *uint64. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Uint64p = zap.Uint64p

	// Float32 constructs a field that carries a float32. The way the
	// floating-point value is represented is encoder-dependent, so marshaling is
	// necessarily lazy.
	Float32 = zap.Float32
	// Float32p constructs a field that carries a *float32. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Float32p = zap.Float32p
	// Float32s constructs a field that carries a slice of floats.
	Float32s = zap.Float32s
	// Float64 constructs a field that carries a float64. The way the floating-point value
	// is represented is encoder-dependent, so marshaling is necessarily lazy.
	Float64 = zap.Float64
	// Float64p constructs a field that carries a *float64. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Float64p = zap.Float64p
	// Float64s constructs a field that carries a slice of floats.
	Float64s = zap.Float64s

	// Bool constructs a field that carries a bool.
	Bool = zap.Bool
	// Boolp constructs a field that carries a *bool. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Boolp = zap.Boolp

	// Binary constructs a field that carries an opaque binary blob.
	//
	// Binary data is serialized in an encoding-appropriate format. For example,
	// zap's JSON encoder base64-encodes binary blobs. To log UTF-8 encoded text,
	// use ByteString.
	Binary = zap.Binary

	// Duration constructs a field with the given key and value. The encoder controls how
	// the duration is serialized.
	Duration = zap.Duration
	// Durationp constructs a field that carries a *time.Duration. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Durationp = zap.Durationp

	// Time constructs a Field with the given key and value. The encoder controls how the
	// time is serialized.
	Time = zap.Time
	// Timep constructs a field that carries a *time.Time. The returned Field will safely
	// and explicitly represent `nil` when appropriate.
	Timep = zap.Timep

	// Namespace creates a named, isolated scope within the logger's context. All subsequent
	// fields will be added to the new namespace.
	//
	// This helps prevent key collisions when injecting loggers into sub-components or
	// third-party libraries.
	Namespace = zap.Namespace
)

var (
	// EnvDevelopment is key of the environment variable that is used to set whether
	// to use development logger configuration on Init.
	EnvDevelopment = globallogger.EnvDevelopment
	// EnvLogFormat is key of the environment variable that is used to set the log format
	// on Init.
	//
	// The value should be one of 'json', 'json_gcp' or 'condensed', defaulting to 'json'.
	EnvLogFormat = "SRC_LOG_FORMAT"
	// EnvLogLevel is key of the environment variable that can be used to set the log
	// level on Init.
	//
	// The value is one of 'debug', 'info', 'warn', 'error', or 'none', defaulting to
	// 'warn'.
	EnvLogLevel = "SRC_LOG_LEVEL"
	// EnvLogScopeLevel is key of the environment variable that can be used to
	// override the log level for specific scopes and its children.
	//
	// It has the format "SCOPE_0=LEVEL_0,SCOPE_1=LEVEL_1,...".
	//
	// Notes:
	//
	//  - these levels do not respect the root level (SRC_LOG_LEVEL), so this
	//    allows operators to turn up the verbosity of specific logs.
	//  - this only affects the outputcore (ie will not effect sentrycore).
	//  - Scope matches the full scope name. IE the below example has the scope
	//    "foo.bar" not "bar".
	//
	//    log.Scoped("foo", "").Scoped("bar", "")
	EnvLogScopeLevel = "SRC_LOG_SCOPE_LEVEL"
	// EnvLogSamplingInitial is key of the environment variable that can be used to set
	// the number of entries with identical messages to always output per second.
	//
	// Defaults to 100 - set explicitly to 0 or -1 to disable.
	EnvLogSamplingInitial = "SRC_LOG_SAMPLING_INITIAL"
	// EnvLogSamplingThereafter is key of the environment variable that can be used to set
	// the number of entries with identical messages to discard before emitting another
	// one per second, after EnvLogSamplingInitial.
	//
	// Defaults to 100 - set explicitly to 0 or -1 to disable.
	EnvLogSamplingThereafter = "SRC_LOG_SAMPLING_THEREAFTER"
)

Types

type Field

type Field = zapcore.Field

A Field is a marshaling operation used to add a key-value pair to a logger's context.

Field is an aliased import that is intentionally restricted so as to not allow overly liberal use of log fields, namely 'Any()'.

func Error

func Error(err error) Field

Error is shorthand for the common idiom NamedError("error", err).

func NamedError

func NamedError(key string, err error) Field

NamedError constructs a field that logs err.Error() under the provided key.

For the common case in which the key is simply "error", the Error function is shorter and less repetitive.

This is currently intentionally different from the zap.NamedError implementation since we don't want the additional verbosity at the moment.

func Object

func Object(key string, fields ...Field) Field

Object constructs a field that places all the given fields within the given key's namespace.

type Level

type Level string

const (
	LevelDebug Level = "debug"
	LevelInfo  Level = "info"
	LevelWarn  Level = "warn"
	LevelError Level = "error"

	// LevelNone silences all log output.
	LevelNone Level = "none"
)

func (Level) Parse

func (l Level) Parse() zapcore.Level

Parse parses the given level string as a supported output format, while trying to maintain some degree of back-compat with the intent of previously supported log levels.

This is exported only for internal use.

type Logger

type Logger interface {
	// Scoped creates a new Logger with scope attached as part of its instrumentation
	// scope. For example, if the underlying logger is scoped 'foo', then
	// 'logger.Scoped("bar")' will create a logger with scope 'foo.bar'.
	//
	// Scopes should be static values, NOT dynamic values like identifiers or parameters,
	// and should generally be CamelCased with descriptions that follow our logging
	// conventions - learn more: https://docs.sourcegraph.com/dev/how-to/add_logging#scoped-loggers
	//
	// Scopes map to OpenTelemetry InstrumentationScopes:
	// https://opentelemetry.io/docs/reference/specification/logs/data-model/#field-instrumentationscope
	Scoped(scope string) Logger

	// With creates a new Logger with the given fields as attributes.
	//
	// https://opentelemetry.io/docs/reference/specification/logs/data-model/#field-attributes
	With(...Field) Logger
	// WithTrace creates a new Logger with the given trace context. If TraceContext has no
	// fields set, this function is a no-op. If WithTrace has already been called on this
	// logger with a valid TraceContext, the existing TraceContext will be overwritten
	// with the new TraceContext.
	//
	// https://opentelemetry.io/docs/reference/specification/logs/data-model/#trace-context-fields
	WithTrace(TraceContext) Logger

	// Debug logs a debug message, including any fields accumulated on the Logger.
	//
	// Debug logs are typically voluminous, and are usually disabled in production.
	Debug(string, ...Field)
	// Info logs an info message, including any fields accumulated on the Logger.
	//
	// Info is the default logging priority.
	Info(string, ...Field)
	// Warn logs a message at WarnLevel, including any fields accumulated on the Logger.
	//
	// Warning logs are more important than Info, but don't need individual human review.
	Warn(string, ...Field)
	// Error logs an error message, including any fields accumulated on the Logger.
	//
	// Error logs are high-priority. If an application is running smoothly, it shouldn't
	// generate any error-level logs.
	Error(string, ...Field)
	// Fatal logs a fatal error message, including any fields accumulated on the Logger.
	// The logger then calls os.Exit(1), flushing the logger before doing so. Use sparingly.
	Fatal(string, ...Field)

	// AddCallerSkip increases the number of callers skipped by caller annotation. When
	// building wrappers around the Logger, using AddCallerSkip prevents the Logger from
	// always reporting the wrapper code as the caller.
	AddCallerSkip(int) Logger
	// IncreaseLevel creates a logger that only logs at or above the given level for the given
	// scope. To disable all output, you can use LogLevelNone.
	//
	// IncreaseLevel is only allowed to increase the level the Logger was initialized at -
	// it has no affect if the preset level is higher than the indicated level.
	IncreaseLevel(scope string, description string, level Level) Logger
}

Logger is an OpenTelemetry-compliant logger. All functions that log output should hold a reference to a Logger that gets passed in from callers, so as to maintain fields and context.

func NoOp

func NoOp() Logger

NoOp returns a no-op Logger that can never produce any output. It can be safely created before initialization. Use sparingly, and do not use with the intent of replacing it post-initialization.

func Scoped

func Scoped(scope string) Logger

Scoped returns the global logger and sets it up with the given scope and OpenTelemetry compliant implementation. Instead of using this everywhere a log is needed, callers should hold a reference to the Logger and pass it in to places that need to log.

Scopes should be static values, NOT dynamic values like identifiers or parameters, and should generally be CamelCased with descriptions that follow our logging conventions - learn more: https://docs.sourcegraph.com/dev/how-to/add_logging#scoped-loggers

When testing, you should use 'logtest.Scoped(*testing.T)' instead - learn more: https://docs.sourcegraph.com/dev/how-to/add_logging#testing-usage

type PostInitCallbacks

type PostInitCallbacks struct {
	// Sync must be called before application exit, such as via defer.
	//
	// Note: The error from sync is suppressed since this is usually called as a
	// defer in func main. In that case there isn't a reasonable way to handle the
	// error. As such this function signature doesn't return an error.
	Sync func()

	// Update should be called to change sink configuration, e.g. via
	// conf.Watch. Note that sinks not created upon initialization will
	// not be created post-initialization. Is a no-op if no sinks are enabled.
	Update func(SinksConfigGetter) func()
}

PostInitCallbacks is a set of callbacks returned by Init that enables finalization and updating of any configured sinks.

func Init

func Init(r Resource, s ...Sink) *PostInitCallbacks

Init initializes the log package's global logger as a logger of the given resource. It must be called on service startup, i.e. 'main()', NOT on an 'init()' function. Subsequent calls will panic, so do not call this within a non-service context.

Init returns a set of callbacks - see PostInitCallbacks for more details. The Sync callback in particular must be called before application exit.

For testing, you can use 'logtest.Init' to initialize the logging library.

If Init is not called, trying to create a logger with Scoped will panic.

type Resource

type Resource = otelfields.Resource

type SentrySink

type SentrySink struct {
	// ClientOptions expose various options to configure the Sentry client
	sentry.ClientOptions
}

SentrySink reports all warning-level and above log messages that contain an error field (via the `log.Error(err)` or `log.NamedError(name, err)` field constructors) to Sentry, complete with stacktrace data and any additional context logged in the corresponding log message (including anything accumulated on a sub-logger).

type Sink

type Sink interface {
	Name() string
	// contains filtered or unexported methods
}

Sink describes additional destinations that github.com/sourcegraph/log can send log entries to. It can only be implemented directly within the package.

func NewSentrySink

func NewSentrySink() Sink

NewSentrySink instantiates a Sentry sink to provide to `log.Init` with the following default values: - SampleRate: 0.1 To provide different values see `NewSentrySinkWith`

func NewSentrySinkWith

func NewSentrySinkWith(s SentrySink) Sink

NewSentrySinkWith instantiates a Sentry sink to provide to `log.Init` with the values provided in SentrySink.

type SinksConfig

type SinksConfig struct {
	Sentry *SentrySink
}

SinksConfig describes unified configuration for all sinks.

type SinksConfigGetter

type SinksConfigGetter func() SinksConfig

SinksConfigGetter should provide the latest SinksConfig to update sink configuration.

type TraceContext

type TraceContext = otelfields.TraceContext

TraceContext represents a trace to associate with log entries.

https://opentelemetry.io/docs/reference/specification/logs/data-model/#trace-context-fields