README
¶
kvlog
kvlog is a logging library based on key-value logging implemented using go (golang).
Description
kvlog provides types and functions to produce a log stream of key-value based log events.
Key-value based log messages differ from conventional string-based log messages. They do not
contain a bare string message but any number of key-value-tuples which are encoded using a simple
to parse syntax. This allows log processor systems such as the ELK-stack
to analyze and index the log messages based on key-value-tuples.
Log Format
The format used by kvlog follows the defaults of the
logstash KV filter. The following lines
show examples of the log output
ts=2019-08-16T12:58:22 level=info event=<started>
ts=2019-08-16T12:58:34 level=info event=<request> method=<GET> url=</> status=200 duration=0.001s
ts=2019-08-16T12:58:34 level=info event=<request> method=<GET> url=</favicon.ico> status=404 duration=0.000s
ts=2019-08-16T12:58:35 level=info event=<request> method=<POST> url=</pdf> status=200 duration=0.009s
Installation
$ go get -u bitbucket.org/halimath/kvlog
Usage
kvlog can be used in different ways.
Module functions
The most simple usage uses module functions.
package main
import (
"bitbucket.org/halimath/kvlog"
)
func main () {
// Optionally configure threshold
kvlog.ConfigureThreshold(kvlog.LevelWarn)
// ...
kvlog.Info(kvlog.KV("event", "App started"))
}
The module provides methods for all log level (Debug, Info, Warn, Error) as well as configuration methods
for the threshold (ConfigureThreshold) which defaults to info and for the output (ConfigureOutput) which
defaults to stdout.
Logger instance
A more advanced usage involves a dedicated Logger instance which can be used in dependency injection scenarios.
package main
import (
"bitbucket.org/halimath/kvlog"
)
func main () {
l := kvlog.NewLogger(kvlog.Stdout(), kvlog.LevelInfo)
// ...
l.Info(kvlog.KV("event", "App started"))
}
HTTP handler
kvlog contains an HTTP access log handler, that can be used to wrap other http.Handers.
package main
import (
"net/http"
"bitbucket.org/halimath/kvlog"
)
func main() {
mux := http.NewServeMux()
// ...
kvlog.Info(kvlog.KV("event", "started"))
http.ListenAndServe(":8000", kvlog.Handler(kvlog.L, mux))
}
Changelog
0.1.0
- Initial release
License
Copyright 2019 Alexander Metzner.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Documentation
¶
Overview ¶
Package kvlog provides a key-value based logging system primary targetting container based deployments.
Example ¶
Debug(KV("event", "test"), KV("foo", "bar"))
Info(KV("event", "test"), KV("foo", "bar"))
Output:
Index ¶
- Constants
- func ConfigureOutput(out Output)
- func ConfigureThreshold(t Level)
- func Debug(pairs ...KVPair)
- func Error(pairs ...KVPair)
- func Handler(l *Logger, h http.Handler) http.Handler
- func Info(pairs ...KVPair)
- func Warn(pairs ...KVPair)
- type KVPair
- type Level
- type Logger
- type Message
- type Output
- type WriterLogOutput
Examples ¶
Constants ¶
const ( KeyLevel = "level" KeyTimestamp = "ts" )
Variables ¶
This section is empty.
Functions ¶
func ConfigureOutput ¶
func ConfigureOutput(out Output)
func ConfigureThreshold ¶
func ConfigureThreshold(t Level)
Types ¶
type KVPair ¶
type KVPair struct {
// Key stores the key of the pair
Key string
// Value stores the value
Value interface{}
}
KVPair implements a key-value pair
type Logger ¶
type Logger struct {
Threshold Level
// contains filtered or unexported fields
}
Logger implements a logger component. The output is written to the given output.
var L *Logger
type Message ¶
type Message []KVPair
Message represents a single log message expressed as an ordered list of key value pairs
func NewMessage ¶
NewMessage creates a new message from the given log level and key-value pairs
type Output ¶
type Output interface {
WriteLogMessage(m Message)
}
Output describes the interface to be implemented by log output streams
type WriterLogOutput ¶
type WriterLogOutput struct {
// contains filtered or unexported fields
}
WriterLogOutput implements a Output that writes to an io.Writer
func (*WriterLogOutput) WriteLogMessage ¶
func (w *WriterLogOutput) WriteLogMessage(m Message)
WriteLogMessage writes the bytes to the writer
Source Files