golog

Overview ¶

Package golog provides an easy to use foundation for your logging operations.

Source code and other details for the project are available at GitHub:

https://github.com/readystock/golog

Current Version ¶

0.0.8

Installation ¶

The only requirement is the Go Programming Language

$ go get -u github.com/readystock/golog

Overview ¶

Example code:

package main

import (
	"github.com/readystock/golog"
)

func main() {
	// Default Output is `os.Stdout`,
	// but you can change it:
	// golog.SetOutput(os.Stderr)

	// Time Format defaults to: "2006/01/02 15:04"
	// you can change it to something else or disable it with:
	golog.SetTimeFormat("")

	// Level defaults to "info",
	// but you can change it:
	golog.SetLevel("debug")

	golog.Println("This is a raw message, no levels, no colors.")
	golog.Info("This is an info message, with colors (if the output is terminal)")
	golog.Warn("This is a warning message")
	golog.Error("This is an error message")
	golog.Debug("This is a debug message")
}

New ¶

Golog has a default, package-level initialized instance for you, however you can choose to create and use a logger instance for a specific part of your application.

Example Code:

package main

import (
	"github.com/readystock/golog"
)

func main() {
	log := golog.New()

	// Default Output is `os.Stdout`,
	// but you can change it:
	// log.SetOutput(os.Stderr)

	// Level defaults to "info",
	// but you can change it:
	log.SetLevel("debug")

	log.Println("This is a raw message, no levels, no colors.")
	log.Info("This is an info message, with colors (if the output is terminal)")
	log.Warn("This is a warning message")
	log.Error("This is an error message")
	log.Debug("This is a debug message")
}

Format ¶

Golog sets colors to levels when its `Printer.Output` is actual a compatible terminal which can renders colors, otherwise it will downgrade itself to a white foreground.

Golog has functions to print a formatted log too.

Example Code:

golog.Infof("[%d] This is an info %s", 1, "formatted log")
golog.Warnf("[%d] This is an info %s", 1, "formatted log")
golog.Errorf("[%d] This is an info %s", 1, "formatted log")
golog.Debugf("[%d] This is an info %s", 1, "formatted log")

Output ¶

Golog takes a simple `io.Writer` as its underline Printer's Output.

Example Code:

golog.SetOutput(io.Writer)

You can even override the default line braker, "\n", by using the `golog#NewLine` function at startup.

Example Code:

golog.NewLine("\r\n")

Levels ¶

Golog is a leveled logger, therefore you can set a level and print whenever the print level is valid with the set-ed one.

Available built'n levels are:

// DisableLevel will disable printer
DisableLevel Level = iota
// ErrorLevel will print only errors
ErrorLevel
// WarnLevel will print errors and warnings
WarnLevel
// InfoLevel will print errors, warnings and infos
InfoLevel
// DebugLevel will print on any level, errors, warnings, infos and debug messages
DebugLevel

Below you'll learn a way to add a custom level or modify an existing level.

The default colorful text(or raw text for unsupported outputs) for levels can be overridden by using the `golog#ErrorText, golog#WarnText, golog#InfoText and golog#DebugText` functions.

Example Code:

package main

import (
	"github.com/readystock/golog"
)

func main() {

	// First argument is the raw text for outputs
	// that are not support colors,
	// second argument is the full colorful text (yes it can be different if you wish to).
	//
	// If the second argument is empty then golog will update the colorful text to the
	// default color (i.e red on ErrorText) based on the first argument.

	// Default is "[ERRO]"
	golog.ErrorText("|ERROR|", "")
	// Default is "[WARN]"
	golog.WarnText("|WARN|", "")
	// Default is "[INFO]"
	golog.InfoText("|INFO|", "")
	// Default is "[DBUG]"
	golog.DebugText("|DEBUG|", "")

	// Business as usual...
	golog.SetLevel("debug")

	golog.Println("This is a raw message, no levels, no colors.")
	golog.Info("This is an info message, with colors (if the output is terminal)")
	golog.Warn("This is a warning message")
	golog.Error("This is an error message")
	golog.Debug("This is a debug message")
}

Golog gives you the power to add or modify existing levels is via Level Metadata.

Example Code:

package main

import (
	"github.com/readystock/golog"
)

