log

Documentation

Index

• Variables
• func Debugf(s string, args ...interface{})
• func SetDebugOutput(w io.Writer)
• func ToContext(ctx context.Context, logger *Entry) context.Context
• type ClientFields
• type ContextFields
• type Entry
  • func Extract(ctx context.Context) *Entry
  • func NewEntry(logger *Logger) *Entry
  • func (entry *Entry) ExtractClient(protocol RequestProtocol) ClientFields
  • func (entry *Entry) ExtractContext() ContextFields
  • func (entry *Entry) ExtractServer(protocol RequestProtocol) ServerFields
  • func (entry *Entry) WithClient(protocol RequestProtocol, fields ClientFields) *Entry
  • func (entry *Entry) WithContext(fields ContextFields) *Entry
  • func (entry *Entry) WithError(err error) *Entry
  • func (entry *Entry) WithField(name string, value interface{}) *Entry
  • func (entry *Entry) WithFields(fields Fields) *Entry
  • func (entry *Entry) WithMetrics(fields MetricsFields) *Entry
  • func (entry *Entry) WithProcessMetricsFields(fields ProcessMetricsFields) *Entry
  • func (entry *Entry) WithRequest(protocol RequestProtocol, fields PayloadFields) *Entry
  • func (entry *Entry) WithResponse(protocol RequestProtocol, fields PayloadFields) *Entry
  • func (entry *Entry) WithScope(scope string) *Entry
  • func (entry *Entry) WithServer(protocol RequestProtocol, fields ServerFields) *Entry
• type Fields
• type Logger
  • func NewLogger(opts Options, out io.Writer) *Logger
  • func (l *Logger) NewEntry() *Entry
  • func (l *Logger) WithField(name string, value interface{}) *Entry
  • func (l *Logger) WithFields(fields Fields) *Entry
  • func (l *Logger) WithScope(value string) *Entry
• type MetricsFields
• type Options
• type PayloadFields
• type ProcessMetricsFields
• type RequestProtocol
• type ServerFields

Variables

var (
	NullLogger = NewLogger(Options{}, ioutil.Discard)

	DefaultLogger = NewLogger(Options{Level: "error"}, os.Stdout)
)

var NilWriter io.Writer = new(nilWriter)

Functions

func Debugf

func Debugf(s string, args ...interface{})

func SetDebugOutput

func SetDebugOutput(w io.Writer)

func ToContext

func ToContext(ctx context.Context, logger *Entry) context.Context

Types

type ClientFields

type ClientFields ServerFields

ClientFields is same as ServerFields, except you should set Kind to `client`.

type ContextFields

type ContextFields struct {

	// TraceID is usually used to trace requests between services. It is
	// usually provided by other services.
	TraceID string `json:"trace_id,omitempty"`

	// RequestID is usually generated by request entry point.
	// For example, in your first request middleware.
	RequestID string `json:"request_id,omitempty"`

	// UserID is used to record user's ID. In case any server use it.
	UserID string `json:"user_id,omitempty"`

	// DeviceID is used to record the device handling current progress.
	DeviceID string `json:"device_id,omitempty"`

	// TargetID is an abstract id field. It can be anything in your system.
	TargetID string `json:"target_id,omitempty"`

	// TargetType is used to indicate target type.
	TargetType string `json:"target_type,omitempty"`

	// ObjectID is an abstract id field like TargetID.
	ObjectID string `json:"object_id,omitempty"`
}

ContextFields contains values travel through the hole request or job.

type Entry

type Entry struct {
	*logrus.Entry
}

Entry is wrapper of logrus.Entry which provides some methods to log structured data.

func Extract

func Extract(ctx context.Context) *Entry

func NewEntry

func NewEntry(logger *Logger) *Entry

func (*Entry) ExtractClient

func (entry *Entry) ExtractClient(protocol RequestProtocol) ClientFields

ExtractClient returns the client fields in the current entry, in case someone want to attach additional data to it.

func (*Entry) ExtractContext

func (entry *Entry) ExtractContext() ContextFields

ExtractContext returns the context fields in the current entry, in case someone want to attach additional data to it.

func (*Entry) ExtractServer

func (entry *Entry) ExtractServer(protocol RequestProtocol) ServerFields

ExtractServer returns the server fields in the current entry, in case someone want to attach additional data to it.

func (*Entry) WithClient

func (entry *Entry) WithClient(protocol RequestProtocol, fields ClientFields) *Entry

WithClient is much like WithServer except it is used to log outgoing requests.

func (*Entry) WithContext

func (entry *Entry) WithContext(fields ContextFields) *Entry

WithContext attach some context data to the logger. Context data is used to trace your requests or jobs.

func (*Entry) WithError

func (entry *Entry) WithError(err error) *Entry

WithError is wrapper of logrus.Entry.WithError

func (*Entry) WithField

func (entry *Entry) WithField(name string, value interface{}) *Entry

WithField is wrapper of logrus.Entry.WithField. You SHOULD NOT use it in your code.

func (*Entry) WithFields

func (entry *Entry) WithFields(fields Fields) *Entry

WithFields is wrapper of logrus.Entry.WithFields. You SHOULD NOT use it in your code.

func (*Entry) WithMetrics

