What's CoLog?

CoLog is a prefix-based leveled execution log for Go. It's heavily inspired by Logrus and aims to offer similar features by parsing the output of the standard library log. If you don't understand what this means take a look at this picture.

But why?

An introduction and the rationale behind CoLog can be found in this blog post: https://texlution.com/post/colog-prefix-based-logging-in-golang/

Features

• Supports hooks to receive log entries and send them to external systems via AddHook
• Supports customs formatters (color/pain text and JSON built-in) via SetFormatter
• Provides 6 built-in levels: trace, debug, info, warning, error, alert
• Understands full, 3 letter, and 1 letter headers: error:, err:, e:
• Supports custom prefixes (headers in CoLog terms) via SetHeaders and AddHeader
• Control levels used via SetMinLevel and SetDefaultLevel
• Supports optionally parsing key=value or key='some value' pairs
• Supports custom key-value extractor via SetExtractor
• Supports permanent context values via FixedValue and ClearFixedValues
• Supports standalone loggers via NewCoLog and NewLogger
• Compatible with existing Logrus hooks and formatters via cologrus
• Supports Windows terminal colors via wincolog

API stability

CoLog's API is very unlikely to get breaking changes, but there are no promises. That being said, CoLog only needs to be imported by final applications and if you have one of those, you should be vendoring you dependencies in the first place. CoLog has no external dependencies, to vendor it you just need to clone this repo anywhere you want and start using it.

Usage examples

Basic usage

package main

import (
	"log"

	"github.com/comail/colog"
)

func main() {
	colog.Register()
	log.Print("info: that's all it takes!")
}

JSON output to a file with field parsing

package main

import (
	"log"
	"os"
	"time"

	"github.com/comail/colog"
)

func main() {
	file, err := os.OpenFile("temp_json.log", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0777)
	if err != nil {
		panic(err)
	}

	colog.Register()
	colog.SetOutput(file)
	colog.ParseFields(true)
	colog.SetFormatter(&colog.JSONFormatter{
		TimeFormat: time.RFC3339,
		Flag:       log.Lshortfile,
	})

	log.Print("info: logging this to json")
	log.Print("warning: with fields foo=bar")
}

// cat tempjson.log
// {"level":"info","time":"2015-08-16T13:26:07+02:00","file":"json_example.go","line":24,"message":"logging this to json"}
// {"level":"warning","time":"2015-08-16T13:26:07+02:00","file":"json_example.go","line":25,"message":"with fields","fields":{"foo":"bar"}}

Standalone logger with level control and fixed values

package main

import (
	"log"
	"os"

	"github.com/comail/colog"
)

func main() {
	cl := colog.NewCoLog(os.Stdout, "worker ", log.LstdFlags)
	cl.SetMinLevel(colog.LInfo)
	cl.SetDefaultLevel(colog.LWarning)
	cl.FixedValue("worker_id", 42)

	logger := cl.NewLogger()
	logger.Print("this gets warning level")
	logger.Print("debug: this won't be displayed")
}

// [  warn ] worker 2015/08/16 13:43:06 this gets warning level    worker_id=42

Adding custom hooks

package main

import (
	"fmt"
	"log"

	"github.com/comail/colog"
)

type myHook struct {
	levels []colog.Level
}

func (h *myHook) Levels() []colog.Level {
	return h.levels
}

func (h *myHook) Fire(e *colog.Entry) error {
	fmt.Printf("We got an entry: \n%#v", e)
	return nil
}

func main() {
	colog.Register()
	colog.ParseFields(true)

	hook := &myHook{
		levels: []colog.Level{
			colog.LInfo,    // the hook only receives
			colog.LWarning, // these levels
		},
	}

	colog.AddHook(hook)

	colog.SetMinLevel(colog.LError) // this affects only the output
	log.Print("info: something foo=bar")
}

// We got an entry:
// &colog.Entry{Level:0x3, Time:time.Time{sec:63575323196, nsec:244349216, loc:(*time.Location)(0x23f8c0)}, Host:"",
// Prefix:"", File:"/data/workspace/comail/comail/src/comail.io/go/colog/examples/hook_example.go", Line:37,
// Message:[]uint8{0x73, 0x6f, 0x6d, 0x65, 0x74, 0x68, 0x69, 0x6e, 0x67}, Fields:colog.Fields{"foo":"bar"}}%