Using The Log Package In Go

Nov 5, 2013


Linux is unique to Windows in many ways, and writing programs in Linux is no exception. The use of standard out, standard err and null devices is not only a good idea but it’s the law. If your programs are going to be logging information, it is best to follow the destination conventions. This way your programs will work with all of the Mac/Linux tooling and hosted environments.

Go has a package in the standard library called log and a type called logger. Using the log package will give you everything you need to be a good citizen. You will be able to write to all the standard devices, custom files or any destination that support the io.Writer interface.

I have provided a really simple sample that will get you started with using logger:

package main

import (
    "io"
    "io/ioutil"
    "log"
    "os"
)

var (
    Trace   *log.Logger
    Info    *log.Logger
    Warning *log.Logger
    Error   *log.Logger
)

func Init(
    traceHandle io.Writer,
    infoHandle io.Writer,
    warningHandle io.Writer,
    errorHandle io.Writer) {

    Trace = log.New(traceHandle,
        "TRACE: ",
        log.Ldate|log.Ltime|log.Lshortfile)

    Info = log.New(infoHandle,
        "INFO: ",
        log.Ldate|log.Ltime|log.Lshortfile)

    Warning = log.New(warningHandle,
        "WARNING: ",
        log.Ldate|log.Ltime|log.Lshortfile)

    Error = log.New(errorHandle,
        "ERROR: ",
        log.Ldate|log.Ltime|log.Lshortfile)
}

func main() {
    Init(ioutil.Discard, os.Stdout, os.Stdout, os.Stderr)

    Trace.Println("I have something standard to say")
    Info.Println("Special Information")
    Warning.Println("There is something you need to know about")
    Error.Println("Something has failed")
}

When you run this program you will get the follow output:

INFO: 2013/11/05 18:11:01 main.go:44: Special Information
WARNING: 2013/11/05 18:11:01 main.go:45: There is something you need to know about
ERROR: 2013/11/05 18:11:01 main.go:46: Something has failed

You will notice that Trace logging is not being displayed. Let’s look at the code to find out why.

Look at the Trace logger pieces:

var Trace *log.Logger

Trace = log.New(traceHandle,
    "TRACE: ",
    log.Ldate|log.Ltime|log.Lshortfile)

Init(ioutil.Discard, os.Stdout, os.Stdout, os.Stderr)

Trace.Println("I have something standard to say")

The code creates a package level variable called Trace which is a pointer to a log.Logger object. Then inside the Init function, a new log.Logger object is created. The parameters to the log.New function are as follows:

func New(out io.Writer, prefix string, flag int) *Logger

out:    The out variable sets the destination to which log data will be written.
prefix: The prefix appears at the beginning of each generated log line.
flags:  The flag argument defines the logging properties.

Flags:
const (
// Bits or’ed together to control what’s printed. There is no control over the
// order they appear (the order listed here) or the format they present (as
// described in the comments). A colon appears after these items:
// 2009/01/23 01:23:23.123123 /a/b/c/d.go:23: message
Ldate = 1 << iota // the date: 2009/01/23
Ltime             // the time: 01:23:23
Lmicroseconds     // microsecond resolution: 01:23:23.123123. assumes Ltime.
Llongfile         // full file name and line number: /a/b/c/d.go:23
Lshortfile        // final file name element and line number: d.go:23. overrides Llongfile
LstdFlags = Ldate | Ltime // initial values for the standard logger
)

In this sample program the destination for Trace is ioutil.Discard. This is a null device where all write calls succeed without doing anything. Therefore when you write using Trace, nothing appears in the terminal window.

Look at Info:

var Info *log.Logger

Info = log.New(infoHandle,
    "INFO: ",
    log.Ldate|log.Ltime|log.Lshortfile)

Init(ioutil.Discard, os.Stdout, os.Stdout, os.Stderr)

Info.Println("Special Information")

For Info os.Stdout is passed into Init for the infoHandle. This means when you write using Info, the message will appear on the terminal window, via standard out.

Last, look at Error:

var Error *log.Logger

Error = log.New(errorHandle,
    "INFO: ",
    log.Ldate|log.Ltime|log.Lshortfile)

Init(ioutil.Discard, os.Stdout, os.Stdout, os.Stderr)

Error.Println("Special Information")

This time os.Stderr is passed into Init for the errorHandle. This means when you write using Error, the message will appear on the terminal window, via standard error. However, passing these messages to os.Stderr allows other applications running your program to know an error has occurred.

Since any destination that support the io.Writer interface is accepted, you can create and use files:

file, err := os.OpenFile("file.txt", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
if err != nil {
    log.Fatalln("Failed to open log file", output, ":", err)
}

MyFile = log.New(file,
    "PREFIX: ",
    log.Ldate|log.Ltime|log.Lshortfile)

In the sample code, a file is opened and then passed into the log.New call. Now when you use MyFile to write, the writes go to file.txt.

You can also have the logger write to multiple destinations at the same time.

file, err := os.OpenFile("file.txt", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
if err != nil {
    log.Fatalln("Failed to open log file", output, ":", err)
}

multi := io.MultiWriter(file, os.Stdout)

MyFile := log.New(multi,
    "PREFIX: ",
    log.Ldate|log.Ltime|log.Lshortfile)

Here writes are going to the file and to standard out.

Notice the use of log.Fatalln in the handling of any error with OpenFile. The log package provides an initial logger that can be configured as well. Here is a sample program using log with the standard configuration:

package main

import (
    "log"
)

func main() {
    log.Println("Hello World")
}

Here is the output:

2013/11/05 18:42:26 Hello World

If you want to remove the formatting or change it, you can use the log.SetFlags function:

package main

import (
    "log"
)

func main() {
    log.SetFlags(0)
    log.Println("Hello World")
}

Here is the output:

Hello World

Now all the formatting has been removed. If you want to send the output to a different destination use the log.SetOutput:

package main

import (
    "io/ioutil"
    "log"
)

func main() {
    log.SetOutput(ioutil.Discard)
    log.Println("Hello World")
}

Now nothing will display on the terminal window. You can use any destination that support the io.Writer interface.

Based on this example I wrote a new logging package for all my programs:

go get github.com/goinggo/tracelog

I wish I knew about log and loggers when I started writing Go programs. Expect to see a lot more of the log package from me in the future.


Go Training

We have taught Go to thousands of developers all around the world since 2014. There is no other company that has been doing it longer and our material has proven to help jump start developers 6 to 12 months ahead of their knowledge of Go. We know what knowledge developers need in order to be productive and efficient when writing software in Go.

Our Go, Web and Data Science classes are perfect for both experienced and beginning engineers. We start every class from the beginning and get very detailed about the internals, mechanics, specification, guidelines, best practices and design philosophies. We cover a lot about "if performance matters" with a focus on mechanical sympathy, data oriented design, decoupling and writing production software.

Learn More

To learn about Corporate training events, options and special pricing please contact:

William Kennedy
ArdanLabs (www.ardanlabs.com)
bill@ardanlabs.com