func (entry *Entry) WithMetrics(fields MetricsFields) *Entry

WithMetrics is used to log metrics data.

func (*Entry) WithProcessMetricsFields

func (entry *Entry) WithProcessMetricsFields(fields ProcessMetricsFields) *Entry

func (*Entry) WithRequest

func (entry *Entry) WithRequest(protocol RequestProtocol, fields PayloadFields) *Entry

WithRequest is used to log request payload.

func (*Entry) WithResponse

func (entry *Entry) WithResponse(protocol RequestProtocol, fields PayloadFields) *Entry

WithResponse is used to log response payload.

func (*Entry) WithScope

func (entry *Entry) WithScope(scope string) *Entry

WithScope indicate the logging scope. Scope can be a function name, a job name, a request name, or even a project name.

func (*Entry) WithServer

func (entry *Entry) WithServer(protocol RequestProtocol, fields ServerFields) *Entry

WithServer attach some information about requests on the server. It's something like Nginx or Apache access log, but it is strictly structured.

type Fields

type Fields = logrus.Fields

type Logger

type Logger struct {
	*logrus.Logger
}

Logger hold a logrus.Logger

func NewLogger

func NewLogger(opts Options, out io.Writer) *Logger

New create a logrus entry instance and return

func (*Logger) NewEntry

func (l *Logger) NewEntry() *Entry

NewEntry creates an Entry object based on current Logger.

func (*Logger) WithField

func (l *Logger) WithField(name string, value interface{}) *Entry

func (*Logger) WithFields

func (l *Logger) WithFields(fields Fields) *Entry

func (*Logger) WithScope

func (l *Logger) WithScope(value string) *Entry

type MetricsFields

type MetricsFields struct {

	// Name is the metrics name. It is something can describe your metrics.
	Name string `json:"name,omitempty"`

	// Value si the metrics value. Usually int64 is enough for logging metrics.
	Value int64 `json:"value"`
}

MetricsFields is used to log system metrics. It contains the metrics name and value.

type Options

type Options struct {
	Formatter string `yaml:"formatter" mapstructure:"formatter"`
	Level     string `yaml:"level" mapstructure:"level"`
	Mode      string `yaml:"mode" mapstructure:"mode"`
}

Options configuration for logrus

type PayloadFields

type PayloadFields struct {

	// Content is body content. It uses `interface{}` type to provide flexibility to
	// log raw request content as string or structure content.
	Content interface{} `json:"content,omitempty"`
}

PayloadFields is used to log request payload, either request body or response body.

type ProcessMetricsFields

type ProcessMetricsFields struct {
	// Goroutine is the number of goroutine
	Goroutine int `json:"goroutine,omitempty"`

	// Alloc is bytes of allocated heap objects.
	Alloc uint64 `json:"alloc,omitempty"`

	// TotalAlloc is cumulative bytes allocated for heap objects.
	TotalAlloc uint64 `json:"total_alloc,omitempty"`

	// Sys is the total bytes of memory obtained from the OS.
	Sys uint64 `json:"sys,omitempty"`

	// Mallocs is the cumulative count of heap objects allocated.
	Mallocs uint64 `json:"mallocs,omitempty"`

	// Frees is the cumulative count of heap objects freed.
	Frees uint64 `json:"frees,omitempty"`

	// LiveObject is the number of live objects is Mallocs - Frees.
	LiveObjects uint64 `json:"live_objects,omitempty"`

	// HeapObjects is the number of allocated heap objects.
	HeapObjects uint64 `json:"heap_objects,omitempty"`

	// PauseTotalNs is the cumulative nanoseconds in GC
	// stop-the-world pauses since the program started.
	PauseTotalNs uint64 `json:"pause_total_ns,omitempty"`

	// NumGC is the number of completed GC cycles.
	NumGC uint32 `json:"num_gc,omitempty"`
}

ProcessMetricsFields is use to log process states

type RequestProtocol

type RequestProtocol string

const (
	ProtocolHTTP RequestProtocol = "http"
	ProtocolGRPC RequestProtocol = "grpc"
	ProtocolTCP  RequestProtocol = "tcp"
)

type ServerFields

type ServerFields struct {

	// Host is request host.
	Host string `json:"host,omitempty"`

	// Remote is address where the request come from.
	Remote string `json:"remote,omitempty"`

	// Method refers HTTP request method if server type is HTTP. It refers
	// service name if server type is gRPC.
	Method string `json:"method,omitempty"`

	// URI is request path. It is used when Kind is server.
	URI string `json:"uri,omitempty"`

	// URL is request url. It is used when Kind is client.
	URL string `json:"url,omitempty"`

	// Referer is just the HTTP Referer.
	Referer string `json:"referer,omitempty"`

	// UserAgent is HTTP User-Agent header.
	UserAgent string `json:"ua,omitempty"`

	// Status is HTTP response status code.
	Status int `json:"status,omitempty"`

	// Service is used by gRPC server.
	Service string `json:"service,omitempty"`

	// Code is usually means gRPC response code.
	Code string `json:"code,omitempty"`

	// Kind is used to indicate if it is server or client.
	Kind string `json:"kind,omitempty"`
}

ServerFields contains request basic information on server. Kind should be set to `server`.