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 GetTraceparent(ctx context.Context) (*tracing.Traceparent, bool)
• func NewTraceparent() (*tracing.Traceparent, error)
• func Tracing(headerName string) func(next http.Handler) http.Handler
• func WithTraceparent(ctx context.Context, tp *tracing.Traceparent) 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) Clone(opts ...zap.Option) *Logger
  • 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 DefaultTraceHeader = "Traceparent"

DefaultTraceHeader is the default header used as a trace id.

Functions

func GetTraceparent

func GetTraceparent(ctx context.Context) (*tracing.Traceparent, bool)

GetTracing returns the tracing id from the context if it exists.

func NewTraceparent

func NewTraceparent() (*tracing.Traceparent, error)

NewTraceparent generates a new traceparent.

func Tracing

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

Tracing 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/smallstep/tracing to create a new one.

func WithTraceparent

func WithTraceparent(ctx context.Context, tp *tracing.Traceparent) context.Context

WithTraceparent returns a new context with the given tracing id added to 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) Clone

func (l *Logger) Clone(opts ...zap.Option) *Logger

Clones creates a new copy of 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 'Traceparent'.