log

package module
v0.0.0-...-881f455 Latest Latest
Warning

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

Go to latest
Published: Sep 30, 2020 License: Apache-2.0 Imports: 14 Imported by: 16

README

SPDX-License-Identifier: Apache-2.0
Copyright (c) 2019 Intel Corporation

Log

Common logging library with Syslog support

Getting Started

In its most basic form, the log package from open-ness/common repository can be used by calling package level print funcs, i.e. Debug(f|ln), Info(f|ln), Err(f|ln), etc.

By default, all logs will be printed to stderr and a remote syslog service, if connected. To change the default print output destination, use SetOutput. For example, to turn off printing of all logs, regardless of severity level, use SetOutput(ioutil.Discard).

The default severity level is INFO and the default syslog facility is LOCAL0. To change these SetLevel and SetFacility can be used, respectively, to alter the default logger. Regardless of the severity level set, all logs will be sent to any connected remote syslog service. Severity only affects what is written to output.

To connect the default logger to a remote syslog service, use ConnectSyslog, providing the address of the UDP server or an empty string to connect to the local machine's service via domain socket. To disconnect, use the corresponding DisconnectSyslog func.

Structured Logging / Tags

Minimal support for structured tagging exists via (*Logger).WithField(s). Key-value pairs can be set before printing in order to automatically prepend data to each log. The data is in the message portion, not the tag, of the syslog message, so this is essentially just default formatting.

As an example, one may wish to create a logger for a software package within a larger monolith that tags itself. This may look like

package api

import "github.com/open-ness/common/log"

var log = log.DefaultLogger.WithField("component", "api")

func Hello(name string) {
	log.Infof("Hello %s!", name)
	// Output: "[component=api] Hello <name>!"
}

As an edge case, if the value is nil, then the prepended data will look like [key] rather than [key=<nil>]. This may be useful if a key such as "component" is implied.

Advanced Usage

Each Logger instance can have one non-syslog writer - for which print levels can be set - and one remote syslog connection. Package level functions use a default Logger instance. For cases where the default logger is not sufficient more can be created with new(Logger).

For dynamic print level changes via OS signals, see SignalVerbosityChanges.

Testing

go test -v -race

Documentation

Index

Constants

View Source
const (
	// DefaultLevel is the initial logging verbosity
	DefaultLevel = syslog.LOG_INFO
	// DefaultFacility is the default facility portion of the syslog priority.
	DefaultFacility = syslog.LOG_LOCAL0
)

Variables

View Source
var (
	// DefaultLogger is the package-level logger that is used for all package
	// funcs.
	DefaultLogger = &Logger{}
)

Functions

func Alert

func Alert(a ...interface{})

Alert writes ALERT message to output and syslog if connected.

func Alertf

func Alertf(frmt string, a ...interface{})

Alertf writes formatted ALERT message to output and syslog if connected.

func Alertln

func Alertln(a ...interface{})

Alertln writes ALERT message to output and syslog if connected.

func ConnectSyslog

func ConnectSyslog(addr string) error

ConnectSyslog connects to a remote syslog. If addr is an empty string, it will connect to the local syslog service.

func Crit

func Crit(a ...interface{})

Crit writes CRITICAL message to output and syslog if connected.

func Critf

func Critf(frmt string, a ...interface{})

Critf writes formatted CRITICAL message to output and syslog if connected.

func Critln

func Critln(a ...interface{})

Critln writes CRITICAL message to output and syslog if connected.

func Debug

func Debug(a ...interface{})

Debug writes DEBUG message to output and syslog if connected.

func Debugf

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

Debugf writes formatted DEBUG message to output and syslog if connected.

func Debugln

func Debugln(a ...interface{})

Debugln writes DEBUG message to output and syslog if connected.

func DisconnectSyslog

func DisconnectSyslog() error

DisconnectSyslog closes the connection to syslog.

func Emerg

func Emerg(a ...interface{})

Emerg writes EMERGENCY message to output and syslog if connected.

func Emergf

func Emergf(frmt string, a ...interface{})

Emergf writes formatted EMERGENCY message to output and syslog if connected.

func Emergln

func Emergln(a ...interface{})

Emergln writes EMERGENCY message to output and syslog if connected.

func Err

func Err(a ...interface{})

Err writes ERROR message to output and syslog if connected.

func Errf

func Errf(frmt string, a ...interface{})

