log

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 9, 2020 License: Apache-2.0 Imports: 11 Imported by: 0

README

Readme

Package log supports logging to a managed set of log files.

The logger is configured by a JSON file called log.config or <exe>.log.config. If <exe>.log.config exists in the same directory as other log.config files, it will be used for the executable: <exe>, which is equal to os.Executable(). All executables, <exe>, for which there is no <exe>.log.config will use log.config if it exists. If there are no log config files in the working directory of an executable, the logging defaults will be used (see godocs for config).

The following is a JSON configuration structure containing the default logger paramerters:

{
	"RootDir": "/usr/local/var/log",
	"NumFiles": 3,
	"FileNumBytes": 1000000,
	"Priority": "INFO",
	"SuppressedFiles": ""
}

The logger reads log.config periodically. The logger uses changed parameters. The log.config can be changed while the program is running and further logging reflects the changed log.config.

The logger initialises and closes automatically.

log.Panic(...) and log.Panicf(...) log a stack trace in addition to the log message, close the open log file and call os.Exit(1).

The logger will automatically tag every log message with time, the source file and line number of the call to log.

If the logger priority is DEBUG the logger can be configured to suppress the debug messages from one or more files by providing a comma separated string to the suppressFilesDebug parameter of log.Init(...). The components of the string correspond to file names without extension. E.g.: "pkga,pkgb" will suppress debug messages from pkga.go and pkgb.go.

Package log supports four Priority levels in decreasing order of priority: Panic, Warning, Info, Debug. The logger instance has two methods to log a message of each Priority: and f, e.g.: Info and Infof. takes a string parameter, while f takes a format string followed by a list of parameters. The format of the f format string parameter is the same as for fmt.Printf.

The logger is initialised with the minimum priority level. The logger discards all messages logged with a lower priority.

The directory log/examples demonstrates some featurs of log:

examples/basic:
	Shows the basic usage of the log package.

examples/set_config:
	Shows a change of log file size and debug level on a live program.

examples/suppress_files:
	Shows the suppression of debug message from a selection of files

examples/basic:

log.config:
{
	"RootDir": "logs",
}

Rootdir sets the logging directory to the directory "logs" under the working directory. The other Config parameters will take their default values.

package main

import (
	"github.com/goccmack/goutil/log/example/pkga"

	"github.com/goccmack/goutil/log"
)

package main

import (
	"github.com/goccmack/goutil/log/examples/basic/pkga"

	"github.com/goccmack/goutil/log"
)

func main() {
	// Log something
	log.Info("This message WILL appear in the log")

	pkga.Go()
	// Give pkga time to log a message
	time.Sleep(time.Millisecond)

	log.Debug("This message will NOT appear in the log")
	log.Panic("This is a panic")
}

======================

package pkga

import (
	"github.com/goccmack/goutil/log"
)

func Go() {
	// Log something
	log.Debug("This is pkga")
}

The resulting log is:

File set configuration @ 2018-12-20T12:07:58.555278+01:00
Maximum file size 1000000 bytes
Maximum 3 files
2018-12-20T12:07:58.555087+01:00 Log configuration:
RootDir: logs
NumFiles: 3
NumBytes: 1000000
Priority: INFO
Suppress:
2018-12-20T12:07:58.555464+01:00 [INFO] -main.go, line 14- This message WILL appear in the log
2018-12-20T12:07:58.555482+01:00 [INFO] -pgka.go, line 9- This is pkga
2018-12-20T12:07:58.555495+01:00 [PANIC] -main.go, line 19- This is a panic
goroutine 1 [running]:
github.com/goccmack/goutil/log.getPanicStackTrace(0x10bea8e, 0x3)
	.../github.com/goccmack/goutil/log/interface.go:138 +0x74
github.com/goccmack/goutil/log.Panic(0x10fac35, 0xf)
	.../github.com/goccmack/goutil/log/interface.go:96 +0x22
main.main()
	.../github.com/goccmack/goutil/log/examples/basic/main.go:19 +0x8d

Documentation

Overview

Package log supports logging to a managed set of log files.

