README ¶
ulog
ulog is the antidote to modern loggers.
- ULog only logs JSON formatted output. Structured logging is the only good logging.
- ULog does not have log levels. If you don't want something logged, don't log it.
- ULog supports setting fields in context. This is useful for building a log context over the course of an operation.
- ULog has no dependencies. Using ulog only brings in what it needs, and that isn't much!
- ULog always uses RFC3339 formatted UTC timestamps, for sanity.
Basic Usage
ulog.Print("a message")
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message" }
With Fields
ulog.Print("a message",
"field", "value",
"a_number", 123,
"a_bool", false,
)
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message", "field": "value", "a_number": 123, "a_bool": false }
With Context
logger := ulog.With(
"request_id", "12345",
"user_id": "big_jim_mcdonald",
)
logger.Print("a message",
"field", "value",
"a_number", 123,
"a_bool", false)
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message", "request_id": "12345", "user_id": "big_jim_mcdonald", "field": "value", "a_number": 123, "a_bool": false }
With More Complex Data Types
ulog.Print("something complex!",
"array", []string{"this", "is", "an", "array"},
"map", map[string]string{
"key": "value",
"just": "like that",
},
"the_ulog_struct_itself", ulog.With("hello", "world"),
)
{ "ts": "2019-11-18T13:41:56Z", "msg": "something complex!", "array": [ "this", "is", "an", "array" ], "map": { "key": "value", "just": "like that" }, "the_ulog_struct_itself": { "Fields": [ "hello", "world" ] } }
Output To Somewhere Other Than STDOUT
var sb strings.Builder
logger := ulog.WithWriter(sb)
logger.Print("a message",
"field", "value",
"a_number", 123,
"a_bool", false)
fmt.Println(sb.String())
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message", "field": "value", "a_number": 123, "a_bool": false }
Output to systemd-journald
import "github.com/UNO-SOFT/ulog/ulogjournal"
logger := ulog.WithWriter(ulogjournal.Maybe(os.Stderr))
This will log to /var/run/systemd/journal/socket
if exists and os.Stderr
is the same as file as $JOURNAL_STREAM
says, os.Stderr
otherwise.
For more information, see journald and JOURNAL_STREAM.
Documentation ¶
Overview ¶
Package ulog is the antidote to modern loggers.
ulog only logs JSON formatted output. Structured logging is the only good logging.
ulog does not have log levels. If you don't want something logged, don't log it.
ulog does support setting fields in context. Useful for building a log context over the course of an operation.
Index ¶
- Constants
- Variables
- func Log(keyvals ...interface{}) error
- func Print(msg string, fields ...Field) error
- func WithContext(ctx context.Context) context.Context
- func Write(msg string, fields ...Field)
- type Field
- type ULog
- func (u ULog) Log(keyvals ...interface{}) error
- func (u ULog) Print(msg string, fields ...Field) error
- func (u ULog) With(fields ...Field) ULog
- func (u ULog) WithContext(ctx context.Context) context.Context
- func (u ULog) WithKeyNames(timestampKey, messageKey string) ULog
- func (u ULog) Write(msg string, fields ...Field)
Constants ¶
const ( DefaultTimestampKey = "ts" DefaultMessageKey = "msg" )
Variables ¶
var (
DefaultWriter = os.Stderr
)
Functions ¶
func WithContext ¶ added in v1.1.6
WithContext returns a Context, storing the default ULog in it.
Types ¶
type ULog ¶
type ULog struct { Writer io.Writer TimestampKey, MessageKey string `json:"-"` // contains filtered or unexported fields }
ULog is the antidote to modern loggers
func FromContext ¶ added in v1.1.6
FromContext returns the ULog from the Context, or a disabled logger if no logger is set on the Context.
func NewTestLogger ¶ added in v1.2.1
func NewTestLogger(t testLogger) ULog
func WithKeyNames ¶
WithKeyNames returns a copy of the ULog instance with the provided key names for timestamp and message keys.
func WithWriter ¶
WithWriter returns a copy of the standard ULog instance configured to write to the given writer
If w has a Print(string, ...Field) method, then that will be used, without JSON encoding! This can be useful for example with ulogjournal.
func (ULog) Print ¶ added in v1.4.0
Print a JSON message to the configured writer or os.Stderr.
Includes the message with the key `msg`. Includes the timestamp with the key `ts`. The timestamp field is always first and the message second.
Fields in context will not be overridden. ULog will log the same key multiple times if it is set multiple times. If you don't want that, don't specify it multiple times.
If the underlying Writer has a Print method (with the same signature), than that will be used.
func (ULog) With ¶
With returns a copy of the ULog instance with the provided fields preset for every subsequent call.
func (ULog) WithContext ¶ added in v1.1.6
WithContext returns a Context, storing the ULog in int.
func (ULog) WithKeyNames ¶
WithKeyNames returns a copy of the ULog instance with the provided key names for timestamp and message keys.