logx

package module
v1.6.1 Latest Latest
Warning

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

Go to latest
Published: Sep 13, 2022 License: Apache-2.0 Imports: 7 Imported by: 12

README

LogX - Simple Golang Logging Library

LogX is an easy to use logging library for usage in any Golang application.

With LogX you can:

  • Log to Console!
  • Log to Files!
  • Log to multiple logs simultaneously!
  • Log to any io.Writer!

LogX supports all the options of the standard Golang log library with the addition of the Trace, Debug, Info, Warning and Error logging levels.

Example using LogX:

package main

import "github.com/PurpleSec/logx"

func main() {
    // New Console Log
    con := logx.Console(logx.Info)
    con.Error("Testing Error!")
    con.Info("Informational Numbers: %d %d %d...", 1, 2, 3)

    // New File Log
    fil, err := logx.File("log.log", logx.Debug)
    if err != nil {
        panic(err)
    }
    fil.Debug("Debugging in progress!")
    fil.Trace("You shouldn't see this :P")
    fil.Warning("Objects in mirror are closer than they appear!")

    // Multi Log Logging!
    multi := logx.Multiple(con, fil)

    // Disable Exiting on a Fatal call for testing.
    logx.FatalExits = false

    multi.Debug("This will only appear in the file log :D")
    multi.Info("Hello World!")
    multi.Fatal("OMG BAD STUFF")
    multi.Trace("This won't get logged, yay!")
}

Documentation

Overview

Package logx is an easy to use logging library for usage in any Golang application.

With LogX you can: - Log to Console! - Log to Files! - Log to multiple logs simultaneously! - Log to any io.Writer!

LogX supports all the options of the standard Golang log library with the addition of the Trace, Debug, Info, Warning and Error logging levels.

Example using LogX:

package main

import "github.com/PurpleSec/logx"

func main() {
    New Console Log
    con := logx.Console(logx.Info)
    con.Error("Testing Error!")
    con.Info("Informational Numbers: %d %d %d...", 1, 2, 3)

    New File Log
    fil, err := logx.File("log.log", logx.Debug)
    if err != nil {
         panic(err)
     }
   fil.Debug("Debugging in progress!")
   fil.Trace("You shouldn't see this :P")
   fil.Warning("Objects in mirror are closer than they appear!")

   Multi Log Logging!
   multi := logx.Multiple(con, fil)

   Disable Exiting on a Fatal call for testing.
   logx.FatalExits = false

   multi.Debug("This will only appear in the file log :D")
   multi.Info("Hello World!")
   multi.Fatal("OMG BAD STUFF")
   multi.Trace("This won't get logged, yay!")
}

Index

Constants

View Source
const (
	// FlagDate instructs the Logger to include the local date in the logging output.
	//
	// Same as 'log.Ldate' or 'Ldate'.
	FlagDate uint8 = 1 << iota
	// FlagTime instructs the Logger to include the local time in the logging output.
	//
	// Same as 'log.Ltime' or 'Ltime'.
	FlagTime
	// FlagMicroseconds instructs the Logger to include the local time (in milliseconds)
	// in the logging output. Implies 'FlagTime'.
	//
	// Same as 'log.Lmicroseconds' or 'Lmicroseconds'.
	FlagMicroseconds
	// FlagFileLong instructs the Logger to include the full source file name and
	// line number in the logging output.
	//
	// Same as 'log.Llongfile' or 'Llongfile'.
	FlagFileLong
	// FlagFileShort instructs the Logger to include the shortened source file
	// name (file name only) and line number in the logging output. Overrides
	// 'FlagFileLong'.
	//
	// Same as 'log.Lshortfile' or 'Lshortfile'.
	FlagFileShort
	// FlagTimeUTC instructs the Logger to use the UTC time zone as the log output
	// date/time instead of the local time zone. Only takes affect if 'FlagDate',
	// 'FlagTime' or 'FlagMicroseconds' is implied.
	//
	// Same as 'log.LUTC' or 'LUTC'.
	FlagTimeUTC

	// FlagStandard is the standard logging flags used as the setting for the default
	// logger. This is the same as 'FlagDate | FlagTime'.
	//
	// Same as 'log.LstdFlags' or 'LstdFlags'.
	FlagStandard = FlagDate | FlagTime
)
View Source
const (
	Ldate               = FlagDate
	Ltime               = FlagTime
	Lmicroseconds       = FlagMicroseconds
	Llongfile           = FlagFileLong
	Lshortfile          = FlagFileShort
	LUTC                = FlagTimeUTC
	Lmsgprefix    uint8 = 0
	LstdFlags           = FlagStandard
)

