journald

README

journald

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

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

Installation

Install the package with:

go get github.com/ssgreg/journald

Usage

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 connect-less socket
• work with messages of any size and type
• client can use any number of separation connections

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
• 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
	// 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

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