Errf writes formatted ERROR message to output and syslog if connected.

func Errln

func Errln(a ...interface{})

Errln writes ERROR message to output and syslog if connected.

func GetFacility

func GetFacility() syslog.Priority

GetFacility returns the facility portion of the current syslog priority.

func GetLevel

func GetLevel() syslog.Priority

GetLevel returns the verbosity level that log will print at and below. It can be compared to syslog.LOG_EMERG...syslog.LOG_DEBUG.

func Info

func Info(a ...interface{})

Info writes INFO message to output and syslog if connected.

func Infof

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

Infof writes formatted INFO message to output and syslog if connected.

func Infoln

func Infoln(a ...interface{})

Infoln writes INFO message to output and syslog if connected.

func Notice

func Notice(a ...interface{})

Notice writes NOTICE message to output and syslog if connected.

func Noticef

func Noticef(frmt string, a ...interface{})

Noticef writes formatted NOTICE message to output and syslog if connected.

func Noticeln

func Noticeln(a ...interface{})

Noticeln writes NOTICE message to output and syslog if connected.

func ParseLevel

func ParseLevel(prio string) (syslog.Priority, error)

ParseLevel parses provided syslog severity name into its integer(syslog.Priority) representation. Supported input values: emerg, emergency, alert, crit, critical, err, error, warn, warning, notice, info, information, debug. Input is parsed without case sensitivity.

func Print

func Print(p syslog.Priority, a ...interface{})

Print writes message with severity and set facility to output and syslog if connected.

func Printf

func Printf(p syslog.Priority, frmt string, a ...interface{})

Printf writes message with severity and set facility to output and syslog if connected.

func Println

func Println(p syslog.Priority, a ...interface{})

Println writes message with severity and set facility to output and syslog if connected.

func SetFacility

func SetFacility(p syslog.Priority)

SetFacility alters the syslog facility used for logs. If the priority includes a verbosity level it will be ignored.

func SetLevel

func SetLevel(p syslog.Priority)

SetLevel alters the verbosity level that log will print at and below. It takes values syslog.LOG_EMERG...syslog.LOG_DEBUG. If the priority includes a facility it will be ignored.

func SetOutput

func SetOutput(w io.Writer)

SetOutput changes the writer of local logs written by each logging func in addition to any remote syslog connection. If w is nil then os.Stderr will be used. If no non-remote logging is desired, set output to ioutil.Discard.

func SignalVerbosityChanges

func SignalVerbosityChanges(ctx context.Context, l *Logger)

SignalVerbosityChanges captures SIGUSR1 and SIGUSR2 and decreases and increases verbosity on each signal, respectively.

This function spawns a goroutine in order to make it safe to send a USR1 or USR2 signal as soon as the function has returned.

func Warning

func Warning(a ...interface{})

Warning writes WARNING message to output and syslog if connected.

func Warningf

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

Warningf writes formatted WARNING message to output and syslog if connected.

func Warningln

func Warningln(a ...interface{})

Warningln writes WARNING message to output and syslog if connected.

Types

type GrpcLogger

type GrpcLogger struct {
	// Logger is the underlying Logger to write to. If none is specified, then
	// the default logger (package var) is used.
	Logger *Logger

	// PrintLevel specifies the level that all print messages will be written
	// at. If none is specified, the default of INFO will be used.
	PrintLevel syslog.Priority
	// contains filtered or unexported fields
}

GrpcLogger implements grpclog's Logger and LoggerV2 interfaces.

func (*GrpcLogger) Error

func (l *GrpcLogger) Error(args ...interface{})

Error initializes and logs to error logger. All arguments are forwarded.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Errorf

func (l *GrpcLogger) Errorf(format string, args ...interface{})

Errorf logs to error logger. All arguments are forwarded.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Errorln

func (l *GrpcLogger) Errorln(args ...interface{})

Errorln logs to error logger. Arguments are handled in the manner of fmt.Println.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Fatal

func (l *GrpcLogger) Fatal(args ...interface{})

Fatal initializes, logs to alert logger and calls os.exit with value 1. All arguments are forwarded to logger.

This function partially implements the grpclog.Logger and grpclog.LoggerV2 interfaces.

func (*GrpcLogger) Fatalf

func (l *GrpcLogger) Fatalf(format string, args ...interface{})

Fatalf initializes, logs to alertf logger and calls os.exit with value 1. All arguments are forwarded to logger.