Flag values that mirror the ones in the 'log' package.

NOTE: 'Lmsgprefix' has no effect.

View Source
const Append = settingAppend(true)

Append is a logging setting that instructs the Log to override the default log file truncation behavior. When this is used in the options for creating a file backed log instance, the new logged data will be appended to any previous data that the file contains.

This setting has no effect on non-file backed logging instances.

Variables

View Source
var DefaultConsole io.Writer = os.Stderr

DefaultConsole is a pointer to the output that all the console Log structs will use when created.

This can be set to any io.Writer. The default is the Stderr console.

View Source
var DefaultFlags = FlagStandard

DefaultFlags is the default bitwise flag value that is used for new logging instances that are not given a flag options setting when created.

This flag number may be changed before running to affect creation of new logging instances.

View Source
var FatalExits = true

FatalExits is a boolean setting that determines if a call to Fatal or LogFatal will exit the program using 'os.Exit(1)'. If this is set to false, a call to Fatal or LogFatal will continue program execution after being called.

The default value is true.

View Source
var Global = Console()

Global is the default Global logging instance. This can be used instead of passing around a logging handle.

All standard 'Log*' functions or functions with a nil struct will go to this logging instance.

View Source
var NOP = nop{}

NOP is a Logger that can consume all types of logs but does not do anything (a NOP).

This can be used similar to context.TODO or if logging is not needed and nil log instances are not available or allowed.

Functions

func LogDebug

func LogDebug(m string, v ...interface{})

LogDebug writes a debugging message to the Global logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogError

func LogError(m string, v ...interface{})

LogError writes an error message to the Global logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogFatal

func LogFatal(m string, v ...interface{})

LogFatal writes a fatal message to the Global logger.

This function will result in the program exiting with a non-zero error code after being called, unless the 'logx.FatalExits' setting is 'false'. The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogInfo

func LogInfo(m string, v ...interface{})

LogInfo writes an informational message to the Global logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogPanic

func LogPanic(m string, v ...interface{})

LogPanic writes a panic message to the Global logger.

This function will result in the program exiting with a Go 'panic()' after being called. The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogPrint

func LogPrint(m string, v ...interface{})

LogPrint writes a message to the Global logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is affected by the setting of 'Global.SetPrintLevel'. By default, this will print as an 'Info' logging message.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogTrace

func LogTrace(m string, v ...interface{})

LogTrace writes a tracing message to the Global logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

func LogWarning

func LogWarning(m string, v ...interface{})

LogWarning writes a warning message to the Global logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is used only as a handy quick usage solution. It is recommended to use a direct function call on a logger or the Global logger instead.

Types

type Level

type Level uint8

Level is an alias of a byte that represents the current Log level.

const (
	// Trace is the Tracing log level, everything logged is passed to the Log
	// (it might get noisy).
	Trace Level = iota
	// Debug prints slightly less information than Trace, but is primarily useful
	// for debugging messages.
	Debug
	// Info is the standard informational log Level, this can be used to print
	// out handy information messages.
	Info
	// Warning is exactly how it sounds, any event that occurs of notice, but
	// is not major. This is the default logging
	// level.
	Warning
	// Error is similar to the Warning level, except more serious.
	Error
	// Fatal means the program cannot continue when this event occurs. Normally
	// the program will exit after this.
	//
	// Set 'logx.FatalExits' to 'false' to disable exiting when a Fatal log entry
	// is triggered.
	Fatal
	// Panic is a special level only used by the 'Panic*' functions. This will
	// act similar to the 'Fatal' level but will trigger a Go 'panic()' call
	// instead once log writing is complete.
	//
	// The 'logx.FatalExits' variable does not apply to this level.
	Panic
	// Print is a special level only used for LogWriters. This level instructs
	// the LogWriter to use it's inbuilt print level for the specified message.
	//
	// Attempting to use this out of this context will fail.
	Print
)

func Normal

func Normal(req int, normal Level) Level

Normal will attempt to normalize the requested log level. This will check the supplied integer and will return it as a valid log level if in bounds of the supported log levels. If not, the specified normal log level will be returned instead.

func NormalUint

func NormalUint(req uint, normal Level) Level

NormalUint will attempt to normalize the requested log level. This will check the supplied integer and will return it as a valid log level if in bounds of the supported log levels. If not, the specified normal log level will be returned instead. This function is made to specifically work on unsigned integers instead.

