journald

README

journald

Package journald offers Go implementation of systemd Journal's native API for logging. Key features are:

• based on a connection-less socket
• work with messages of any size and type
• client can use any number of separate sockets

Installation

Install the package with:

go get github.com/ssgreg/journald

Usage: The Best Way

The Best Way to use structured logs (systemd Journal, etc.) is logf - the fast, asynchronous, structured logger in Go with zero allocation count and it's journald driver logfjournald. This driver uses journald package. The following example creates the new logf logger with logfjournald appender.

package main

import (
    "runtime"

    "github.com/ssgreg/logf"
    "github.com/ssgreg/logfjournald"
)

func main() {
    // Create journald Appender with default journald Encoder.
    appender, appenderClose := logfjournald.NewAppender(logfjournald.NewEncoder.Default())
    defer appenderClose()

    // Create ChannelWriter with journald Encoder.
    writer, writerClose := logf.NewChannelWriter(logf.ChannelWriterConfig{
        Appender: appender,
    })
    defer writerClose()

    // Create Logger with ChannelWriter.
    logger := logf.NewLogger(logf.LevelInfo, writer)

    logger.Info("got cpu info", logf.Int("count", runtime.NumCPU()))
}

The JSON representation of the journal entry this generates:

{
  "TS": "2018-11-01T07:25:18Z",
  "PRIORITY": "6",
  "LEVEL": "info",
  "MESSAGE": "got cpu info",
  "COUNT": "4",
}

Usage: AS-IS

Let's look at what the journald provides as Go APIs for logging:

package main

import (
    "github.com/ssgreg/journald"
)

func main() {
    journald.Print(journald.PriorityInfo, "Hello World!")
}

The JSON representation of the journal entry this generates:

{
    "PRIORITY": "6",
    "MESSAGE":  "Hello World!",
    "_PID":     "3965",
    "_COMM":    "simple",
    "...":      "..."
}

The primary reason for using the Journal's native logging APIs is not just plain logs: it is to allow passing additional structured log messages from the program into the journal. This additional log data may the be used to search the journal for, is available for consumption for other programs, and might help the administrator to track down issues beyond what is expressed in the human readable message text. Here's an example how to do that with journals.Send:

package main

import (
    "os"
    "runtime"

    "github.com/ssgreg/journald"
)

func main() {
    journald.Send("Hello World!", journald.PriorityInfo, map[string]interface{}{
        "HOME":        os.Getenv("HOME"),
        "TERM":        os.Getenv("TERM"),
        "N_GOROUTINE": runtime.NumGoroutine(),
        "N_CPUS":      runtime.NumCPU(),
        "TRACE":       runtime.ReadTrace(),
    })
}

This will write a log message to the journal much like the earlier examples. However, this times a few additional, structured fields are attached:

{
    "PRIORITY":     "6",
    "MESSAGE":      "Hello World!",
    "HOME":         "/root",
    "TERM":         "xterm",
    "N_GOROUTINE":  "2",
    "N_CPUS":       "4",
    "TRACE":        [103,111,32,49,46,56,32,116,114,97,99,101,0,0,0,0],
    "_PID":         "4037",
    "_COMM":        "send",
    "...":          "..."
}

Our structured message includes seven fields. The first two we passed are well-known fields:

1. MESSAGE= is the actual human readable message part of the structured message.
2. PRIORITY= is the numeric message priority value as known from BSD syslog formatted as an integer string.

Applications may relatively freely define additional fields as they see fit (we defined four pretty arbitrary ones in our example). A complete list of the currently well-known fields is available here.

Thanks to http://0pointer.de/blog/ for the inspiration.

Documentation

Overview

Package journald offers Go implementation of systemd Journal's native API for logging. Key features are:

• based on connection-less socket
• work with messages of any size and type
• client can use any number of separation sockets

Let's look at what the journald provides as Go APIs for logging:

package main

import (
	"github.com/ssgreg/journald"
)

func main() {
	journald.Print(journald.PriorityInfo, "Hello World!")
}

The JSON representation of the journal entry this generates:

{
	"PRIORITY": "6",
	"MESSAGE": "Hello World!",
	"_PID": "3965",
	"_COMM": "simple",
	...
}

The primary reason for using the Journal's native logging APIs is a not just the source code location however: it is to allow passing additional structured log messages from the program into the journal. This additional log data may the be used to search the journal for, is available for consumption for other programs, and might help the administrator to track down issues beyond what is expressed in the human readable message text. Here's and example how to do that with journals.Send:

package main

import (
	"os"
	"runtime"

	"github.com/ssgreg/journald"
)

