Go implementation of systemd Journal's native API for logging

Overview

journald

GoDoc Build Status Go Report Status GoCover

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.

Issues
  • Fedora 33: test failed (v1.0.0)

    Fedora 33: test failed (v1.0.0)

    + cd journald-1.0.0
    + LDFLAGS=' -X github.com/ssgreg/journald/version=1.0.0'
    + GO_TEST_FLAGS='-buildmode pie -compiler gc'
    + GO_TEST_EXT_LD_FLAGS='-Wl,-z,relro -Wl,--as-needed  -Wl,-z,now -specs=/usr/lib/rpm/redhat/redhat-hardened-ld  '
    + go-rpm-integration check -i github.com/ssgreg/journald -b /home/safarov/rpmbuild/BUILD/journald-1.0.0/_build/bin -s /home/safarov/rpmbuild/BUILD/journald-1.0.0/_build -V 1.0.0-1.fc33 -p /home/safarov/rpmbuild/BUILDROOT/golang-github-ssgreg-journald-1.0.0-1.fc33.x86_64 -g /usr/share/gocode -r '.*example.*'
    Testing    in: /home/safarov/rpmbuild/BUILD/journald-1.0.0/_build/src
             PATH: /home/safarov/rpmbuild/BUILD/journald-1.0.0/_build/bin:/home/safarov/.local/bin:/home/safarov/bin:/home/safarov/.local/bin:/home/safarov/bin:/home/safarov/.local/bin:/home/safarov/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin
           GOPATH: /home/safarov/rpmbuild/BUILD/journald-1.0.0/_build:/usr/share/gocode:/usr/share/gocode
      GO111MODULE: off
          command: go test -buildmode pie -compiler gc -ldflags " -X github.com/ssgreg/journald/version=1.0.0 -extldflags '-Wl,-z,relro -Wl,--as-needed  -Wl,-z,now -specs=/usr/lib/rpm/redhat/redhat-hardened-ld  '"
          testing: github.com/ssgreg/journald
    github.com/ssgreg/journald
    
    
    --- FAIL: TestCheckSmallMessage (5.13s)
        send_test.go:79: 
            	Error Trace:	send_test.go:79
            	Error:      	Received unexpected error:
            	            	exit status 1
            	Test:       	TestCheckSmallMessage
    
    opened by sergey-safarov 3
  • Support

    Support "unit" name via jounrnalctl and controlling name in journal logs?

    Hi,

    Is it possible to use the "journal -u test" to get only messages from "test" unit.

    I tried this ( i tried adding the WithName but this doesn't seem to do anything in my case)

    	// Create Logger with ChannelWriter.
    	logger := logf.NewLogger(logf.LevelInfo, writer).WithName("test")
    
    	logger.Info("IAN got cpu info", logf.Int("count", runtime.NumCPU()))
    

    but it didn't work.

    If I look in the logs, it is there but I can't specify the unit.

    Here is the example of the log

    Oct 19 13:08:11 kube01 testme.go.gorun[253735]: IAN got cpu info
    

    Another thing that I am not sure if it's possible to control, but you notice the "testme.go.gorun", is it possible to control that ?

    I am using gorun with a go file.. my go file is called testme.go and obviously running the "gorun".

    I was wondering if we can just replace this with something custom i.e "test"

    Any help really appreciated

    Thanks in advance

    opened by iangregsondev 2
Releases(v1.0.0)
Owner
Grigory Zubankov
Unit Manager @Acronis Go, C++, C
Grigory Zubankov
Gomol is a library for structured, multiple-output logging for Go with extensible logging outputs

gomol Gomol (Go Multi-Output Logger) is an MIT-licensed structured logging library for Go. Gomol grew from a desire to have a structured logging libra

Kristin Davidson 18 Dec 20, 2021
A simple logging module for go, with a rotating file feature and console logging.

A simple logging module for go, with a rotating file feature and console logging. Installation go get github.com/jbrodriguez/mlog Usage Sample usage W

Juan B. Rodriguez 25 Jun 11, 2022
FactorLog is a logging infrastructure for Go that provides numerous logging functions for whatever your style may be

FactorLog FactorLog is a fast logging infrastructure for Go that provides numerous logging functions for whatever your style may be. It could easily b

Kevin Darlington 55 Aug 3, 2022
Package logging implements a logging infrastructure for Go

Golang logging library Package logging implements a logging infrastructure for Go. Its output format is customizable and supports different logging ba

Luke Zhang 0 Nov 10, 2021
Seelog is a native Go logging library that provides flexible asynchronous dispatching, filtering, and formatting.

Seelog Seelog is a powerful and easy-to-learn logging framework that provides functionality for flexible dispatching, filtering, and formatting log me

Seelog project repository 1.6k Aug 1, 2022
Go-metalog - Standard API for structured logging

Metalog is a standard API for structured logging and adapters for its implementa

Kirill 4 Jan 20, 2022
Logging, distilled

What is distillog? distillog aims to offer a minimalistic logging interface that also supports log levels. It takes the stdlib API and only slightly e

Akshay Moghe 28 Aug 8, 2022
Simple and blazing fast lockfree logging library for golang

glg is simple golang logging library Requirement Go 1.11 Installation go get github.com/kpango/glg Example package main import ( "net/http" "time"

Yusuke Kato 168 Jul 27, 2022
Logging library for Golang

GLO Logging library for Golang Inspired by Monolog for PHP, severity levels are identical Install go get github.com/lajosbencz/glo Severity levels Deb

Lajos Bencz 14 Aug 26, 2021
Simple and configurable Logging in Go, with level, formatters and writers

go-log Logging package similar to log4j for the Golang. Support dynamic log level Support customized formatter TextFormatter JSONFormatter Support mul

Guoqiang Chen 12 May 23, 2022
The Simplest and worst logging library ever written

gologger A Simple Easy to use go logger library. Displays Colored log into console in any unix or windows platform. You can even store your logs in fi

Sadlil Rhythom 40 Jul 16, 2022
Structured logging package for Go.

Package log implements a simple structured logging API inspired by Logrus, designed with centralization in mind. Read more on Medium. Handlers apexlog

Apex 1.2k Aug 12, 2022
Simple, configurable and scalable Structured Logging for Go.

log Log is a simple, highly configurable, Structured Logging library Why another logging library? There's allot of great stuff out there, but also tho

Go Playgound 280 Jun 22, 2022
LogVoyage - logging SaaS written in GoLang

No longer maintained, sorry. Completely rewritten v2 is going to be released soon. Please follow http://github.com/logvoyage LogVoyage - fast and simp

null 91 Apr 21, 2022
Structured, composable logging for Go

log15 Package log15 provides an opinionated, simple toolkit for best-practice logging in Go (golang) that is both human and machine readable. It is mo

Alan Shreve 1.1k Aug 16, 2022
Minimalistic logging library for Go.

logger Minimalistic logging library for Go. Blog Post Features: Advanced output filters (package and/or level) Attributes Timers for measuring perform

Azer Ko├žulu 155 Aug 2, 2022
Structured, pluggable logging for Go.

Logrus Logrus is a structured logger for Go (golang), completely API compatible with the standard library logger. Logrus is in maintenance-mode. We wi

Simon Eskildsen 21.1k Aug 12, 2022
Logur is an opinionated collection of logging best practices

Logur is an opinionated collection of logging best practices. Table of Contents Preface Features Installation Usage FAQ Why not just X logger? Why not

Logur 166 Aug 14, 2022
Utilities for slightly better logging in Go (Golang).

logutils logutils is a Go package that augments the standard library "log" package to make logging a bit more modern, without fragmenting the Go ecosy

HashiCorp 324 Jul 12, 2022