log

Documentation

Overview

Package log provides sensible logging defaults for Labkit.

Labkit uses Logrus for logging.

Applications that use Labkit should rely directly on Labkit.

This package provides some utility methods for working with Labkit, including:

1. Initialize Logrus in a consistent manner 1. Using GitLab's defaults with logrus 1. Passing correlation-ids between contexts and logrus

For backward compatibility reasons, the log timestamp format defaults to time.RFC3339, as done by Logrus. Additionally, for millisecond precision timestamps, it is possible to opt in for using ISO8601. At present this can be done by setting the `GITLAB_ISO8601_LOG_TIMESTAMP` environment variable to any value. ISO8601 will become the default and only format in the next major release.

Please review the examples for more details of how to use this package.

Index

• func AccessLogger(h http.Handler, opts ...AccessLoggerOption) http.Handler
• func ContextLogger(ctx context.Context) *logrus.Entry
• func Info(args ...interface{})
• func Initialize(opts ...LoggerOption) (io.Closer, error)
• func New() *logrus.Logger
• func WithContextFields(ctx context.Context, fields Fields) *logrus.Entry
• func WithError(err error) *logrus.Entry
• func WithField(key string, value interface{}) *logrus.Entry
• func WithFields(fields Fields) *logrus.Entry
• type AccessLogField
• type AccessLoggerOption
  • func WithAccessLogger(logger *logrus.Logger) AccessLoggerOption
  • func WithExtraFields(f ExtraFieldsGeneratorFunc) AccessLoggerOption
  • func WithFieldsExcluded(fields AccessLogField) AccessLoggerOption
  • func WithXFFAllowed(xffAllowed XFFAllowedFunc) AccessLoggerOption
• type ExtraFieldsGeneratorFunc
• type Fields
  • func ContextFields(ctx context.Context) Fields
• type LoggerOption
  • func WithFormatter(format string) LoggerOption
  • func WithLogLevel(level string) LoggerOption
  • func WithLogger(logger *logrus.Logger) LoggerOption
  • func WithOutputName(outputName string) LoggerOption
  • func WithTimezone(location *time.Location) LoggerOption
  • func WithWriter(writer io.Writer) LoggerOption
• type XFFAllowedFunc

Examples

• AccessLogger
• Initialize

Functions

func AccessLogger

func AccessLogger(h http.Handler, opts ...AccessLoggerOption) http.Handler

AccessLogger will generate access logs for the service.

Example

package main

import (
	"fmt"
	"net/http"

	"gitlab.com/gitlab-org/labkit/log"
)

func main() {
	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello world")
	})

	// This func is used by WithExtraFields to add additional fields to the logger
	extraFieldGenerator := func(r *http.Request) log.Fields {
		return log.Fields{"header": r.Header.Get("X-Magical-Header")}
	}

	http.ListenAndServe(":8080",
		log.AccessLogger(handler, // Add accesslogger middleware
			log.WithExtraFields(extraFieldGenerator),                          // Include custom fields into the logs
			log.WithFieldsExcluded(log.HTTPRequestReferrer|log.HTTPUserAgent), // Exclude user-agent and referrer fields from the logs
		),
	)
}

func ContextLogger

func ContextLogger(ctx context.Context) *logrus.Entry

ContextLogger will set the correlation id in the logger based on the context. This reference should not be held outside of the scope of the context.

func Info

func Info(args ...interface{})

Info is a delegator method for logrus.Info Info is an exception to our rule about discouraging non-structured use, as there are valid reasons for simply emitting a single log line.

func Initialize

func Initialize(opts ...LoggerOption) (io.Closer, error)

Initialize will configure the logger based on the options passed. It will validate the options and if validation fails drop to the defaults while logging a message to STDERR.

Example

package main

import (
	"gitlab.com/gitlab-org/labkit/log"
)

func main() {
	// Initialize the global logger
	closer, err := log.Initialize(
		log.WithFormatter("json"),    // Use JSON formatting
		log.WithLogLevel("info"),     // Use info level
		log.WithOutputName("stderr"), // Output to stderr
	)
	defer closer.Close()
	log.WithError(err).Info("This has been logged")

	// Example of configuring a non-global logger using labkit
	myLogger := log.New() // New logrus logger
	closer2, err := log.Initialize(
		log.WithLogger(myLogger),                  // Tell logkit to initialize myLogger
		log.WithFormatter("text"),                 // Use text formatting
		log.WithLogLevel("debug"),                 // Use debug level
		log.WithOutputName("/var/log/labkit.log"), // Output to `/var/log/labkit.log`
	)
	defer closer2.Close()

	log.WithError(err).Info("This has been logged")
}

func New

func New() *logrus.Logger

New is a delegator method for logrus.New.

func WithContextFields

func WithContextFields(ctx context.Context, fields Fields) *logrus.Entry

WithContextFields is a utility method for logging with context and fields.

func WithError

func WithError(err error) *logrus.Entry

