journald

README

journald-send

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
• client can use any number of separation connections

Example

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

package main

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

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 a 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 and example how to do that with journals.Send:

package main
import (
    "os"
    "runtime"
    "strconv"
    "github.com/ssgreg/journald-send"
)

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

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",
    "_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.

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
• 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-send"
)

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"
	"strconv"

	"github.com/ssgreg/journald-send"
)

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

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",
	"_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 IsNotExists() bool
• func Print(p Priority, format string, a ...interface{}) error
• func Send(msg string, p Priority, fields map[string]string) 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]string) error
• type Priority

Variables

var (

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

Functions

func IsNotExists

func IsNotExists() bool

IsNotExists 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]string) 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 {
	// contains filtered or unexported fields
}

Journal TODO

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]string) 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