README
¶
jsonlog
=======
Victor Schubert <victor@trackit.io>
v1.0, 2017-10-05
_jsonlog_ is a simple Go logger. It produces structured logs using JSON and can
also output arbitrary data taken as an argument and from a `context.Context`.
== Usage
=== Logging
The module provides a default logger which logs on the standard output.
[source,go]
----
package main
import "github.com/trackit/jsonlog"
func main() {
jsonlog.DefaultLogger.Info("Info log message", nil)
jsonlog.DefaultLogger.Warning("Warning with data", map[string]int{ "foobar": 42 })
}
----
This code produces the following output (the JSON objects were prettified, the
library outputs each object on a single line and without unnecessary spaces):
[source,json]
----
{
"message": "Info log message",
"level": "info",
"time": "2017-10-05T21:07:58.115210089+02:00"
}
{
"message": "Warning with data",
"level": "warning",
"time": "2017-10-05T21:07:58.115320884+02:00",
"data": {
"foobar": 42
}
}
----
=== Choosing the log level
The logger has four log levels: debug, info, warning and error. Each message
has a `"level"` field to indicate the message's level.
[source,go]
----
package main
import "github.com/trackit/jsonlog"
func main() {
logger := jsonlog.DefaultLogger.WithLogLevel(jsonlog.LogLevelDebug)
logger.Debug("Debug message. Only prints with adequate log level.", nil)
}
----
=== Using values from a context
The Go standard library provides the `context` module to propagate
cancellation, enforce timeouts and hold data about the current context.
_jsonlog_ can make use of those values.
[source,go]
----
package main
import (
"context"
"math/rand"
"github.com/trackit/jsonlog"
)
const (
runId = iota
)
func main() {
ctx := context.WithValue(context.Background(), runId, rand.Int63())
logger := jsonlog.DefaultLogger.WithContext(ctx).WithContextKey(runId, "runId")
logger.Info("Log with context", nil)
}
----
A `Logger` with a `Context` and registered context keys will include the
context values in each message; the previous code would produce the following
log: (the JSON object was prettified)
[source,go]
----
{
"message": "Log with context",
"level": "info",
"time": "2017-10-05T21:18:49.973938562+02:00",
"context": {
"runId": 5577006791947779410
}
}
----
Documentation
¶
Overview ¶
Package logs provides structured JSON logging with arbitrary data. It supports contexts and can extract values from these.
Index ¶
- Constants
- Variables
- func ContextWithLogger(ctx context.Context, logger Logger) context.Context
- func Debug(str string, data interface{}) error
- func Error(str string, data interface{}) error
- func Info(str string, data interface{}) error
- func Log(logLevel LogLevel, str string, data interface{}) error
- func Warning(str string, data interface{}) error
- type LogLevel
- type Logger
- func (l Logger) Debug(str string, data interface{}) error
- func (l Logger) Error(str string, data interface{}) error
- func (l Logger) Info(str string, data interface{}) error
- func (l Logger) Log(logLevel LogLevel, str string, data interface{}) error
- func (l Logger) Warning(str string, data interface{}) error
- func (l Logger) WithContext(ctx context.Context) Logger
- func (l Logger) WithContextKey(contextKey interface{}, messageKey string) Logger
- func (l Logger) WithLogLevel(logLevel LogLevel) Logger
- func (l Logger) WithWriter(w io.Writer) Logger
Constants ¶
const ( LogLevelDebug = LogLevel(iota) LogLevelInfo LogLevelWarning LogLevelError )
Variables ¶
var ( // DefaultLogger logs to the standard output, filtering out debug // messages, and uses the background context. DefaultLogger = Logger{ // contains filtered or unexported fields } )
Functions ¶
func ContextWithLogger ¶ added in v1.1.0
ContextWithLogger creates a new context holding a given logger. The logger can be retrieved with LoggerFromContextOrDefault.
Types ¶
type LogLevel ¶
type LogLevel uint
LogLevel represents a level of logging: the Logger is setup with one and will only log messages with a log level superior or equal to its own.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger logs messages to an io.Writer in JSON format, possibly extracting values from its Context.
func LoggerFromContextOrDefault ¶ added in v1.1.0
LoggerFromContextOrDefault gets a Logger from the current context if there is one. Otherwise it returns the default logger.
func (Logger) Log ¶
Log logs a message as specified by the Logger. Each message is output as a JSON object with `str' in the "message" field, `data' in the "data" field (if not nil) and values from the context in "context".
func (Logger) WithContext ¶
WithContext returns a new Logger with the given context.
func (Logger) WithContextKey ¶
WithContextKey returns a new Logger which will extract from the context the value at `contextKey' and output it under `messageKey' in the JSON message.
func (Logger) WithLogLevel ¶
WithLogLevel returns a new Logger with the given log level.
Source Files