go-logging

go-logging is a high-performance logging library for golang.

• Simple: It supports only necessary operations and easy to get started.
• Fast: Asynchronous logging without runtime-related fields has an extremely low delay of about 800 nano-seconds.
• Performance in my laptop as follow.

BenchmarkSync 300000 4018 ns/op
BenchmarkAsync 300000 4229 ns/op
BenchmarkBasicSync 500000 2504 ns/op
BenchmarkBasicAsync 1000000 2495 ns/op
BenchmarkPrintln 1000000 1550 ns/op

Getting Started

Installation

The step below will download the library source code to ${GOPATH}/src/github.com/ccding/go-logging.

go get github.com/ccding/go-logging/logging

Given the source code downloaded, it makes you be able to run the examples, tests, and benchmarks.

cd${GOPATH}/src/github.com/ccding/go-logging/logging
go get
go run ../example.go
go test -v -bench .

Example

go-logging is used like any other Go libraries. You can simply use the library in this way.

import"github.com/ccding/go-logging/logging"

Here is a simple example.

package main
import (
"github.com/ccding/go-logging/logging"
)
funcmain() {
logger, _:=logging.SimpleLogger("main")
logger.Error("this is a test from error")
logger.Destroy()
}

Configuration

Construction Functions

It has the following functions to create a logger.

// with BasicFormat and writing to stdoutSimpleLogger(namestring) (*Logger, error)
// with BasicFormat and writing to DefaultFileNameBasicLogger(namestring) (*Logger, error)
// with RichFormatand writing to DefaultFileNameRichLogger(namestring) (*Logger, error)
// with detailed configuration and writing to fileFileLogger(namestring, levelLevel, formatstring, timeFormatstring, filestring, syncbool) (*Logger, error)
// with detailed configuration and writing to a writerWriterLogger(namestring, levelLevel, formatstring, timeFormatstring, outio.Writer, syncbool) (*Logger, error)
// read configurations from a config fileConfigLogger(filenamestring) (*Logger, error)

The meanings of these fields are

namestring// logger namelevelLevel// record level higher than this will be printedformatstring// format configurationtimeFormatstring// format for timefilestring// file name for loggingoutio.Writer// writer for loggingsyncbool// use sync or async way to record logs

The detailed description of these fields will be presented later.

Logging Functions

It supports the following functions for logging. All of these functions are thread-safe.

(*Logger) Logf(levelLevel, formatstring, v...interface{})
(*Logger) Log(levelLevel, v...interface{})
(*Logger) Criticalf(formatstring, v...interface{})
(*Logger) Critical(v...interface{})
(*Logger) Fatalf(formatstring, v...interface{})
(*Logger) Fatal(v...interface{})
(*Logger) Errorf(formatstring, v...interface{})
(*Logger) Error(v...interface{})
(*Logger) Warningf(formatstring, v...interface{})
(*Logger) Warning(v...interface{})
(*Logger) Warnf(formatstring, v...interface{})
(*Logger) Warn(v...interface{})
(*Logger) Infof(formatstring, v...interface{})
(*Logger) Info(v...interface{})
(*Logger) Debugf(formatstring, v...interface{})
(*Logger) Debug(v...interface{})
(*Logger) Notsetf(formatstring, v...interface{})
(*Logger) Notset(v...interface{})

Logger Operations

The logger supports the following operations. In these functions, SetWriter and Destroy are not thread-safe, while others are. All these functions are running in a synchronous way.

// Getter functions
(*Logger) Name() string// get name
(*Logger) TimeFormat() string// get time format
(*Logger) Level() Level// get level [this function is thread safe]
(*Logger) RecordFormat() string// get the first part of the format
(*Logger) RecordArgs() []string// get the second part of the format
(*Logger) Writer() io.Writer// get writer
(*Logger) Sync() bool// get sync or async// Setter functions
(*Logger) SetLevel(levelLevel) // set level [this function is thread safe]
(*Logger) SetWriter(out...io.Writer) // set multiple writers// Other functions
(*Logger) Flush() // flush the writer
(*Logger) Destroy() // destroy the logger

Fields Description

Name

Name field is a string, which can be written to the logging and used to separate multiple loggers. It allows two logger having the same name. There is not any default value for name.

Logging Levels

There are these levels in logging.

CRITICAL50FATALCRITICALERROR40WARNING30WARNWARNINGINFO20DEBUG10NOTSET0

Record Format

The record format is described by a string, which has two parts separated by \n. The first part describes the format of the log, and the second part lists all the fields to be shown in the log. In other word, the first part is the first parameter format of fmt.Printf(format string, v ...interface{}), and the second part describes the second parameter v of it. It is not allowed to have \n in the first part. The fields in the second part are separated by comma ,, while extra blank spaces are allowed. An example of the format string is

constBasicFormat="%s [%6s] %30s - %s\n name,levelname,time,message"

which is the pre-defined BasicFormat used by BasicLogger() and SimpleLogger().

It supports the following fields for the second part of the format.

"name"string%s// name of the logger"seqid"uint64%d// sequence number"levelno"int32%d// level number"levelname"string%s// level name"created"int64%d// starting time of the logger"nsecs"int64%d// nanosecond of the starting time"time"string%s// record created time"timestamp"int64%d// timestamp of record"rtime"int64%d// relative time since started"filename"string%s// source filename of the caller"pathname"string%s// filename with path"module"string%s// executable filename"lineno"int%d// line number in source code"funcname"string%s// function name of the caller"process"int%d// process id"message"string%s// logger message

The following runtime-related fields is extremely expensive and slow, please be careful when using them.

"filename"string%s// source filename of the caller"pathname"string%s// filename with path"lineno"int%d// line number in source code"funcname"string%s// function name of the caller

There are a few pre-defined values for record format.

BasicFormat="%s [%6s] %30s - %s\n name,levelname,time,message"RichFormat="%s [%6s] %d %30s - %d - %s:%s:%d - %s\n name, levelname, seqid, time, filename, funcname, lineno, message"

Time Format

We use the same time format as golang. The default time format is

DefaultTimeFormat="2006-01-02 15:04:05.999999999"// default time format

File Name, Writer, and Sync

The meaning of these fields are obvious. Filename is used to create writer. We also allow the user create a writer by herself and pass it to the logger. Sync describes whether the user would like to use synchronous or asynchronous method to write logs. true value means synchronous method, and false value means asynchronous way. We suggest you use asynchronous way because it causes extremely low extra delay by the logging functions.

Contributors

In alphabetical order

• Cong Ding (ccding)
• Xiang Li (xiang90)
• Zifei Tong (5kg)