CoLog is a prefix-based leveled execution log for Go

Last update: Dec 14, 2022

Related tags

Overview

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"}}%

Comments

question about best usage when using for testing

Does it parse errors on Tests ?

, i was hoping that doing a t.Error("alert: blah"), would display in Red. In the below example, i end up having to do a t.Error & a log.Println(alert), in order to get the RED visual warning.

I know this is picky ! But when you have lots of tests, looking at your Bash Terminal can get really slow trying to hunt for it. The visual aids are great.

Any advice welcome, as you can see what i can getting at.

func init() {

    colog.Register()
    colog.ParseFields(true)
    colog.SetMinLevel(colog.LWarning)
    colog.SetDefaultLevel(colog.LInfo)
}

func TestGetProduct(t *testing.T) {
    t.Error("alert: thrown from t.Errror !!")
    log.Println("alert: thrown from log.Print !!")


}

Bash Terminal has:

[ alert ] 2016/04/15 18:58:35 thrown from log.Print !!                                          
--- FAIL: TestGetProducts_CategoryOnly (0.01s)
    products_test.go:105: alert: thrown from t.Errro !!
    products_test.go:112: Passed

opened by joeblew99 2

Using `SetFormatter` requires `SetOutput` to print color

prints no color:

colog.SetFormatter(&colog.StdFormatter{})
log.Print("warn: foobar")

prints with color:

colog.SetFormatter(&colog.StdFormatter{})
colog.SetOutput(os.Stderr)
log.Print("warn: foobar")

opened by kyoh86 1

fix README.md

I change example code import "comail.io/go/colog" -> import "github.com/comail/colog". And delete trailing whitespace.

I want to change CoLog showcase image too. But I can not.

opened by kmtr 1
support colors on windows
Following up #1 color should be supported on windows. Since colog shouldn't bring any dependencies this needs to happen via a subpackage or more likely via an extra package like cologrus

this package could do something like have a Register() function itself and call directly colog.Register() then set colorable.NewColorableStderr() as the output.

The question is how the colorSupported() function should become smarter to handle all this scenarios:

windows/no-windows OS

colorable/no-colorable output

tty/no-tty output

// figure if output supports color func (cl *CoLog) colorSupported() bool { if runtime.GOOS == "windows" { return false } if cl.out == os.Stderr && isTerminal(int(os.Stderr.Fd())) { return true } if cl.out == os.Stdout && isTerminal(int(os.Stdout.Fd())) { return true } return false }
opened by bictorman 0
Consider merging with logutils, logfilter

I found out about colog via https://github.com/hashicorp/logutils/issues/5 Another related project is https://github.com/d2g/logfilter

Would you be interested in joining forces? What would you need to see to deprecate colog in favor of something else? Feature parity, migration docs, perf tests, &c? Would you accept changes to enable something else to be deprecated in favor of colog?

opened by josephholsten 0