func main() {
	// Let's add a custom level,
	//
	// It should be starting from level index 6,
	// because we have 6 built'n levels  (0 is the start index):
	// disable,
	// fatal,
	// error,
	// warn,
	// info
	// debug

	// First we create our level to a golog.Level
	// in order to be used in the Log functions.
	var SuccessLevel golog.Level = 6
	// Register our level, just three fields.
	golog.Levels[SuccessLevel] = &golog.LevelMetadata{
		Name:    "success",
		RawText: "[SUCC]",
		// ColorfulText (Green Color[SUCC])
		ColorfulText: "\x1b[32m[SUCC]\x1b[0m",
	}

	// create a new golog logger
	myLogger := golog.New()

	// set its level to the higher in order to see it
	// ("success" is the name we gave to our level)
	myLogger.SetLevel("success")

	// and finally print a log message with our custom level
	myLogger.Logf(SuccessLevel, "This is a success log message with green color")
}

The logger's level can be changed via passing one of the level constants to the `Level` field or by passing its string representation to the `SetLevel` function.

Example Code:

golog.SetLevel("disable")
golog.SetLevel("fatal")
golog.SetLevel("error")
golog.SetLevel("warn")
golog.SetLevel("info")
golog.SetLevel("debug")

Integrations ¶

Transaction with your favorite, but deprecated logger is easy. Golog offers two basic interfaces, the `ExternalLogger` and the `StdLogger` that can be directly used as arguments to the `Install` function in order to adapt an external logger.

Outline:

// Install receives  an external logger
// and automatically adapts its print functions.
//
// Install adds a golog handler to support third-party integrations,
// it can be used only once per `golog#Logger` instance.
//
// For example, if you want to print using a logrus
// logger you can do the following:
// `golog.Install(logrus.StandardLogger())`
//
// Look `golog#Handle` for more.
Install(logger ExternalLogger)

// InstallStd receives  a standard logger
// and automatically adapts its print functions.
//
// Install adds a golog handler to support third-party integrations,
// it can be used only once per `golog#Logger` instance.
//
// Example Code:
//	import "log"
//	myLogger := log.New(os.Stdout, "", 0)
//	InstallStd(myLogger)
//
// Look `golog#Handle` for more.
InstallStd(logger StdLogger)

Logrus Integration ¶

Example Code:

package main

import (
	"github.com/readystock/golog"
	"github.com/sirupsen/logrus"
)

func main() {
	// outputOnly()
	full()
}

func full() {
	// simulate a logrus preparation:
	logrus.SetLevel(logrus.InfoLevel)
	logrus.SetFormatter(&logrus.JSONFormatter{})

	// pass logrus.StandardLogger() to print logs using using the default,
	// package-level logrus' instance of Logger:
	golog.Install(logrus.StandardLogger())

	golog.Debug(`this debug message will not be shown,
	because the logrus level is InfoLevel`)
	golog.Error("this error message will be visible as json")

	// simulate a change of the logrus formatter
	// as you see we have nothing more to change
	// on the golog, it works out of the box,
	// it will be adapt by this change, automatically.
	logrus.SetFormatter(&logrus.TextFormatter{})

	golog.Error("this error message will be visible as text")
	golog.Info("this info message will be visible as text")
}

func outputOnly() {
	golog.SetOutput(logrus.StandardLogger().Out)
	golog.Info(`output only, this will print the same contents
	as golog but using the defined logrus' io.Writer`)

	golog.Error("this error message will be visible as text")
}

Standard `log.Logger` Integration ¶

Example Code:

package main

import (
	"log"
	"os"

	"github.com/readystock/golog"
)

// simulate a log.Logger preparation:
var myLogger = log.New(os.Stdout, "", 0)

func main() {
	golog.SetLevel("error")
	golog.InstallStd(myLogger)

	golog.Debug(`this debug message will not be shown,
	because the golog level is ErrorLevel`)

	golog.Error("this error message will be visible the only visible")

	golog.Warn("this info message will not be visible")
}

That's the basics ¶

But you should have a basic idea of the golog package by now, we just scratched the surface. If you enjoy what you just saw and want to learn more, please follow the below links:

Examples:

https://github.com/readystock/golog/tree/master/_examples