Skip to content

Latest commit

 

History

History
228 lines (160 loc) · 5.26 KB

README.md

File metadata and controls

228 lines (160 loc) · 5.26 KB
Raw

Go-Log

Build Status

A logger, for Go!

It's sort of log and code.google.com/p/log4go compatible, so in most cases can be used without any code changes.

Breaking change

go-log was inconsistent with the default Go 'log' package, and log.Fatal calls didn't trigger an os.Exit(1).

This has been fixed in the current release of go-log, which might break backwards compatibility.

You can disable the fix by setting ExitOnFatal to false, e.g.

log.Logger().ExitOnFatal = false

Getting started

Install go-log:

go get github.com/ian-kent/go-log/log

Use the logger in your application:

import(
  "github.com/ian-kent/go-log/log"
)

// Pass a log message and arguments directly
log.Debug("Example log message: %s", "example arg")

// Pass a function which returns a log message and arguments
log.Debug(func(){[]interface{}{"Example log message: %s", "example arg"}})
log.Debug(func(i ...interface{}){[]interface{}{"Example log message: %s", "example arg"}})

You can also get the logger instance:

logger := log.Logger()
logger.Debug("Yey!")

Or get a named logger instance:

logger := log.Logger("foo.bar")

Log levels

The default log level is DEBUG.

To get the current log level:

level := logger.Level()

Or to set the log level:

// From a LogLevel
logger.SetLevel(levels.TRACE)

// From a string
logger.SetLevel(log.Stol("TRACE"))

Log appenders

The default log appender is appenders.Console(), which logs the raw message to STDOUT.

To get the current log appender:

appender := logger.Appender()

If the appender is nil, the parent loggers appender will be used instead.

If the appender eventually resolves to nil, log data will be silently dropped.

You can set the log appender:

logger.SetAppender(appenders.Console())

Rolling file appender

Similar to log4j's rolling file appender, you can use

// Append to (or create) file
logger.SetAppender(appenders.RollingFile("filename.log", true))

// Truncate (or create) file
logger.SetAppender(appenders.RollingFile("filename.log", false))

You can also control the number of log files which are kept:

r := appenders.RollingFile("filename.log", true)
r.MaxBackupIndex = 2 // filename.log, filename.log.1, filename.log.2

And the maximum log file size (in bytes):

r := appenders.RollingFile("filename.log", true)
r.MaxFileSize = 1024 // 1KB, defaults to 100MB

Fluentd appender

The fluentd appender lets you write log data directly to fluentd:

logger.SetAppender(appenders.Fluentd(fluent.Config{}))

It uses github.com/t-k/fluent-logger-golang.

The tag is currently fixed to 'go-log', and the data structure sent to fluentd is simple:

{
  message: "<output from layout>"
}

Layouts

Each appender has its own layout. This allows the log data to be transformed as it is written to the appender.

The default layout is layout.Basic(), which passes the log message and its arguments through fmt.Sprintf.

To get the current log appender layout:

appender := logger.Appender()
layout := appender.Layout()

To set the log appender layout:

appender.SetLayout(layout.Basic())

You can also use layout.Pattern(pattern string), which accepts a pattern format similar to log4j:

Code Description
%c The package the log statement is in
%C Currently also the package the log statement is in
%d The current date/time, using time.Now().String()
%F The filename the log statement is in
%l The location of the log statement, e.g. package/somefile.go:12
%L The line number the log statement is on
%m The log message and its arguments formatted with fmt.Sprintf
%n A new-line character
%p Priority - the log level
%r ms since logger was created

Logger inheritance

Loggers are namespaced with a ., following similar rules to Log4j.

If you create a logger named foo, it will automatically inherit the log settings (levels and appender) of the root logger.

If you then create a logger named foo.bar, it will inherit the log settings of foo, which in turn inherits the log settings from the root logger.

You can break this by setting the log level or setting an appender on a child logger, e.g.:

logger := log.Logger("foo.bar")
logger.SetLevel(levels.TRACE)
logger.SetAppender(appenders.Console())

If you then created a logger named foo.bar.qux, it would inherit the trace level and console appender of the foo.bar logger.

Roadmap

  • log4j configuration support
    • .properties
    • .xml
    • .json
  • layouts
    • fixmes/todos in pattern layout
  • appenders
    • add socket appender
    • fixmes/todos and tests for fluentd appender
  • optimise logger creation
    • collapse loggers when parent namespace is unused
    • reorganise loggers when new child tree is created
  • add godoc documentation

Contributing

Before submitting a pull request:

  • Format your code: go fmt ./...
  • Make sure tests pass: go test ./...

Licence

Copyright ©‎ 2014, Ian Kent (http://www.iankent.eu).

Released under MIT license, see LICENSE for details.