This function partially implements the grpclog.Logger and grpclog.LoggerV2 interfaces.

func (*GrpcLogger) Fatalln

func (l *GrpcLogger) Fatalln(args ...interface{})

Fatalln executes Fatal func and forwards all arguments.

This function partially implements the grpclog.Logger and grpclog.LoggerV2 interfaces.

func (*GrpcLogger) Info

func (l *GrpcLogger) Info(args ...interface{})

Info initializes and logs to info logger. All arguments are forwarded.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Infof

func (l *GrpcLogger) Infof(format string, args ...interface{})

Info initializes and logs to infof logger. All arguments are forwarded.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Infoln

func (l *GrpcLogger) Infoln(args ...interface{})

Infoln logs to info logger. All arguments are forwarded to Info func

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Print

func (l *GrpcLogger) Print(args ...interface{})

Print logs to the level set at init. Arguments are handled in the manner of fmt.Print.

This function partially implements the grpclog.Logger interface.

func (*GrpcLogger) Printf

func (l *GrpcLogger) Printf(format string, args ...interface{})

Printf logs to the level set at init. Arguments are handled in the manner of fmt.Printf.

This function partially implements the grpclog.Logger interface.

func (*GrpcLogger) Println

func (l *GrpcLogger) Println(args ...interface{})

Println logs to the level set at init. Arguments are handled in the manner of fmt.Println.

This function partially implements the grpclog.Logger interface.

func (*GrpcLogger) V

func (l *GrpcLogger) V(level int) bool

V reports whether verbosity level l is at least the requested verbose level.

Levels are _not_ identical to Syslog and are defined by the grpclog library as:

0: FATAL and ERROR
1: FATAL and ERROR and WARNING
2: FATAL and ERROR and WARNING and INFO

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Warning

func (l *GrpcLogger) Warning(args ...interface{})

Warning initializes and logs to warning logger. All arguments are forwarded.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Warningf

func (l *GrpcLogger) Warningf(format string, args ...interface{})

Warningf initializes and logs to warning logger. All arguments are forwarded.

This function partially implements the grpclog.LoggerV2 interface.

func (*GrpcLogger) Warningln

func (l *GrpcLogger) Warningln(args ...interface{})

Warningln logs to warning logger. Arguments are forwarded to Warning func

This function partially implements the grpclog.LoggerV2 interface.

type Logger

type Logger struct {
	// Printer embeds all printing funcs. It should not be set manually.
	Printer
	// contains filtered or unexported fields
}

Logger implements syslog logging funcs and can be connected to a syslog server.

func (*Logger) ConnectSyslog

func (l *Logger) ConnectSyslog(addr string) error

ConnectSyslog connects to a remote syslog. If addr is an empty string, it will connect to the local syslog service.

func (*Logger) ConnectSyslogTLS

func (l *Logger) ConnectSyslogTLS(addr string, conf *tls.Config) error

ConnectSyslogTLS connects to a remote syslog, performing a TLS client handshake. This is always done over TCP and the addr cannot be empty (in an attempt to connect to the local syslog service).

func (*Logger) DisconnectSyslog

func (l *Logger) DisconnectSyslog() error

DisconnectSyslog closes the connection to syslog.

func (*Logger) GetFacility

func (l *Logger) GetFacility() syslog.Priority

GetFacility returns the facility portion of the current syslog priority.

func (*Logger) GetLevel

func (l *Logger) GetLevel() syslog.Priority

GetLevel returns the verbosity level that log will print at and below. It can be compared to syslog.LOG_EMERG...syslog.LOG_DEBUG.

func (*Logger) SetFacility

func (l *Logger) SetFacility(p syslog.Priority)

SetFacility alters the syslog facility used for logs. If the priority includes a verbosity level it will be ignored.

func (*Logger) SetLevel

func (l *Logger) SetLevel(p syslog.Priority)

SetLevel alters the verbosity level that log will print at and below. It takes values syslog.LOG_EMERG...syslog.LOG_DEBUG. If the priority includes a facility it will be ignored.

func (*Logger) SetOutput

func (l *Logger) SetOutput(w io.Writer)

SetOutput changes the writer of local logs written by each logging func in addition to any remote syslog connection. If w is nil then os.Stderr will be used. If no non-remote logging is desired, set output to ioutil.Discard.

func (*Logger) WithField

func (l *Logger) WithField(key string, value interface{}) Printer

