go-logging

README

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

• Simple: It supports only necessary operations and easy to get start.
• Fast: Asynchronous logging without runtime-related fields has an extremely low delay of about 800 nano-seconds.

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"
)

func main() {
	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 stdout
SimpleLogger(name string) (*Logger, error)
// with BasicFormat and writing to DefaultFileName
BasicLogger(name string) (*Logger, error)
// with RichFormatand writing to DefaultFileName
RichLogger(name string) (*Logger, error)
// with detailed configuration and writing to file
FileLogger(name string, level Level, format string, timeFormat string, file string, sync bool) (*Logger, error)
// with detailed configuration and writing to a writer
WriterLogger(name string, level Level, format string, timeFormat string, out io.Writer, sync bool) (*Logger, error)
// read configurations from a config file
ConfigLogger(filename string) (*Logger, error)

The meanings of these fields are

name           string        // logger name
level          Level         // record level higher than this will be printed
format         string        // format configuration
timeFormat     string        // format for time
file           string        // file name for logging
out            io.Writer     // writer for logging
sync           bool          // 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(level Level, format string, v ...interface{})
(*Logger) Log(level Level, v ...interface{})
(*Logger) Criticalf(format string, v ...interface{})
(*Logger) Critical(v ...interface{})
(*Logger) Fatalf(format string, v ...interface{})
(*Logger) Fatal(v ...interface{})
(*Logger) Errorf(format string, v ...interface{})
(*Logger) Error(v ...interface{})
(*Logger) Warningf(format string, v ...interface{})
(*Logger) Warning(v ...interface{})
(*Logger) Warnf(format string, v ...interface{})
(*Logger) Warn(v ...interface{})
(*Logger) Infof(format string, v ...interface{})
(*Logger) Info(v ...interface{})
(*Logger) Debugf(format string, v ...interface{})
(*Logger) Debug(v ...interface{})
(*Logger) Notsetf(format string, 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(level Level)            // 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.

CRITICAL     50
FATAL        CRITICAL
ERROR        40
WARNING      30
WARN         WARNING
INFO         20
DEBUG        10
NOTSET       0

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

const BasicFormat = "%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
"thread"        int32      %d      // thread id
"process"       int        %d      // process id
"message"       string     %d      // 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
"thread"        int32      %d      // thread id

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, thread, 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][ccding])
• Xiang Li ([xiangli-cmu][xiangli])
• Zifei Tong ([5kg][5kg]) [ccding]: //github.com/ccding [xiangli]: //github.com/xiangli-cmu [5kg]: //github.com/5kg

TODO List

1. logging server