func (Level) String

func (l Level) String() string

String returns the textual name of the Level.

type Log

type Log interface {
	// SetLevel changes the current logging level of this Log.
	SetLevel(Level)
	// SetPrefix changes the current logging prefix of this Log.
	SetPrefix(string)
	// SetPrintLevel sets the logging level used when 'Print*' statements are called.
	SetPrintLevel(Level)
	// Print writes a message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprint' and 'fmt.Print'. The only
	// argument is a vardict of interfaces that can be used to output a string value.
	//
	// This function is affected by the setting of 'SetPrintLevel'. By default,
	// this will print as an 'Info' logging message.
	Print(...interface{})
	// Panic writes a panic message to the logger.
	//
	// This function will result in the program exiting with a Go 'panic()' after
	// being called. The function arguments are similar to 'fmt.Sprint' and 'fmt.Print.'
	// The only argument is a vardict of interfaces that can be used to output a
	// string value.
	Panic(...interface{})
	// Println writes a message to the logger.
	//
	// The function arguments are similar to fmt.Sprintln and fmt.Println. The only
	// argument is a vardict of interfaces that can be used to output a string value.
	//
	// This function is affected by the setting of 'SetPrintLevel'. By default,
	// this will print as an 'Info' logging message.
	Println(...interface{})
	// Panicln writes a panic message to the logger.
	//
	// This function will result in the program exiting with a Go 'panic()' after
	// being called. The function arguments are similar to 'fmt.Sprintln' and
	// 'fmt.Println'. The only argument is a vardict of interfaces that
	// can be used to output a string value.
	Panicln(...interface{})
	// Info writes an informational message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The
	// first argument is a string that can contain formatting characters. The second
	// argument is a vardict of interfaces that can be omitted or used in the supplied
	// format string.
	Info(string, ...interface{})
	// Error writes an error message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The
	// first argument is a string that can contain formatting characters. The second
	// argument is a vardict of interfaces that can be omitted or used in the supplied
	// format string.
	Error(string, ...interface{})
	// Fatal writes a fatal message to the logger.
	//
	// This function will result in the program exiting with a non-zero error code
	// after being called, unless the 'logx.FatalExits' setting is 'false'. The
	// function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first
	// argument is a string that can contain formatting characters. The second argument
	// is a vardict of interfaces that can be omitted or used in the supplied format
	// string.
	Fatal(string, ...interface{})
	// Trace writes a tracing message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The
	// first argument is a string that can contain formatting characters. The second
	// argument is a vardict of interfaces that can be omitted or used in the supplied
	// format string.
	Trace(string, ...interface{})
	// Debug writes a debugging message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The
	// first argument is a string that can contain formatting characters. The second
	// argument is a vardict of interfaces that can be omitted or used in the supplied
	// format string.
	Debug(string, ...interface{})
	// Printf writes a message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The
	// first argument is a string that can contain formatting characters. The second
	// argument is a vardict of interfaces that can be omitted or used in the supplied
	// format string.
	//
	// This function is affected by the setting of 'SetPrintLevel'. By default,
	// this will print as an 'Info' logging message.
	Printf(string, ...interface{})
	// Panicf writes a panic message to the logger.
	//
	// This function will result in the program exiting with a Go 'panic()' after
	// being called. The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'.
	// The first argument is a string that can contain formatting characters. The
	// second argument is a vardict of interfaces that can be omitted or used in
	// the supplied format string.
	Panicf(string, ...interface{})
	// Warning writes a warning message to the logger.
	//
	// The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The
	// first argument is a string that can contain formatting characters. The second
	// argument is a vardict of interfaces that can be omitted or used in the supplied
	// format string.
	Warning(string, ...interface{})
}

Log is an interface for any type of struct that supports standard Logging functions.

func Console

func Console(o ...Option) Log

Console returns a console logger that uses the Console writer.

func File

func File(s string, o ...Option) (Log, error)

File will attempt to create a File backed Log instance that will write to file specified.

This function will truncate the file before starting a new Log if the 'Append' option isn't specified.

func Writer

func Writer(w io.Writer, o ...Option) Log

Writer returns a Log instance based on the Writer 'w' for the logging output and allows specifying non-default Logging options.

type LogWriter

type LogWriter interface {
	Log(Level, int, string, ...interface{})
}

LogWriter is an interface that is used inline with logging operations. This interface defines a single function 'Log' which takes a Level to log, the additional stack depth (can be zero), and the message and optional arguments to be logged.