The logger is configured by a JSON file called <component>.log.config. <component> is the name of the go binary executable (os.Executable()). The logger looks for the log config file in $PWD.

The following is a JSON configuration structure containing the default logger paramerters: 

{
	"RootDir": "/usr/local/var/log",
	"NumFiles": 3,
	"FileNumBytes": 1000000,
	"Priority": "INFO",
	"SuppressedFiles": ""
}

If the working directory does not contain a log.config file the logger uses these parameters. All fields of log.config are optional. The logger will used default values for missing parameters.

The logger reads log.config periodically. The logger uses changed parameters. The log.config can be changed while the program is running and further logging reflects the changed log.config.

The logger initialises and closes automatically but log.Close() should be called to ensure that the last logged items are properly flushed before the program terminates.

log.Panic(...) and log.Panicf(...) log a stack trace in addition to the log message, close the open log file and call os.Exit(1).

The logger will automatically tag every log message with time, the source file and line number of the call to log.

If the logger priority is DEBUG the logger can be configured to suppress the debug messages from one or more files by providing a comma separated string to the suppressFilesDebug parameter of log.Init(...). The components of the string correspond to file names without extension. E.g.: "pkga,pkgb" will suppress debug messages from pkga.go and pkgb.go.

Package log supports four Priority levels in decreasing order of priority: Panic, Warning, Info, Debug. The logger instance has two methods to log a message of each Priority: <Priority> and <Priority>f, e.g.: Info and Infof. <Priority> takes a string parameter, while <Priority>f takes a format string followed by a list of parameters. The format of the <Priorty>f format string parameter is the same as for fmt.Printf.

The logger is initialised with the minimum priority level. The logger discards all messages logged with a lower priority.

The directory log/examples demonstrates some featurs of log: 

examples/basic:
	Shows the basic usage of the log package.

examples/set_config:
	Shows a change of log file size and debug level on a live program.

examples/suppress_files:
	Shows the suppression of debug message from a selection of files

examples/basic: 

log.config:
{
	"RootDir": "logs",
}

Rootdir sets the logging directory to the directory "logs" under the working directory. The other Config parameters will take their default values. 

package main

import (
	"github.com/goccmack/goutil/log/example/pkga"

	"github.com/goccmack/goutil/log"
)

package main

import (
	"github.com/goccmack/goutil/log/examples/basic/pkga"

	"github.com/goccmack/goutil/log"
)

func main() {
	// Log something
	log.Info("This message WILL appear in the log")

	pkga.Go()
	// Give pkga time to log a message
	time.Sleep(time.Millisecond)

	log.Debug("This message will NOT appear in the log")
	log.Panic("This is a panic")
}

======================

package pkga

import (
	"github.com/goccmack/goutil/log"
)

func Go() {
	// Log something
	log.Debug("This is pkga")
}

The resulting log is: 

File set configuration @ 2018-12-20T12:07:58.555278+01:00
Maximum file size 1000000 bytes
Maximum 3 files
2018-12-20T12:07:58.555087+01:00 Log configuration:
RootDir: logs
NumFiles: 3
NumBytes: 1000000
Priority: INFO
Suppress:
2018-12-20T12:07:58.555464+01:00 [INFO] -main.go, line 14- This message WILL appear in the log
2018-12-20T12:07:58.555482+01:00 [INFO] -pgka.go, line 9- This is pkga
2018-12-20T12:07:58.555495+01:00 [PANIC] -main.go, line 19- This is a panic
goroutine 1 [running]:
github.com/goccmack/goutil/log.getPanicStackTrace(0x10bea8e, 0x3)
	.../github.com/goccmack/goutil/log/interface.go:138 +0x74
github.com/goccmack/goutil/log.Panic(0x10fac35, 0xf)
	.../github.com/goccmack/goutil/log/interface.go:96 +0x22
main.main()
	.../github.com/goccmack/goutil/log/examples/basic/main.go:19 +0x8d

Index

Constants

