Documentation

Overview

    Package logging defines Logger interface and context.Context helpers to put\get logger from context.Context.

    Unfortunately standard library doesn't define any Logger interface (only struct). And even worse: GAE logger is exposing different set of methods. Some additional layer is needed to unify the logging. Package logging is intended to be used from packages that support both local and GAE environments. Such packages should not use global logger but must accept instances of Logger interface (or even more generally context.Context) as parameters. Then callers can pass appropriate Logger implementation (or inject appropriate logger into context.Context) depending on where the code is running.

    Index

    Constants

    View Source
    const DefaultLevel = Info

      DefaultLevel is the default Level value.

      View Source
      const (
      	// ErrorKey is a logging field key to use for errors.
      	ErrorKey = "error"
      )

      Variables

      This section is empty.

      Functions

      func Debugf

      func Debugf(c context.Context, fmt string, args ...interface{})

        Debugf is a shorthand method to call the current logger's Errorf method.

        func Errorf

        func Errorf(c context.Context, fmt string, args ...interface{})

          Errorf is a shorthand method to call the current logger's Errorf method.

          func Infof

          func Infof(c context.Context, fmt string, args ...interface{})

            Infof is a shorthand method to call the current logger's Errorf method.

            func IsLogging

            func IsLogging(c context.Context, l Level) bool

              IsLogging tests whether the context is configured to log at the specified level.

              Individual Logger implementations are supposed to call this function when deciding whether to log the message.

              func Logf

              func Logf(c context.Context, l Level, fmt string, args ...interface{})

                Logf is a shorthand method to call the current logger's logging method which corresponds to the supplied log level.

                func SetError

                func SetError(c context.Context, err error) context.Context

                  SetError returns a context with its error field set.

                  func SetFactory

                  func SetFactory(c context.Context, f Factory) context.Context

                    SetFactory sets the Logger factory for this context.

                    The factory will be called each time Get(context) is used.

                    func SetField

                    func SetField(c context.Context, key string, value interface{}) context.Context

                      SetField is a convenience method for SetFields for a single key/value pair.

                      func SetFields

                      func SetFields(c context.Context, fields Fields) context.Context

                        SetFields adds the additional fields as context for the current Logger. The display of these fields depends on the implementation of the Logger. The new context will contain the combination of its current Fields, updated with the new ones (see Fields.Copy). Specifying the new fields as nil will clear the currently set fields.

                        func SetLevel

                        func SetLevel(c context.Context, l Level) context.Context

                          SetLevel returns a new context with the given logging level.

                          It can be retrieved with GetLevel(context).

                          func Warningf

                          func Warningf(c context.Context, fmt string, args ...interface{})

                            Warningf is a shorthand method to call the current logger's Errorf method.

                            Types

                            type Config

                            type Config struct {
                            	Level Level
                            }

                              Config is a logging configuration structure.

                              func (*Config) AddFlags

                              func (c *Config) AddFlags(fs *flag.FlagSet)

                                AddFlags adds common flags to a supplied FlagSet.

                                func (*Config) AddFlagsPrefix

                                func (c *Config) AddFlagsPrefix(fs *flag.FlagSet, prefix string)

                                  AddFlagsPrefix adds common flags to a supplied FlagSet with a prefix.

                                  A string prefix must be supplied which will be prepended to each added flag verbatim.

                                  func (*Config) Set

                                  func (c *Config) Set(ctx context.Context) context.Context

                                    Set returns a new context configured to use logging level passed via the command-line level flag.

                                    type Factory

                                    type Factory func(context.Context) Logger

                                      Factory is a function that returns a Logger instance bound to the specified context.

                                      The given context will be used to detect logging level and fields.

                                      func GetFactory

                                      func GetFactory(c context.Context) Factory

                                        GetFactory returns the currently-configured logging factory (or nil).

                                        type FieldEntry

                                        type FieldEntry struct {
                                        	Key   string      // The field's key.
                                        	Value interface{} // The field's value.
                                        }

                                          FieldEntry is a static representation of a single key/value entry in a Fields.

                                          func (*FieldEntry) String

                                          func (e *FieldEntry) String() string

                                            String returns the string representation of the field entry: "<key>":"<value>".

                                            type Fields

                                            type Fields map[string]interface{}

                                              Fields maps string keys to arbitrary values.

                                              Fields can be added to a Context. Fields added to a Context augment those in the Context's parent Context, overriding duplicate keys. When Fields are added to a Context, they are copied internally for retention.

                                              Fields can also be added directly to a log message by calling its logging passthrough methods. This immediate usage avoids the overhead of duplicating the fields for retention.

                                              func GetFields

                                              func GetFields(c context.Context) Fields

                                                GetFields returns the current Fields.

                                                This method is used for logger implementations with the understanding that the returned fields must not be mutated.

                                                func NewFields

                                                func NewFields(v map[string]interface{}) Fields

                                                  NewFields instantiates a new Fields instance by duplicating the supplied map.

                                                  func WithError

                                                  func WithError(err error) Fields

                                                    WithError returns a Fields instance containing an error.

                                                    func (Fields) Copy

                                                    func (f Fields) Copy(other Fields) Fields

                                                      Copy returns a copy of this Fields with the keys from other overlaid on top of this one's.

                                                      func (Fields) Debugf

                                                      func (f Fields) Debugf(c context.Context, fmt string, args ...interface{})

                                                        Debugf is a shorthand method to call the current logger's Errorf method.

                                                        func (Fields) Errorf

                                                        func (f Fields) Errorf(c context.Context, fmt string, args ...interface{})

                                                          Errorf is a shorthand method to call the current logger's Errorf method.

                                                          func (Fields) Infof

                                                          func (f Fields) Infof(c context.Context, fmt string, args ...interface{})

                                                            Infof is a shorthand method to call the current logger's Errorf method.

                                                            func (Fields) SortedEntries

                                                            func (f Fields) SortedEntries() (s []*FieldEntry)

                                                              SortedEntries processes a Fields object, pruning invisible fields, placing the ErrorKey field first, and then sorting the remaining fields by key.

                                                              func (Fields) String

                                                              func (f Fields) String() string

                                                                String returns a string describing the contents of f in a sorted, dictionary-like format.

                                                                func (Fields) Warningf

                                                                func (f Fields) Warningf(c context.Context, fmt string, args ...interface{})

                                                                  Warningf is a shorthand method to call the current logger's Errorf method.

                                                                  type Level

                                                                  type Level int

                                                                    Level is an enumeration consisting of supported log levels.

                                                                    const (
                                                                    	Debug Level = iota
                                                                    	Info
                                                                    	Warning
                                                                    	Error
                                                                    )

                                                                      Defined log levels.

                                                                      func GetLevel

                                                                      func GetLevel(c context.Context) Level

                                                                        GetLevel returns the Level for this context. It will return DefaultLevel if none is defined.

                                                                        func (*Level) Set

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

                                                                          Set implements flag.Value.

                                                                          func (Level) String

                                                                          func (l Level) String() string

                                                                            String implements flag.Value.

                                                                            type Logger

                                                                            type Logger interface {
                                                                            	// Debugf formats its arguments according to the format, analogous to
                                                                            	// fmt.Printf and records the text as a log message at Debug level.
                                                                            	Debugf(format string, args ...interface{})
                                                                            
                                                                            	// Infof is like Debugf, but logs at Info level.
                                                                            	Infof(format string, args ...interface{})
                                                                            
                                                                            	// Warningf is like Debugf, but logs at Warning level.
                                                                            	Warningf(format string, args ...interface{})
                                                                            
                                                                            	// Errorf is like Debugf, but logs at Error level.
                                                                            	Errorf(format string, args ...interface{})
                                                                            
                                                                            	// LogCall is a generic logging function. This is oriented more towards
                                                                            	// utility functions than direct end-user usage.
                                                                            	LogCall(l Level, calldepth int, format string, args []interface{})
                                                                            }

                                                                              Logger interface is ultimately implemented by underlying logging libraries (like go-logging or GAE logging). It is the least common denominator among logger implementations.

                                                                              Logger instance is bound to some particular context that defines logging level and extra message fields.

                                                                              Implementations register factories that produce Loggers (using 'SetFactory' function), and top level functions (like 'Infof') use them to grab instances of Logger bound to passed contexts. That's how they know what logging level to use and what extra fields to add.

                                                                              var Null Logger = nullLogger{}

                                                                                Null is a logger that silently ignores all messages.

                                                                                func Get

                                                                                func Get(c context.Context) Logger

                                                                                  Get the current Logger, or a logger that ignores all messages if none is defined.

                                                                                  Directories

                                                                                  Path Synopsis
                                                                                  Package gologger is a compatibility layer between go-logging library and luci-go/common/logging.
                                                                                  Package gologger is a compatibility layer between go-logging library and luci-go/common/logging.
                                                                                  Package sdlogger is a logger that formats entries as JSON understood by Stackdriver log collectors.
                                                                                  Package sdlogger is a logger that formats entries as JSON understood by Stackdriver log collectors.