xlog: git.devever.net/hlandau/xlog Index | Files

package xlog

import "git.devever.net/hlandau/xlog"

Package xlog provides a hierarchical, configurable logging system suitable for use in libraries.

Index

Package Files

logger.go multisink.go severity.go syslogsink.go terminal.go writersink.go xlog.go

func VisitSites Uses

func VisitSites(siteFunc func(s Site) error) error

Calls a function for every Site which has been created.

Do not attempt to create new loggers from the callback.

type LogClosure Uses

type LogClosure func() string

LogClosure can be used to pass a function that returns a string to a log method call. This is useful if the computation of a log message is expensive and the message will often be filtered.

func (LogClosure) String Uses

func (c LogClosure) String() string

type Logger Uses

type Logger struct {
    Sink
}

Logger is the interface exposed to the internals of a package, which uses it to log messages. This is the other side of a Site.

The 'f' functions work like Printf. The suffix-free functions work like 'Print'. The 'e' functions are no-ops if nil is passed for the error; otherwise, they print the error as well as the arguments specified.

Fatal calls os.Exit(1) like "log", and Panic panics. Both emit Critical-severity log messages before doing so.

func New Uses

func New(name string) (Logger, Site)

Creates a new logger.

While there are no particular restrictions on facility names, the preferred convention for the facility name is a dot-separated hierarchy of words matching [a-zA-Z0-9_-]+. Hyphens are preferred over underscores, and uppercase should be avoided in most cases.

The facility name should reflect the package and, if the package's status as a subpackage is of particular significance or grouping is desirable, a parent package.

For example, if you have a package foo which has 10 subpackages which implement different parts of foo, you might give them facility names like "foo.alpha", "foo.beta", "foo.gamma", etc.

Typical usage:

var log, Log = xlog.New("facility name")

func NewQuiet Uses

func NewQuiet(name string) (Logger, Site)

Like New, but the created logger by default doesn't output anything but the most severe errors. Intended for use by libraries so that consuming code needs to opt in to log output by that library.

func NewUnder Uses

func NewUnder(name string, site Site) (Logger, Site)

Creates a logger which is subordinate to another logger.

All log messages will be forwarded through the parent logger, meaning that any filtration or forwarding settings set on the parent logger will also apply to this one.

The name of the logger is formed by appending the name given to the name of the parent logger and ".". If site is nil, behaves like New().

func (Logger) Alert Uses

func (l Logger) Alert(params ...interface{})

func (Logger) Alerte Uses

func (l Logger) Alerte(err error, params ...interface{})

func (Logger) Alertef Uses

func (l Logger) Alertef(err error, format string, params ...interface{})

func (Logger) Alertf Uses

func (l Logger) Alertf(format string, params ...interface{})

func (Logger) Critical Uses

func (l Logger) Critical(params ...interface{})

func (Logger) Criticale Uses

func (l Logger) Criticale(err error, params ...interface{})

func (Logger) Criticalef Uses

func (l Logger) Criticalef(err error, format string, params ...interface{})

func (Logger) Criticalf Uses

func (l Logger) Criticalf(format string, params ...interface{})

func (Logger) Debug Uses

func (l Logger) Debug(params ...interface{})

func (Logger) Debuge Uses

func (l Logger) Debuge(err error, params ...interface{})

func (Logger) Debugef Uses

func (l Logger) Debugef(err error, format string, params ...interface{})

func (Logger) Debugf Uses

func (l Logger) Debugf(format string, params ...interface{})

func (Logger) Emergency Uses

func (l Logger) Emergency(params ...interface{})

func (Logger) Emergencye Uses

func (l Logger) Emergencye(err error, params ...interface{})

func (Logger) Emergencyef Uses

func (l Logger) Emergencyef(err error, format string, params ...interface{})

func (Logger) Emergencyf Uses

func (l Logger) Emergencyf(format string, params ...interface{})

func (Logger) Error Uses

func (l Logger) Error(params ...interface{})

func (Logger) Errore Uses

func (l Logger) Errore(err error, params ...interface{})

func (Logger) Erroref Uses

func (l Logger) Erroref(err error, format string, params ...interface{})

func (Logger) Errorf Uses

func (l Logger) Errorf(format string, params ...interface{})

func (Logger) Fatal Uses

func (l Logger) Fatal(params ...interface{})

func (Logger) Fatale Uses

func (l Logger) Fatale(err error, params ...interface{})

func (Logger) Fatalef Uses

func (l Logger) Fatalef(err error, format string, params ...interface{})

func (Logger) Fatalf Uses

func (l Logger) Fatalf(format string, params ...interface{})

func (Logger) Info Uses

func (l Logger) Info(params ...interface{})

func (Logger) Infoe Uses

func (l Logger) Infoe(err error, params ...interface{})

func (Logger) Infoef Uses

func (l Logger) Infoef(err error, format string, params ...interface{})

func (Logger) Infof Uses

func (l Logger) Infof(format string, params ...interface{})

func (Logger) Notice Uses

func (l Logger) Notice(params ...interface{})

func (Logger) Noticee Uses

func (l Logger) Noticee(err error, params ...interface{})

func (Logger) Noticeef Uses

func (l Logger) Noticeef(err error, format string, params ...interface{})

func (Logger) Noticef Uses

func (l Logger) Noticef(format string, params ...interface{})

func (Logger) Panic Uses

func (l Logger) Panic(params ...interface{})

func (Logger) Panice Uses

func (l Logger) Panice(err error, params ...interface{})

func (Logger) Panicef Uses

func (l Logger) Panicef(err error, format string, params ...interface{})

func (Logger) Panicf Uses

func (l Logger) Panicf(format string, params ...interface{})

