README
go-log
The logging library used by go-ipfs
It currently uses a modified version of go-logging to implement the standard printf-style log output.
Install
go get github.com/ipfs/go-log
Usage
Once the package is imported under the name logging
, an instance of EventLogger
can be created like so:
var log = logging.Logger("subsystem name")
It can then be used to emit log messages, either plain printf-style messages at six standard levels or structured messages using Start
, StartFromParentState
, Finish
and FinishWithErr
methods.
Example
func (s *Session) GetBlock(ctx context.Context, c *cid.Cid) (blk blocks.Block, err error) {
// Starts Span called "Session.GetBlock", associates with `ctx`
ctx = log.Start(ctx, "Session.GetBlock")
// defer so `blk` and `err` can be evaluated after call
defer func() {
// tag span associated with `ctx`
log.SetTags(ctx, map[string]interface{}{
"cid": c,
"block", blk,
})
// if err is non-nil tag the span with an error
log.FinishWithErr(ctx, err)
}()
if shouldStartSomething() {
// log message on span associated with `ctx`
log.LogKV(ctx, "startSomething", true)
}
...
}
Tracing
go-log
wraps the opentracing-go methods - StartSpan
, Finish
, LogKV
, and SetTag
.
go-log
implements its own tracer - loggabletracer
- based on the basictracer-go implementation. If there is an active WriterGroup
the loggabletracer
will record span data to the WriterGroup
. An example of this can be seen in the log tail
command of go-ipfs
.
Third party tracers may be used by calling opentracing.SetGlobalTracer()
with your desired tracing implementation. An example of this can be seen using the go-jaeger-plugin
and the go-ipfs
tracer plugin
Contribute
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.
Want to hack on IPFS?
License
MIT
Documentation
Overview ¶
Package log is the logging library used by IPFS (https://github.com/ipfs/go-ipfs). It uses a modified version of https://godoc.org/github.com/whyrusleeping/go-logging .
Index ¶
- Variables
- func ContextWithLoggable(ctx context.Context, l Loggable) context.Context
- func FormatRFC3339(t time.Time) string
- func GetSubsystems() []string
- func SetAllLoggers(lvl LogLevel)
- func SetDebugLogging()
- func SetLogLevel(name, level string) error
- func SetLogLevelRegex(e, l string) error
- func SetupLogging()
- type EventInProgress
- type EventLogger
- type LogLevel
- type Loggable
- type LoggableF
- type LoggableMap
- type Metadata
- type StandardLogger
- type ZapEventLogger
- func (el *ZapEventLogger) Event(ctx context.Context, event string, metadata ...Loggable)
- func (el *ZapEventLogger) EventBegin(ctx context.Context, event string, metadata ...Loggable) *EventInProgress
- func (el *ZapEventLogger) Finish(ctx context.Context)
- func (el *ZapEventLogger) FinishWithErr(ctx context.Context, err error)
- func (el *ZapEventLogger) LogKV(ctx context.Context, alternatingKeyValues ...interface{})
- func (el *ZapEventLogger) SerializeContext(ctx context.Context) ([]byte, error)
- func (el *ZapEventLogger) SetErr(ctx context.Context, err error)
- func (el *ZapEventLogger) SetTag(ctx context.Context, k string, v interface{})
- func (el *ZapEventLogger) SetTags(ctx context.Context, tags map[string]interface{})
- func (el *ZapEventLogger) Start(ctx context.Context, operationName string) context.Context
- func (el *ZapEventLogger) StartFromParentState(ctx context.Context, operationName string, parent []byte) (context.Context, error)
- func (el *ZapEventLogger) Warning(args ...interface{})
- func (el *ZapEventLogger) Warningf(format string, args ...interface{})
Examples ¶
Constants ¶
Variables ¶
var ( LevelDebug = log2.LevelDebug LevelInfo = log2.LevelInfo LevelWarn = log2.LevelWarn LevelError = log2.LevelError LevelDPanic = log2.LevelDPanic LevelPanic = log2.LevelPanic LevelFatal = log2.LevelFatal )
Functions ¶
func ContextWithLoggable ¶
ContextWithLoggable returns a derived context which contains the provided Loggable. Any Events logged with the derived context will include the provided Loggable.
func FormatRFC3339 ¶
FormatRFC3339 returns the given time in UTC with RFC3999Nano format.
func GetSubsystems ¶
func GetSubsystems() []string
GetSubsystems returns a slice containing the names of the current loggers
func SetAllLoggers ¶
func SetAllLoggers(lvl LogLevel)
SetAllLoggers changes the logging level of all loggers to lvl
func SetDebugLogging ¶
func SetDebugLogging()
SetDebugLogging calls SetAllLoggers with logging.DEBUG
func SetLogLevel ¶
SetLogLevel changes the log level of a specific subsystem name=="*" changes all subsystems
func SetLogLevelRegex ¶
SetLogLevelRegex sets all loggers to level `l` that match expression `e`. An error is returned if `e` fails to compile.
func SetupLogging ¶
func SetupLogging()
Types ¶
type EventInProgress ¶
type EventInProgress struct {
// contains filtered or unexported fields
}
DEPRECATED EventInProgress represent and event which is happening Deprecated: Stop using go-log for event logging
func (*EventInProgress) Append ¶
func (eip *EventInProgress) Append(l Loggable)
DEPRECATED use `LogKV` or `SetTag` Append adds loggables to be included in the call to Done
func (*EventInProgress) Close ¶
func (eip *EventInProgress) Close() error
Close is an alias for done Deprecated: Stop using go-log for event logging
func (*EventInProgress) Done ¶
func (eip *EventInProgress) Done()
Done creates a new Event entry that includes the duration and appended loggables. Deprecated: Stop using go-log for event logging
func (*EventInProgress) DoneWithErr ¶
func (eip *EventInProgress) DoneWithErr(err error)
DEPRECATED use `FinishWithErr` DoneWithErr creates a new Event entry that includes the duration and appended loggables. DoneWithErr accepts an error, if err is non-nil, it is set on the EventInProgress. Otherwise the logic is the same as the `Done()` method
func (*EventInProgress) SetError ¶
func (eip *EventInProgress) SetError(err error)
DEPRECATED use `SetError(ctx, error)` SetError includes the provided error
type EventLogger ¶
type EventLogger interface { StandardLogger // Event merges structured data from the provided inputs into a single // machine-readable log event. // // If the context contains metadata, a copy of this is used as the base // metadata accumulator. // // If one or more loggable objects are provided, these are deep-merged into base blob. // // Next, the event name is added to the blob under the key "event". If // the key "event" already exists, it will be over-written. // // Finally the timestamp and package name are added to the accumulator and // the metadata is logged. // DEPRECATED // Deprecated: Stop using go-log for event logging Event(ctx context.Context, event string, m ...Loggable) // DEPRECATED // Deprecated: Stop using go-log for event logging EventBegin(ctx context.Context, event string, m ...Loggable) *EventInProgress // Start starts an opentracing span with `name`, using // any Span found within `ctx` as a ChildOfRef. If no such parent could be // found, Start creates a root (parentless) Span. // // The return value is a context.Context object built around the // returned Span. // // Example usage: // // SomeFunction(ctx context.Context, ...) { // ctx := log.Start(ctx, "SomeFunction") // defer log.Finish(ctx) // ... // } // Deprecated: Stop using go-log for event logging Start(ctx context.Context, name string) context.Context // StartFromParentState starts an opentracing span with `name`, using // any Span found within `ctx` as a ChildOfRef. If no such parent could be // found, StartSpanFromParentState creates a root (parentless) Span. // // StartFromParentState will attempt to deserialize a SpanContext from `parent`, // using any Span found within to continue the trace // // The return value is a context.Context object built around the // returned Span. // // An error is returned when `parent` cannot be deserialized to a SpanContext // // Example usage: // // SomeFunction(ctx context.Context, bParent []byte) { // ctx := log.StartFromParentState(ctx, "SomeFunction", bParent) // defer log.Finish(ctx) // ... // } // Deprecated: Stop using go-log for event logging StartFromParentState(ctx context.Context, name string, parent []byte) (context.Context, error) // Finish completes the span associated with `ctx`. // // Finish() must be the last call made to any span instance, and to do // otherwise leads to undefined behavior. // Finish will do its best to notify (log) when used in correctly // .e.g called twice, or called on a spanless `ctx` // Deprecated: Stop using go-log for event logging Finish(ctx context.Context) // FinishWithErr completes the span associated with `ctx` and also calls // SetErr if `err` is non-nil // // FinishWithErr() must be the last call made to any span instance, and to do // otherwise leads to undefined behavior. // FinishWithErr will do its best to notify (log) when used in correctly // .e.g called twice, or called on a spanless `ctx` // Deprecated: Stop using go-log for event logging FinishWithErr(ctx context.Context, err error) // SetErr tags the span associated with `ctx` to reflect an error occured, and // logs the value `err` under key `error`. // Deprecated: Stop using go-log for event logging SetErr(ctx context.Context, err error) // LogKV records key:value logging data about an event stored in `ctx` // Eexample: // log.LogKV( // "error", "resolve failure", // "type", "cache timeout", // "waited.millis", 1500) // Deprecated: Stop using go-log for event logging LogKV(ctx context.Context, alternatingKeyValues ...interface{}) // SetTag tags key `k` and value `v` on the span associated with `ctx` // Deprecated: Stop using go-log for event logging SetTag(ctx context.Context, key string, value interface{}) // SetTags tags keys from the `tags` maps on the span associated with `ctx` // Example: // log.SetTags(ctx, map[string]{ // "type": bizStruct, // "request": req, // }) // Deprecated: Stop using go-log for event logging SetTags(ctx context.Context, tags map[string]interface{}) // SerializeContext takes the SpanContext instance stored in `ctx` and Seralizes // it to bytes. An error is returned if the `ctx` cannot be serialized to // a bytes array // Deprecated: Stop using go-log for event logging SerializeContext(ctx context.Context) ([]byte, error) }
EventLogger extends the StandardLogger interface to allow for log items containing structured metadata
Example ¶
Output:
type LogLevel ¶
LogLevel represents a log severity level. Use the package variables as an enum.
func LevelFromString ¶
LevelFromString parses a string-based level and returns the corresponding LogLevel.
Supported strings are: DEBUG, INFO, WARN, ERROR, DPANIC, PANIC, FATAL, and their lower-case forms.
The returned LogLevel must be discarded if error is not nil.
type Loggable ¶
type Loggable interface {
Loggable() map[string]interface{}
}
Loggable describes objects that can be marshalled into Metadata for logging
type LoggableF ¶
type LoggableF func() map[string]interface{}
LoggableF converts a func into a Loggable
type LoggableMap ¶
type LoggableMap map[string]interface{}
LoggableMap is just a generic map keyed by string. It implements the Loggable interface.
func (LoggableMap) Loggable ¶
func (l LoggableMap) Loggable() map[string]interface{}
Loggable implements the Loggable interface for LoggableMap
type Metadata ¶
type Metadata map[string]interface{}
Metadata is a convenience type for generic maps
func DeepMerge ¶
DeepMerge merges the second Metadata parameter into the first. Nested Metadata are merged recursively. Primitives are over-written.
func MetadataFromContext ¶
MetadataFromContext extracts Matadata from a given context's value.
func Metadatify ¶
Metadatify converts maps into Metadata.
func (Metadata) JsonString ¶
JsonString returns the marshaled JSON string for the metadata.
type StandardLogger ¶
type StandardLogger interface { log2.StandardLogger // Deprecated use Warn Warning(args ...interface{}) // Deprecated use Warnf Warningf(format string, args ...interface{}) }
StandardLogger provides API compatibility with standard printf loggers eg. go-logging
type ZapEventLogger ¶
type ZapEventLogger struct { zap.SugaredLogger // contains filtered or unexported fields }
ZapEventLogger implements the EventLogger and wraps a go-logging Logger
func (*ZapEventLogger) Event ¶
func (el *ZapEventLogger) Event(ctx context.Context, event string, metadata ...Loggable)
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) EventBegin ¶
func (el *ZapEventLogger) EventBegin(ctx context.Context, event string, metadata ...Loggable) *EventInProgress
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) Finish ¶
func (el *ZapEventLogger) Finish(ctx context.Context)
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) FinishWithErr ¶
func (el *ZapEventLogger) FinishWithErr(ctx context.Context, err error)
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) LogKV ¶
func (el *ZapEventLogger) LogKV(ctx context.Context, alternatingKeyValues ...interface{})
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) SerializeContext ¶
func (el *ZapEventLogger) SerializeContext(ctx context.Context) ([]byte, error)
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) SetErr ¶
func (el *ZapEventLogger) SetErr(ctx context.Context, err error)
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) SetTag ¶
func (el *ZapEventLogger) SetTag(ctx context.Context, k string, v interface{})
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) SetTags ¶
func (el *ZapEventLogger) SetTags(ctx context.Context, tags map[string]interface{})
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) StartFromParentState ¶
func (el *ZapEventLogger) StartFromParentState(ctx context.Context, operationName string, parent []byte) (context.Context, error)
Deprecated: Stop using go-log for event logging
func (*ZapEventLogger) Warning ¶
func (el *ZapEventLogger) Warning(args ...interface{})
Deprecated: use Warn
func (*ZapEventLogger) Warningf ¶
func (el *ZapEventLogger) Warningf(format string, args ...interface{})
Deprecated: use Warnf