func main() {
	journald.Send("Hello World!", journald.PriorityInfo, map[string]interface{}{
		"HOME":        os.Getenv("HOME"),
		"TERM":        os.Getenv("TERM"),
		"N_GOROUTINE": runtime.NumGoroutine(),
		"N_CPUS":      runtime.NumCPU(),
		"TRACE":       runtime.ReadTrace(),
	})
}

This will write a log message to the journal much like the earlier examples. However, this times a few additional, structured fields are attached:

{
	"PRIORITY": "6",
	"MESSAGE": "Hello World!",
	"HOME": "/root",
	"TERM": "xterm",
	"N_GOROUTINE": "2",
	"N_CPUS": "4",
	"TRACE": [103,111,32,49,46,56,32,116,114,97,99,101,0,0,0,0],
	"_PID": "4037",
	"_COMM": "send",
	...
}

Our structured message includes six fields. The first thow we passed are well-known fields: 1. MESSAGE= is the actual human readable message part of the structured message. 2. PRIORITY= is the numeric message priority value as known from BSD syslog formatted as an integer string.

Applications may relatively freely define additional fields as they see fit (we defined four pretty arbitrary ones in our example). A complete list of the currently well-known fields is available here: https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html

For more details visit https://github.com/ssgreg/journald-send

Thanks to http://0pointer.de/blog/ for the inspiration.

Index

• Variables
• func IsNotExist() bool
• func Print(p Priority, format string, a ...interface{}) error
• func Send(msg string, p Priority, fields map[string]interface{}) error
• type Journal
  • func (j *Journal) Close() error
  • func (j *Journal) Print(p Priority, format string, a ...interface{}) error
  • func (j *Journal) Send(msg string, p Priority, fields map[string]interface{}) error
  • func (j *Journal) WriteMsg(data []byte) error
• type Priority

Variables

var (

	// DefaultJournal is the default journal and is used by Print and Send.
	DefaultJournal = &Journal{}
)

Functions

func IsNotExist

func IsNotExist() bool

IsNotExist checks if the system journal is not exist.

func Print

func Print(p Priority, format string, a ...interface{}) error

Print may be used to submit simple, plain text log entries to the system journal. The first argument is a priority value. This is followed by a format string and its parameters.

Print is a wrapper around DefaultJournal.Print.

func Send

func Send(msg string, p Priority, fields map[string]interface{}) error

Send may be used to submit structured log entries to the system journal. It takes a map of fields with names and values.

The field names must be in uppercase and consist only of characters, numbers and underscores, and may not begin with an underscore. All fields that do not follow this syntax will be ignored. The value can be of any size and format. A variable may be assigned more than one value per entry.

A number of well known fields are defined, see: http://0pointer.de/public/systemd-man/systemd.journal-fields.html

Send is a wrapper around DefaultJournal.Send.

Types

type Journal

type Journal struct {

	// NormalizeFieldNameFn is a hook that allows client to change
	// fields names just before sending if set.
	//
	// Default value is nil.
	// string.ToUpper is a good example of the hook usage.
	NormalizeFieldNameFn func(string) string

	// TestModeEnabled allows Journal to do nothing. All messages are
	// discarding.
	TestModeEnabled bool
	// contains filtered or unexported fields
}

Journal keeps a connection to the system journal

func (*Journal) Close

func (j *Journal) Close() error

Close closes the underlying connection.

func (*Journal) Print

func (j *Journal) Print(p Priority, format string, a ...interface{}) error

Print may be used to submit simple, plain text log entries to the system journal. The first argument is a priority value. This is followed by a format string and its parameters.

func (*Journal) Send

func (j *Journal) Send(msg string, p Priority, fields map[string]interface{}) error

Send may be used to submit structured log entries to the system journal. It takes a map of fields with names and values.

The field names must be in uppercase and consist only of characters, numbers and underscores, and may not begin with an underscore. All fields that do not follow this syntax will be ignored. The value can be of any size and format. A variable may be assigned more than one value per entry.

A number of well known fields are defined, see: http://0pointer.de/public/systemd-man/systemd.journal-fields.html

func (*Journal) WriteMsg

func (j *Journal) WriteMsg(data []byte) error

WriteMsg writes the given bytes to the systemd journal's socket. The caller is in charge of correct data format.

type Priority

type Priority int

Priority is the numeric message priority value as known from BSD syslog

const (
	PriorityEmerg Priority = iota
	PriorityAlert
	PriorityCrit
	PriorityErr
	PriorityWarning
	PriorityNotice
	PriorityInfo
	PriorityDebug
)

Priority values