func (Logger) ReceiveLocallye Uses

func (l Logger) ReceiveLocallye(severity Severity, err error, format string, params ...interface{})

func (Logger) Trace Uses

func (l Logger) Trace(params ...interface{})

func (Logger) Tracee Uses

func (l Logger) Tracee(err error, params ...interface{})

func (Logger) Traceef Uses

func (l Logger) Traceef(err error, format string, params ...interface{})

func (Logger) Tracef Uses

func (l Logger) Tracef(format string, params ...interface{})

func (Logger) Warn Uses

func (l Logger) Warn(params ...interface{})

func (Logger) Warne Uses

func (l Logger) Warne(err error, params ...interface{})

func (Logger) Warnef Uses

func (l Logger) Warnef(err error, format string, params ...interface{})

func (Logger) Warnf Uses

func (l Logger) Warnf(format string, params ...interface{})

type MultiSink Uses

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

A sink which dispatches to zero or more other sinks.

var RootSink MultiSink

The sink which is used by default by the root logger.

func (*MultiSink) Add Uses

func (ms *MultiSink) Add(sink Sink)

Add a sink to the MultiSink. Idempotent.

func (*MultiSink) ReceiveFromChild Uses

func (ms *MultiSink) ReceiveFromChild(sev Severity, format string, params ...interface{})

(Implements Sink.)

func (*MultiSink) ReceiveLocally Uses

func (ms *MultiSink) ReceiveLocally(sev Severity, format string, params ...interface{})

(Implements Sink.)

func (*MultiSink) Remove Uses

func (ms *MultiSink) Remove(sink Sink)

Remove a sink from the MultiSink. Idempotent.

type Severity Uses

type Severity int

Log message severity. This is the syslog severity order.

Note that Emergency and Alert are system-level severities. Generally speaking, application programs should not emit log messages at such severities unless they are programs which monitor the system for system-level issues. i.e., programs should never emit Emergency or Alert messages regarding issues with their own operation.

Programs suffering from critical failures should emit log messages at the Critical severity. The Panic*() and Fatal*() log message functions in this package emit log messages at the Critical level.

The Error severity should be used when errors occur which do not constitute a critical or unrecoverable failure of the program.

Any severity less severe than Debug is not part of the syslog severity order. These are converted to messages of Debug severity when exported to e.g. syslog.

Trace should be used for extremely verbose debugging information which is likely to be used mainly for debugging and is of such verbosity that it may overwhelm a programmer unless enabled only for a few specific facilities.

const (
    SevEmergency Severity = iota
    SevAlert
    SevCritical
    SevError
    SevWarn
    SevNotice
    SevInfo
    SevDebug
    SevTrace
    SevNone Severity = -1 // (Do not use.)
)

func ParseSeverity Uses

func ParseSeverity(severity string) (s Severity, ok bool)

Parse a severity string.

func (Severity) String Uses

func (severity Severity) String() string

Returns the severity as an uppercase unabbreviated string.

func (Severity) Syslog Uses

func (severity Severity) Syslog() Severity

Returns the syslog-compatible severity. Converts severities less severe than Debug to Debug.

type Sink Uses

type Sink interface {
    ReceiveLocally(sev Severity, format string, params ...interface{})
    ReceiveFromChild(sev Severity, format string, params ...interface{})
}

Sink is implemented by objects that can receive log messages from loggers deeper in the hierarchy.

var NullSink Sink

The null sink. All log messages to this sink will be discarded.

type Site Uses

type Site interface {
    // The facility name.
    Name() string

    // Sets the severity condition.
    SetSeverity(severity Severity)

    // Set the sink which will receive all messages from this logger.
    SetSink(sink Sink)
}

Site is the interface exposed to the externals of a package, which uses it to configure the logger. This is the other side of a Logger.

var Root Site = rootLogger

The root logger.

type SyslogSink Uses

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

A sink that logs to a "log/syslog".Writer-like interface.

func NewSyslogSink Uses

func NewSyslogSink(syslogger Syslogger) *SyslogSink

Create a new syslog sink. "log/syslog".Writer implements Syslogger.

func (*SyslogSink) ReceiveFromChild Uses

func (ss *SyslogSink) ReceiveFromChild(sev Severity, format string, params ...interface{})

func (*SyslogSink) ReceiveLocally Uses

func (ss *SyslogSink) ReceiveLocally(sev Severity, format string, params ...interface{})

func (*SyslogSink) SetSeverity Uses

func (ss *SyslogSink) SetSeverity(sev Severity)

type Syslogger Uses

type Syslogger interface {
    Alert(m string) error
    Crit(m string) error
    Debug(m string) error
    Emerg(m string) error
    Err(m string) error
    Info(m string) error
    Notice(m string) error
    Warning(m string) error
}

Interface compatible with "log/syslog".Writer.

type WriterSink Uses

type WriterSink struct {
    Systemd bool // Use systemd-format output: "<3>some-log-message"
    // contains filtered or unexported fields
}

Sink which writes each log message on a line to an io.Writer.

var StderrSink *WriterSink

A sink which writes to stderr. This is added to the root sink by default.

func NewWriterSink Uses

func NewWriterSink(w io.Writer) *WriterSink

func (*WriterSink) ReceiveFromChild Uses

func (ws *WriterSink) ReceiveFromChild(sev Severity, format string, params ...interface{})

func (*WriterSink) ReceiveLocally Uses

func (ws *WriterSink) ReceiveLocally(sev Severity, format string, params ...interface{})

func (*WriterSink) SetSeverity Uses

func (ws *WriterSink) SetSeverity(sev Severity)

Package xlog imports 8 packages (graph) and is imported by 2 packages. Updated 2018-06-24. Refresh now. Tools for package owners.