WithError is a delegator method for logrus.WithError.

func WithField

func WithField(key string, value interface{}) *logrus.Entry

WithField is a delegator method for logrus.WithField.

func WithFields

func WithFields(fields Fields) *logrus.Entry

WithFields is a delegator method for logrus.WithFields.

Types

type AccessLogField

type AccessLogField uint16

AccessLogField is used to select which fields are recorded in the access log. See WithoutFields.

const (
	// CorrelationID field will record the Correlation-ID in the access log.
	CorrelationID AccessLogField = 1 << iota

	// HTTPHost field will record the Host Header in the access log.
	HTTPHost

	// HTTPRemoteIP field will record the remote caller in the access log, taking Real-IP and X-Forwarded-For headers into account.
	HTTPRemoteIP

	// HTTPRemoteAddr field will record the remote socket endpoint in the access log.
	HTTPRemoteAddr

	// HTTPRequestMethod field will record the HTTP method in the access log.
	HTTPRequestMethod

	// HTTPURI field will record the URI, including parameters.
	HTTPURI

	// HTTPProto field will record the protocol used to make the request in the access log.
	HTTPProto

	// HTTPResponseStatusCode field will record the response HTTP status code in the access log.
	HTTPResponseStatusCode

	// HTTPResponseSize field will record the response size, in bytes, in the access log.
	HTTPResponseSize

	// HTTPRequestReferrer field will record the referer header in the access log.
	HTTPRequestReferrer

	// HTTPUserAgent field will record the useragent header in the access log.
	HTTPUserAgent

	// RequestDuration field will record the request duration in the access log.
	RequestDuration

	// System field will record the system for the log entry.
	System

	// HTTPResponseContentType field will record the response content-type in the access log.
	HTTPResponseContentType

	// RequestTTFB field will record the time to the first byte being written (HTTP Header effectively)
	// in the access log. Time is recorded before an actual Write happens to ensure that this metric
	// is not affected by a slow client receiving data.
	RequestTTFB
)

type AccessLoggerOption

type AccessLoggerOption func(*accessLoggerConfig)

AccessLoggerOption will configure a access logger handler.

func WithAccessLogger

func WithAccessLogger(logger *logrus.Logger) AccessLoggerOption

WithAccessLogger configures the logger to be used with the access logger.

func WithExtraFields

func WithExtraFields(f ExtraFieldsGeneratorFunc) AccessLoggerOption

WithExtraFields allows extra fields to be passed into the access logger, based on the request.

func WithFieldsExcluded

func WithFieldsExcluded(fields AccessLogField) AccessLoggerOption

WithFieldsExcluded allows fields to be excluded from the access log. For example, backend services may not require the referer or user agent fields.

func WithXFFAllowed

func WithXFFAllowed(xffAllowed XFFAllowedFunc) AccessLoggerOption

WithXFFAllowed decides whether to trust X-Forwarded-For headers.

type ExtraFieldsGeneratorFunc

type ExtraFieldsGeneratorFunc func(r *http.Request) Fields

ExtraFieldsGeneratorFunc allows extra fields to be included in the access log.

type Fields

type Fields = logrus.Fields

Fields is an alias for the underlying logger Fields type Using this alias saves clients from having to import two distinct logging packages, which can be confusing.

func ContextFields

func ContextFields(ctx context.Context) Fields

ContextFields a logrus fields structure with the CorrelationID set.

type LoggerOption

type LoggerOption func(*loggerConfig)

LoggerOption will configure a new logrus Logger.

func WithFormatter

func WithFormatter(format string) LoggerOption

WithFormatter allows setting the format to `text`, `json`, `color` or `combined`. In case the input is not recognized it defaults to text with a warning. More details of these formats: * `text` - human readable. * `json` - computer readable, new-line delimited JSON. * `color` - human readable, in color. Useful for development. * `combined` - httpd access logs. Good for legacy access log parsers.

func WithLogLevel

func WithLogLevel(level string) LoggerOption

WithLogLevel is used to set the log level when defaulting to `info` is not wanted. Other options are: `debug`, `warn`, `error`, `fatal`, and `panic`.

func WithLogger

func WithLogger(logger *logrus.Logger) LoggerOption

WithLogger allows you to configure a proprietary logger using the `Initialize` method.

func WithOutputName

func WithOutputName(outputName string) LoggerOption

WithOutputName allows customization of the sink of the logger. Output is either: `stdout`, `stderr`, or a path to a file.

func WithTimezone

func WithTimezone(location *time.Location) LoggerOption

WithTimezone allows setting the timezone that will be used for log messages. The default behaviour is to use the local timezone, but a specific timezone (such as time.UTC) may be preferred.

func WithWriter

func WithWriter(writer io.Writer) LoggerOption

WithWriter allows the writer to be customized. The application is responsible for closing the writer manually.

type XFFAllowedFunc

type XFFAllowedFunc func(ip string) bool

XFFAllowedFunc decides whether X-Forwarded-For headers are to be trusted.