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 InitializeLogging(thelmaConfig config.Config, thelmaRoot root.Root) error
• func NewFilteredWriter(inner zerolog.LevelWriter, filterBelow zerolog.Level) zerolog.LevelWriter
• func NewMaskingWriter(inner io.Writer, secrets []string) zerolog.LevelWriter
• func WithMask(secrets ...string) zerolog.Logger
• 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 (w *MaskingWriter) Write(p []byte) (n int, err error)
  • func (w *MaskingWriter) WriteLevel(level zerolog.Level, 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 InitializeLogging

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

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

func NewFilteredWriter

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

func NewMaskingWriter

func NewMaskingWriter(inner io.Writer, secrets []string) zerolog.LevelWriter

func WithMask

func WithMask(secrets ...string) zerolog.Logger

WithMask return a copy of the global logger that will mask the given secrets

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 (*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)