This function is used as a "quick-logging" helper and is preferred by the Multi logging struct.

This funcion must ONLY log and not preform any other operations such as exiting on a Fatal or Panic logging level.

Use the higher level 'Fatal' and 'Panic' functions for those additional operations.

The higher level calls may use this function to simplify logging and comply with the logx Multi-logger.

type Multi

type Multi []Log

Multi is a type of Log that is an alias for an array where each Log function will affect each Log instance in the array.

func Multiple

func Multiple(l ...Log) *Multi

Multiple returns a Stack struct that contains the Log instances specified in the 'l' vardict.

func (*Multi) Add

func (m *Multi) Add(l Log)

Add appends the specified Log 'l' the Stack array.

func (Multi) Debug

func (m Multi) Debug(s string, v ...interface{})

Debug writes a debugging message to the logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

func (Multi) Error

func (m Multi) Error(s string, v ...interface{})

Error writes an error message to the logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

func (Multi) Fatal

func (m Multi) Fatal(s string, v ...interface{})

Fatal writes a fatal message to the logger.

This function will result in the program exiting with a non-zero error code after being called, unless the 'logx.FatalExits' setting is 'false'. The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

func (Multi) Info

func (m Multi) Info(s string, v ...interface{})

Info writes n informational message to the logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

func (Multi) Panic

func (m Multi) Panic(v ...interface{})

Panic writes a panic message to the logger.

This function will result in the program exiting with a Go 'panic()' after being called. The function arguments are similar to 'fmt.Sprint' and 'fmt.Print.' The only argument is a vardict of interfaces that can be used to output a string value.

func (Multi) Panicf

func (m Multi) Panicf(s string, v ...interface{})

Panicf writes a panic message to the logger.

This function will result in the program exiting with a Go 'panic()' after being called. The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

func (Multi) Panicln

func (m Multi) Panicln(v ...interface{})

Panicln writes a panic message to the logger.

This function will result in the program exiting with a Go 'panic()' after being called. The function arguments are similar to 'fmt.Sprintln' and 'fmt.Println'. The only argument is a vardict of interfaces that can be used to output a string value.

func (Multi) Print

func (m Multi) Print(v ...interface{})

Print writes a message to the logger.

The function arguments are similar to 'fmt.Sprint' and 'fmt.Print'. The only argument is a vardict of interfaces that can be used to output a string value.

This function is affected by the setting of 'SetPrintLevel'. By default, this will print as an 'Info' logging message.

func (Multi) Printf

func (m Multi) Printf(s string, v ...interface{})

Printf writes a message to the logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

This function is affected by the setting of 'SetPrintLevel'. By default, this will print as an 'Info' logging message.

func (Multi) Println

func (m Multi) Println(v ...interface{})

Println writes a message to the logger.

The function arguments are similar to fmt.Sprintln and fmt.Println. The only argument is a vardict of interfaces that can be used to output a string value.

This function is affected by the setting of 'SetPrintLevel'. By default, this will print as an 'Info' logging message.

func (Multi) SetLevel

func (m Multi) SetLevel(l Level)

SetLevel changes the current logging level of this Log instance.

func (Multi) SetPrefix

func (m Multi) SetPrefix(p string)

SetPrefix changes the current logging prefox of this Log instance.

func (Multi) SetPrintLevel

func (m Multi) SetPrintLevel(n Level)

SetPrintLevel sets the logging level used when 'Print*' statements are called.

func (Multi) Trace

func (m Multi) Trace(s string, v ...interface{})

Trace writes a tracing message to the logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

func (Multi) Warning

func (m Multi) Warning(s string, v ...interface{})

Warning writes a warning message to the logger.

The function arguments are similar to 'fmt.Sprintf' and 'fmt.Printf'. The first argument is a string that can contain formatting characters. The second argument is a vardict of interfaces that can be omitted or used in the supplied format string.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is an interface that allows for passing a vardict of potential settings that can be used during creation of a logging instance.

This interface type will only be fulfilled by internal functions.

func Flags

func Flags(f int) Option

Flags will create an Option interface that will set the provided flag value on the underlying log instance when created.

Valid values for this can be referenced from the 'log' package.

func Prefix

func Prefix(p string) Option

Prefix will create an Option interface that will set the provided prefix on the logging instance when created.

func PrintLevel

func PrintLevel(l Level) Option

PrintLevel will return an Option interface that will set the level used by the 'Print*' functions.

This is similar to calling the 'SetPrintLevel' function.

Jump to

Keyboard shortcuts

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