logging

README

logging

Logging is a collection of collection of packages to make easy the logging experience.

Logging is currently in active development and it's API WILL CHANGE WITHOUT NOTICE.

logging/httplog - the HTTP middleware

Httplog implements and HTTP middleware that can optionally log the raw request and responses.

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/smallstep/logging"
    "github.com/smallstep/logging/httplog"
)

func main() {
    logger, err := logging.New("scim",
        logging.WithLogResponses(),
        logging.WithLogRequests(),
    )
    if err != nil {
        log.Fatal(err)
    }

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello World!")
    })

    srv := &http.Server{
        Addr:    ":8080",
        Handler: httplog.Middleware(logger, http.DefaultServeMux),
    }

    logger.Infof("start listening at %s.", srv.Addr)
    log.Fatal(srv.ListenAndServe())
}

A simple curl http://localhost:8080 will print the following logs:

$ go run examples/httplog.go
{"level":"info","ts":1582944317.382856,"caller":"logging/logger.go:87","msg":"start listening at :8080."}
{"level":"info","ts":1582944330.861353,"caller":"httplog/handler.go:121","msg":"","name":"scim","request-id":"bpct0ijipt3avli7utp0","remote-address":"::1","time":"2020-02-28T18:45:30-08:00","duration":0.000064785,"duration-ns":64785,"method":"GET","path":"/","protocol":"HTTP/1.1","status":200,"size":13,"referer":"","user-agent":"curl/7.64.1","request":"R0VUIC8gSFRUUC8xLjENCkhvc3Q6IGxvY2FsaG9zdDo4MDgwDQpBY2NlcHQ6ICovKg0KVXNlci1BZ2VudDogY3VybC83LjY0LjENClgtVHJhY2UtSWQ6IGJwY3QwaWppcHQzYXZsaTd1dHAwDQoNCg==","response":"SGVsbG8gV29ybGQhCg=="}

Documentation

Index

• Constants
• func GetRequestID(ctx context.Context) (string, bool)
• func GetUserID(ctx context.Context) (string, bool)
• func NewRequestID() string
• func RequestID(headerName string) func(next http.Handler) http.Handler
• func WithRequestID(ctx context.Context, requestID string) context.Context
• func WithUserID(ctx context.Context, userID string) context.Context
• type CommonLogFormat
  • func (f *CommonLogFormat) Format(entry *logrus.Entry) ([]byte, error)
• type Logger
  • func New(name string, opts ...Option) (*Logger, error)
  • func (l *Logger) Debugf(format string, args ...interface{})
  • func (l *Logger) Errorf(format string, args ...interface{})
  • func (l *Logger) Infof(format string, args ...interface{})
  • func (l *Logger) LogRequests() bool
  • func (l *Logger) LogResponses() bool
  • func (l *Logger) Name() string
  • func (l *Logger) Sync() error
  • func (l *Logger) TimeFormat() string
  • func (l *Logger) TraceHeader() string
  • func (l *Logger) Warnf(format string, args ...interface{})
• type Option
  • func WithConfig(raw json.RawMessage) Option
  • func WithFormatJSON() Option
  • func WithFormatText() Option
  • func WithLogRequests() Option
  • func WithLogResponses() Option
  • func WithTimeFormat(format string) Option
  • func WithTraceHeader(name string) Option

Constants

const (
	// RequestIDKey is the context key that should store the request identifier.
	RequestIDKey key = iota
	// UserIDKey is the context key that should store the user identifier.
	UserIDKey
)

Functions

func GetRequestID

func GetRequestID(ctx context.Context) (string, bool)

GetRequestID returns the request id from the context if it exists.

func GetUserID

func GetUserID(ctx context.Context) (string, bool)

GetUserID returns the request id from the context if it exists.

func NewRequestID

func NewRequestID() string

NewRequestID creates a new request id using github.com/rs/xid.

func RequestID

func RequestID(headerName string) func(next http.Handler) http.Handler

RequestID returns a new middleware that gets the given header and sets it in the context so it can be written in the logger. If the header does not exists or it's the empty string, it uses github.com/rs/xid to create a new one.

func WithRequestID

func WithRequestID(ctx context.Context, requestID string) context.Context

WithRequestID returns a new context with the given requestID added to the context.

func WithUserID

func WithUserID(ctx context.Context, userID string) context.Context

WithUserID decodes the token, extracts the user from the payload and stores it in the context.

Types

type CommonLogFormat

type CommonLogFormat struct{}

CommonLogFormat implements the logrus.Formatter interface it writes logrus entries using a CLF format prepended by the request-id.

func (*CommonLogFormat) Format

func (f *CommonLogFormat) Format(entry *logrus.Entry) ([]byte, error)

Format implements the logrus.Formatter interface. It returns the given logrus entry as a CLF line with the following format:

<request-id> <remote-address> <name> <user-id> <time> <duration> "<method> <path> <protocol>" <status> <size>

If a field is not known, the hyphen symbol (-) will be used.

type Logger

type Logger struct {
	*zap.Logger
	// contains filtered or unexported fields
}

Logger is a request logger that uses zap.Logger as core.

func New

func New(name string, opts ...Option) (*Logger, error)

New initializes the logger with the given options.

func (*Logger) Debugf

func (l *Logger) Debugf(format string, args ...interface{})

func (*Logger) Errorf

func (l *Logger) Errorf(format string, args ...interface{})

func (*Logger) Infof

func (l *Logger) Infof(format string, args ...interface{})

func (*Logger) LogRequests

func (l *Logger) LogRequests() bool

LogResponses returns if the logging of requests is enabled.

func (*Logger) LogResponses

func (l *Logger) LogResponses() bool

LogResponses returns if the logging of responses is enabled.

func (*Logger) Name

func (l *Logger) Name() string

Name returns the logging name.

func (*Logger) Sync

func (l *Logger) Sync() error

Sync calls the underlying Core's Sync method, flushing any buffered log entries. Applications should take care to call Sync before exiting.

func (*Logger) TimeFormat

func (l *Logger) TimeFormat() string

TimeFormat returns the configured time format.

func (*Logger) TraceHeader

func (l *Logger) TraceHeader() string

GetTraceHeader returns the trace header configured.

func (*Logger) Warnf

func (l *Logger) Warnf(format string, args ...interface{})

type Option

type Option func(o *options) error

Options is the type used to modify logger options.

func WithConfig

func WithConfig(raw json.RawMessage) Option

WithConfig uses a JSON to configure the logger.

func WithFormatJSON

func WithFormatJSON() Option

WithFormatJSON configures the format of the logs as JSON. Defaults to text.

func WithFormatText

func WithFormatText() Option

WithFormatText configures the format of the logs as text. Defaults to text.

func WithLogRequests

func WithLogRequests() Option

WithLogRequests enables the log of the requests.

func WithLogResponses

func WithLogResponses() Option

WithLogResponses enables the log of responses

func WithTimeFormat

func WithTimeFormat(format string) Option

WithTimeFormat sets a specific format for the time fields.

func WithTraceHeader

func WithTraceHeader(name string) Option

WithTraceHeader defines the name of the header used for tracing. Defaults to 'X-Trace-ID'.