logging

README

Logging

This package handles logging for Thelma.

It uses the zerolog and lumberjack libraries, and supports logging to two locations:

• console (stderr): pretty-formatted, defaults to info level.
• ~/.thelma/logs/thelma.log: JSON-formatted, defaults to debug level, automatically rotated

Configuration

Logging settings can be changed via Thelma configuration. Eg.

logging:
  console:
    level: debug
  file:
    level: trace

See the logConfig struct in logging.go for more configuration options.

Including Caller Information in Logs

Caller information (source file and line number) can be included in logs by setting logging.caller.enabled or THELMA_LOGGING_CALLER_ENABLED to true in config file or environment, respectively.

Usage

Clients should log messages using log.Logger:

import "github.com/rs/zerolog/log"

func doSomething() {
  	logger.Info().Str("my-useful-field", "blah").Msgf("An interesting value: %d", 123)
}

Masking Secrets

Clients can create a child of the global logger with masking for specific secrets using the WithMask function. Secrets in both message text and contextual fields will be masked.

  import "github.com/broadinstitute/thelma/internal/thelma/app/logging"

  logger := logging.WithMask("my-secret")

  // the text "my-secret" will be replaced with "******" in log messages.
  logger.Info().Str("key", "my-secret").Msg("message here")

Documentation

Index

• func Bootstrap()
• func Initialize(thelmaConfig config.Config, thelmaRoot root.Root) error
• func MaskSecret(secret ...string)
• func NewFilteredWriter(inner zerolog.LevelWriter, filterBelow zerolog.Level) zerolog.LevelWriter
• func NewWrappingWriter(inner io.Writer, opts ...func(*wordwrap.Options)) io.Writer
• type FilteredWriter
  • func (w *FilteredWriter) Write(p []byte) (n int, err error)
  • func (w *FilteredWriter) WriteLevel(level zerolog.Level, p []byte) (n int, err error)
• type MaskingWriter
  • func NewMaskingWriter(inner io.Writer) *MaskingWriter
  • func (w *MaskingWriter) MaskSecrets(secrets ...string)
  • func (w *MaskingWriter) Write(p []byte) (n int, err error)
  • func (w *MaskingWriter) WriteLevel(level zerolog.Level, p []byte) (n int, err error)
• type WrappingWriter
  • func (w *WrappingWriter) Write(p []byte) (n int, err error)

Functions

func Bootstrap

func Bootstrap()

Bootstrap configure global zerolog logger with a basic console logger to catch any messages that are logged before full Thelma initialization

func Initialize

func Initialize(thelmaConfig config.Config, thelmaRoot root.Root) error

Initialize updates the global Zerolog logger to match Thelma's configuration. It should be called once during Thelma initialization.

func MaskSecret

func MaskSecret(secret ...string)

MaskSecret configures the global logger to mask the given secret(s)

func NewFilteredWriter

func NewFilteredWriter(inner zerolog.LevelWriter, filterBelow zerolog.Level) zerolog.LevelWriter

func NewWrappingWriter

func NewWrappingWriter(inner io.Writer, opts ...func(*wordwrap.Options)) io.Writer

Types

type FilteredWriter

type FilteredWriter struct {
	// contains filtered or unexported fields
}

FilteredWriter drops log messages below a specified threshold

func (*FilteredWriter) Write

func (w *FilteredWriter) Write(p []byte) (n int, err error)

func (*FilteredWriter) WriteLevel

func (w *FilteredWriter) WriteLevel(level zerolog.Level, p []byte) (n int, err error)

type MaskingWriter

type MaskingWriter struct {
	// contains filtered or unexported fields
}

MaskingWriter replaces sensitive text in log messages

func NewMaskingWriter

func NewMaskingWriter(inner io.Writer) *MaskingWriter

func (*MaskingWriter) MaskSecrets

func (w *MaskingWriter) MaskSecrets(secrets ...string)

func (*MaskingWriter) Write

func (w *MaskingWriter) Write(p []byte) (n int, err error)

Note that Zerolog guarantees log messages won't be split up across multiple Write calls: "Each logging operation makes a single call to the Writer's Write method." (https://github.com/rs/zerolog/blob/e9344a8c507b5f25a4962ff022526be0ddab8e72/log.go#L210) So we don't need to worry about secrets potentially being split across multiple writes.

func (*MaskingWriter) WriteLevel

func (w *MaskingWriter) WriteLevel(level zerolog.Level, p []byte) (n int, err error)

type WrappingWriter

type WrappingWriter struct {
	// contains filtered or unexported fields
}

WrappingWriter wraps lines in log messages to a given width

func (*WrappingWriter) Write

func (w *WrappingWriter) Write(p []byte) (n int, err error)