golog

README

golog

golog is a logger for the Go programming language.

Logging Levels

The logging levels shown below are provided by this logger, and are colorized if the logger is initialized with colorize = true.

• Info ( Presented in the terminal's native colors )
• Debug ( green text on the terminal's native background )
• Warning ( yellow text on the terminal's native background )
• Error ( red text on the terminal's native background )
• Fatal ( white text on a red background )
• Panic ( white text on a red background )

Logging Modes

The logger may be set up to run in the three modes listed below. These modes are defined in logging_output_modes.go:

• ModeScreen - Output logs to STDOUT
• ModeFile - Output logs to a user provided file
• ModeBoth - Output logs to both STDOUT and a user provided file

Startup Actions

Upon initialization of the logger, the user may specify what to do with an existing log file if the user has specified ModeFile or ModeBoth as their logging mode.

The following actions may be taken. These actions are defined in logging_file_actions.go:

• FileActionAppend - If the log file to which the user is writing already exists, add new logs onto it
• FileActionCompress - If the log file to which the user is writing already exists, compress it into a .gz file
• FileActionDelete - If the log file to which the user is writing already exists, delete it

The user may also specify FileActionNone. For now, this is logically equivalent to passing in FileAppend.

Initialization

The logger is a structure that may be initialized by the functions defined below

Raw Initializaion

The following arguments are passed in during initialization by calling SetupLoggerFromFields:

• logMode (LoggingOutputMode) - The mode the logger will operate in, as described in Logging Modes
• logFileStartupAction (LoggingFileAction) - Startup action taken by the logger as described in section Startup Actions
• logDirectory (string) - If logMode is Both or File, this is the directory to which the logger will write logs.
• logFile (string) - If the logMode is Both or File, this is the file to which the logger will write logs.
• shouldColorize (bool) - If set to true logging will be colorized as described in section Logging Modes.
• isMock (bool) - If set to true all filesystem ops will be stubbed by a fake filesystem as defined by afero
• isAsynch (bool) - If set to true perform all logging asynchly in a seperate goroutine

For example:

logger := golog.SetupLoggerFromFields(golog.ModeBoth, golog.FileActionNone, "/path/to/log/file", "file.log", true, false, true)

Initialization From Struct

The logger may be initialized by creating a LoggingConfig struct and passing it to SetupLoggerFromStruct.

The definition for the struct is shown below:

type LoggingConfig struct {
	Name                 string            // The logger profile name
	LogMode              LoggingOutputMode // The logging mode
	LogFileStartupAction LoggingFileAction // The action the logger will take on startup
	LogDirectory         string            // The directory to which the logger writes
	LogFile              string            // The name of the log file to write to
	ShouldColorize       bool              // Indicates if we should output information in color
	IsMock               bool              // If true, mock the filesystem via 'afero'
	IsAsynch             bool              // If true, Asynchly handle log requests
}

A sample initialization would thus be as follows:

config := golog.LoggingConfig{LogMode: golog.Both, LogDirectory: "/dir/to/my/go/project", LogFile: "important.log", ShouldColorize: true, IsMock: false, IsAsynch: true}
logger := golog.SetupLoggerFromStruct(&config)

Initialization From JSON File

The logger may be initialized by specifying the path to a JSON file that contains its definition to SetupLoggerFromConfigFile along with the configuration profile name name. The name is what you have chosen to name a current configuration.

A sample configuration file containing 3 profiles is shown below. Note how each entry has a configuration name name.

[{
	"name": "test1",
	"logMode": 1,                            // ModeFile
	"logFileStartupAction": 1,               // FileActionAppend
	"logDirectory": "/dir/to/my/go/project",
	"logFile": "test1.log",
	"shouldColorize": true,
	"isMock": true,
	"isAsynch": false
}, {
	"name": "test2",
	"logMode": 2,                            // ModeScreen 
	"logFileStartupAction": 2,               // FileActionCompress
	"logDirectory": "/dir/to/my/go/project",
	"logFile": "test2.log",
	"shouldColorize": true,
	"isMock": false,
	"isAsynch": false
}, {
	"name": "test3",
	"logMode": 3,                            // ModeBoth
	"logFileStartupAction": 3,               // FileActionDelete
	"logDirectory": "/dir/to/my/go/project",
	"logFile": "test3.log",
	"shouldColorize": true,
	"isMock": true,
	"isAsynch": true
}]

If we wanted to initialize a logger to have the profile of test1, we would do the following:

var profile = "test1"
var configFile = "/path/to/my/config/config.json"
logger := golog.SetupLoggerFromConfigFile(configFile, profile)

Documentation

Overview

Terminal colors used by the logger

Actions logger will take regarding physical log files on disk

Logging level constants

Logging output modes

Index

• type Logger
  • func SetupLoggerFromConfigFile(fullFilePath string, profile string) (Logger, error)
  • func SetupLoggerFromFields(logMode LoggingOutputMode, logFileStartupAction LoggingFileAction, ...) (Logger, error)
  • func SetupLoggerFromStruct(config *LoggingConfig) (Logger, error)
  • func (logger *Logger) Debug(logText string)
  • func (logger *Logger) Err(logText string)
  • func (logger *Logger) Fatal(logText string)
  • func (logger *Logger) Info(logText string)
  • func (logger *Logger) IsUninitialized() bool
  • func (logger *Logger) Panic(logText string)
  • func (logger *Logger) SetContext(context string)
  • func (logger *Logger) Shutdown()
  • func (logger *Logger) Warning(logText string)
• type LoggingColor
  • func (color LoggingColor) String() string
• type LoggingConfig
• type LoggingFileAction
  • func (fileAction LoggingFileAction) IsValidFileAction() bool
• type LoggingLevel
  • func (level LoggingLevel) String() string
• type LoggingOutputMode
  • func (mode LoggingOutputMode) Int() int
  • func (mode LoggingOutputMode) IsValidMode() bool
  • func (mode LoggingOutputMode) String() string

Types

type Logger

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

Logger is representative of the logger for use in other go programs

The following methods are exposed by this structure ( defined in golog.go ):

Debug(logText string): Log debug output to log destination
Info(logText string): Log info output to log destination
Warning(logText string): Log warning output to log destination
Err(logText string): Log error output to log destination
Fatal(logText string): Log fatal output to log destination
Is_Uninitialized: Returns true if this structure has not been allocated

func SetupLoggerFromConfigFile

func SetupLoggerFromConfigFile(fullFilePath string, profile string) (Logger, error)

func SetupLoggerFromConfigFile sets up and returns a logger instance as specified in 'fullFilePath' for 'profile'

func SetupLoggerFromFields

func SetupLoggerFromFields(logMode LoggingOutputMode, logFileStartupAction LoggingFileAction, logDirectory string, logFile string, shouldColorize bool, isMock bool, isAsynch bool) (Logger, error)

func SetupLoggerFromFields sets up and returns a logger instance from passed in individual fields

func SetupLoggerFromStruct

func SetupLoggerFromStruct(config *LoggingConfig) (Logger, error)

func SetupLoggerFromStruct sets up and returns a logger instance from a LoggingConfigStruct

func (*Logger) Debug

func (logger *Logger) Debug(logText string)

Debug Outputs debug log information to the logging destination

func (*Logger) Err

func (logger *Logger) Err(logText string)

Err Outputs error information to the logging destination

func (*Logger) Fatal

func (logger *Logger) Fatal(logText string)

Fatal Outputs fatal information to the logging desination but does not cause a panic, use 'Panic' instead.

func (*Logger) Info

func (logger *Logger) Info(logText string)

Info Outputs info log information to the logging destination

func (*Logger) IsUninitialized

func (logger *Logger) IsUninitialized() bool

IsUninitialized Returns true if this structure has not yet been allocated since logging mode is private to golog, package users can never set 'logging mode' without using a logger setup method

func (*Logger) Panic

func (logger *Logger) Panic(logText string)

Panic Outputs fatal information to the logging desination and causes a panic

func (*Logger) SetContext

func (logger *Logger) SetContext(context string)

SetContext is called on the logger to the set its context. See 'Context' in the logging struct for more information

func (*Logger) Shutdown

func (logger *Logger) Shutdown()

Shutdown flushes the logger and outputs any remaining messages in its queue if it is asynch one should always call shutdown to ensure all messages are logged correctly

func (*Logger) Warning

func (logger *Logger) Warning(logText string)

Warning Outputs warning information to the logging destination

type LoggingColor

type LoggingColor string

These are constants for terminal colors

func (LoggingColor) String

func (color LoggingColor) String() string

type LoggingConfig

type LoggingConfig struct {
	Name                 string            // The logger profile name
	LogMode              LoggingOutputMode // The logging mode
	LogFileStartupAction LoggingFileAction // The action the logger will take on startup
	LogDirectory         string            // The directory to which the logger writes
	LogFile              string            // The name of the log file to write to
	ShouldColorize       bool              // Indicates if we should output information in color
	IsMock               bool              // If true, mock the filesystem via 'afero'
	IsAsynch             bool              // If true, Asynchly handle log requests
}

LoggingConfig holds a logging configuration for the logger and is used during logger initialization

type LoggingFileAction

type LoggingFileAction int

const (
	FileActionAppend   LoggingFileAction = iota + 1 // Instructs the logger to append onto an existing log if one exists
	FileActionCompress                              // Instructs the logger to compress an existing log file if one exists
	FileActionDelete                                // Instructs the logger to remove an existing log file if one exits
	FileActionNone                                  // Indicates no file actions ( e.g.: when user is writing to screen only )
)

func (LoggingFileAction) IsValidFileAction

func (fileAction LoggingFileAction) IsValidFileAction() bool

type LoggingLevel

type LoggingLevel string

Logging levels for the logger

func (LoggingLevel) String

func (level LoggingLevel) String() string

type LoggingOutputMode

type LoggingOutputMode int

const (
	ModeFile   LoggingOutputMode = iota + 1 // ModeFile indicates information will be outputted to a log file
	ModeScreen                              // ModeScreen indicates information will be outputted to the screen
	ModeBoth                                // ModeBoth indicates information will be outted to both file and screen
)

func (LoggingOutputMode) Int

func (mode LoggingOutputMode) Int() int

func (LoggingOutputMode) IsValidMode

func (mode LoggingOutputMode) IsValidMode() bool

func (LoggingOutputMode) String

func (mode LoggingOutputMode) String() string