View Source 
const (
	// DefaultLogRootDir determines the directory for log files if not specified in log.config
	DefaultLogRootDir = "/usr/local/var/log"
	// DefaultNumFiles determines the maximum number of log files if not specified in log.config
	DefaultNumFiles = 3
	// DefaultLogFileNumBytes determines the maximum log file size if not specified in log.config
	DefaultLogFileNumBytes = 1000000
	// DefaultPriority determines the logger priority if not specified in log.config
	DefaultPriority = INFO
	// DefaultSuppressedFiles determines the suppressed files if not specified in log.config
	DefaultSuppressedFiles = ""
)

Default config

Variables

This section is empty.

Functions

func Close 

func Close()

Close is only necessary before os.Exit is called. Otherwise the logger will automatically close open files when the programe terminates. Calling log.Close() before the client program terminates will cause no harm.

func Debug 

func Debug(msg string)

Debug logs a message with priority Debug.

func Debugf 

func Debugf(format string, a ...interface{})

Debugf logs a formatted message with priority Debug.

func Exit 

func Exit(exitCode int, msg string)

Exit logs a message followed by os.Exit(exitCode)

func Exitf 

func Exitf(exitCode int, format string, a ...interface{})

Exitf logs a formatted message followed by os.Exit(exitCode)

func Info 

func Info(msg string)

Info logs a message with priority Info.

func Infof 

func Infof(format string, a ...interface{})

Infof logs a formatted message with priority Info.

func Panic 

func Panic(msg string)

Panic logs a message followed by a stack trace; flushes and closes the logIF file and then performs os.Exit(1)

func Panicf 

func Panicf(format string, a ...interface{})

Panicf logs a formatted message followed by a stack trace; flushes and closes the logIF file and then performs os.Exit(1)

func SetConfig 

func SetConfig(maxFiles, maxBytes int, priority Priority)

SetConfig sets the configuration of the logger to priority, to use up to maxFiles files and to close files that exceed maxBytes

func Suppress 

func Suppress(files string)

Suppress sets the list of files whose Debug messages are suppressed.Suppressed. If files is an empty string no files are suppressed. files is a comma separated list of file names. File names must not have a path. The ".go" extensions of the file names may be omitted. 

E.g.: "file1,file2"

func Warning 

func Warning(msg string)

Warning logs a message with priority Warning.

func Warningf 

func Warningf(format string, a ...interface{})

Warningf logs a formatted message with priority Warning.

Types

type Config 

type Config struct {
	RootDir      string
	FileName     string
	NumFiles     int
	FileNumBytes int
	Priority     Priority
	// comma separated list of files whose DEBUG messages are suppressed
	SuppressedFiles string
}

Config contains the logger configuration. It is read from the JSON file log.config in the working directory of from the default values if log.config does not exist.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns the default configuration

func GetConfig 

func GetConfig() *Config

GetConfig returns the current logger configuration

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone returns a deep copy of c

func (*Config) Equal 

func (c *Config) Equal(c1 *Config) bool

Equal returns true iff all fields of c are equal to c1

func (*Config) String 

func (c *Config) String() string

String returns a formatted string of c.

func (*Config) ToJSON 

func (c *Config) ToJSON() string

ToJSON returns the JSON format of log.config of c. The following can be used to generate the default JSON for log.config: 

fmt.Println(log.DefaultConfig().ToJSON())

{
    "RootDir": "/usr/local/var/log",
    "NumFiles": 3,
    "FileNumBytes": 1000000,
    "Priority": "INFO",
    "SuppressedFiles": ""
}

type Priority 

type Priority int

Priority of a logging message 

const (
	// Exit is used to terminate with a specified UNIX exit code
	EXIT Priority = iota

	// PANIC is for irrecoverable program failure.
	// The logger calls os.Exit(1) after the message is logged and the logIF closed.
	PANIC

	// WARNING is for recoverable errors
	WARNING

	// INFO provides high-level information about program execution
	INFO

	// DEBUG is used for exeution tracing
	DEBUG
)

func ToPriority 

func ToPriority(str string) (Priority, error)

ToPriority returns the Priority corresponding to str.

func (Priority) String 

func (p Priority) String() string

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
basic/pkga
exit command
set_config command
suppress_files command
Package files implements a managed fileset writer/closer.
 Package files implements a managed fileset writer/closer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.