WithField returns a Printer tagged with a single field.

func (*Logger) WithFields

func (l *Logger) WithFields(kvs map[string]interface{}) Printer

WithFields returns a Printer tagged with multiple fields.

type Printer

type Printer struct {
	Format      func(frmt string, a ...interface{}) string
	Write       func(lvl syslog.Priority, msg string)
	WriteSyslog func(lvl syslog.Priority, msg string)
}

Printer formats and writes logs conditionally based on the current priority level.

func (Printer) Alert

func (p Printer) Alert(a ...interface{})

Alert writes ALERT message to output and syslog if connected.

func (Printer) Alertf

func (p Printer) Alertf(frmt string, a ...interface{})

Alertf writes formatted ALERT message to output and syslog if connected.

func (Printer) Alertln

func (p Printer) Alertln(a ...interface{})

Alertln writes ALERT message to output and syslog if connected.

func (Printer) Crit

func (p Printer) Crit(a ...interface{})

Crit writes CRITICAL message to output and syslog if connected.

func (Printer) Critf

func (p Printer) Critf(frmt string, a ...interface{})

Critf writes formatted CRITICAL message to output and syslog if connected.

func (Printer) Critln

func (p Printer) Critln(a ...interface{})

Critln writes CRITICAL message to output and syslog if connected.

func (Printer) Debug

func (p Printer) Debug(a ...interface{})

Debug writes DEBUG message to output and syslog if connected.

func (Printer) Debugf

func (p Printer) Debugf(frmt string, a ...interface{})

Debugf writes formatted DEBUG message to output and syslog if connected.

func (Printer) Debugln

func (p Printer) Debugln(a ...interface{})

Debugln writes DEBUG message to output and syslog if connected.

func (Printer) Emerg

func (p Printer) Emerg(a ...interface{})

Emerg writes EMERGENCY message to output and syslog if connected.

func (Printer) Emergf

func (p Printer) Emergf(frmt string, a ...interface{})

Emergf writes formatted EMERGENCY message to output and syslog if connected.

func (Printer) Emergln

func (p Printer) Emergln(a ...interface{})

Emergln writes EMERGENCY message to output and syslog if connected.

func (Printer) Err

func (p Printer) Err(a ...interface{})

Err writes ERROR message to output and syslog if connected.

func (Printer) Errf

func (p Printer) Errf(frmt string, a ...interface{})

Errf writes formatted ERROR message to output and syslog if connected.

func (Printer) Errln

func (p Printer) Errln(a ...interface{})

Errln writes ERROR message to output and syslog if connected.

func (Printer) Info

func (p Printer) Info(a ...interface{})

Info writes INFO message to output and syslog if connected.

func (Printer) Infof

func (p Printer) Infof(frmt string, a ...interface{})

Infof writes formatted INFO message to output and syslog if connected.

func (Printer) Infoln

func (p Printer) Infoln(a ...interface{})

Infoln writes INFO message to output and syslog if connected.

func (Printer) Notice

func (p Printer) Notice(a ...interface{})

Notice writes NOTICE message to output and syslog if connected.

func (Printer) Noticef

func (p Printer) Noticef(frmt string, a ...interface{})

Noticef writes formatted NOTICE message to output and syslog if connected.

func (Printer) Noticeln

func (p Printer) Noticeln(a ...interface{})

Noticeln writes NOTICE message to output and syslog if connected.

func (Printer) Print

func (p Printer) Print(lvl syslog.Priority, a ...interface{})

Print writes message with severity and set facility to output and syslog if connected.

func (Printer) Printf

func (p Printer) Printf(lvl syslog.Priority, frmt string, a ...interface{})

Printf writes message with severity and set facility to output and syslog if connected.

func (Printer) Println

func (p Printer) Println(lvl syslog.Priority, a ...interface{})

Println writes message with severity and set facility to output and syslog if connected.

func (Printer) Warning

func (p Printer) Warning(a ...interface{})

Warning writes WARNING message to output and syslog if connected.

func (Printer) Warningf

func (p Printer) Warningf(frmt string, a ...interface{})

Warningf writes formatted WARNING message to output and syslog if connected.

func (Printer) Warningln

func (p Printer) Warningln(a ...interface{})

Warningln writes WARNING message to output and syslog if connected.

Directories

Path Synopsis
Package syslog provides a simple interface to the system log service.
Package syslog provides a simple interface to the system log service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL