journald: github.com/ssgreg/journald Index | Files

package journald

import "github.com/ssgreg/journald"

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

Package Files

doc.go send.go sockaddr.go write_msg_go1.9.go

Variables

var (

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

func IsNotExist Uses

func IsNotExist() bool

IsNotExist checks if the system journal is not exist.

func Print Uses

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 Uses

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.

type Journal Uses

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 Uses

func (j *Journal) Close() error

Close closes the underlying connection.

func (*Journal) Print Uses

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 Uses

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 Uses

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 Uses

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

Package journald imports 13 packages (graph) and is imported by 1 packages. Updated 2018-12-27. Refresh now. Tools for package owners.