syslog

Documentation

Overview

Package syslog contains functionality for using slog with Unix syslog servers, using the syslog package. It provides a Handler that wraps another slog.Handler. The Handler will ensure that the embedded slog.Handler writes to the syslog at the correct log level.

The NewJSONHandler and NewTextHandler functions can be used to setup logging using slog.JSONHandler or slog.TextHandler respectively. These can be used as follows:

package main

import (
	"log/slog"

	"gitlab.com/slxh/go/slogutil/syslog"
)

func main() {
	h, err := syslog.NewTextHandler(nil, nil)
	if err != nil {
		panic(err)
	}

	slog.SetDefault(slog.New(h))
	slog.Info("Hello!") // written to syslog
}

This will be shown in your syslog as something similar to the following:

aug 09 14:16:21 hostname example[542251]: time=2023-08-09T14:16:21.173+02:00 level=INFO msg=Hello!

Use NewHandler to use a custom handler for formatting, for example:

h, err := syslog.NewHandler(nil, func(writer io.Writer) slog.Handler {
	return &MyCustomHandler{}
})

Index

• Constants
• Variables
• type Handler
  • func NewHandler(opts *WriterOptions, handlerFunc func(io.Writer) slog.Handler) (*Handler, error)
  • func NewJSONHandler(opts *WriterOptions, slogOpts *slog.HandlerOptions) (*Handler, error)
  • func NewTextHandler(opts *WriterOptions, slogOpts *slog.HandlerOptions) (*Handler, error)
  • func (s *Handler) Enabled(ctx context.Context, level slog.Level) bool
  • func (s *Handler) Handle(ctx context.Context, record slog.Record) (err error)
  • func (s *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (s *Handler) WithGroup(name string) slog.Handler
• type Writer
  • func NewWriter(opts *WriterOptions) (*Writer, error)
  • func (s *Writer) WithLevel(level slog.Level, fn func())
  • func (s *Writer) Write(p []byte) (int, error)
  • func (s *Writer) WriteLevel(level slog.Level, p []byte) error
• type WriterOptions

Constants

const (
	LevelEmerg   = slog.LevelError + 3
	LevelAlert   = slog.LevelError + 2
	LevelCrit    = slog.LevelError + 1
	LevelErr     = slog.LevelError
	LevelWarning = slog.LevelWarn
	LevelNotice  = slog.LevelInfo + 1
	LevelInfo    = slog.LevelInfo
	LevelDebug   = slog.LevelDebug
)

These slog.Level values can be used when logging to the syslog. It is generally advisable to limit usage to the levels defined in slog, as this will be correctly annotated in log contents.

const (
	FacilityKern     = syslog.LOG_KERN
	FacilityUser     = syslog.LOG_USER
	FacilityMail     = syslog.LOG_MAIL
	FacilityDaemon   = syslog.LOG_DAEMON
	FacilityAuth     = syslog.LOG_AUTH
	FacilitySyslog   = syslog.LOG_SYSLOG
	FacilityLPR      = syslog.LOG_LPR
	FacilityNews     = syslog.LOG_NEWS
	FacilityUUCP     = syslog.LOG_UUCP
	FacilityCron     = syslog.LOG_CRON
	FacilityAuthPriv = syslog.LOG_AUTHPRIV
	FacilityFTP      = syslog.LOG_FTP
	FacilityLocal0   = syslog.LOG_LOCAL0
	FacilityLocal1   = syslog.LOG_LOCAL1
	FacilityLocal2   = syslog.LOG_LOCAL2
	FacilityLocal3   = syslog.LOG_LOCAL3
	FacilityLocal4   = syslog.LOG_LOCAL4
	FacilityLocal5   = syslog.LOG_LOCAL5
	FacilityLocal6   = syslog.LOG_LOCAL6
	FacilityLocal7   = syslog.LOG_LOCAL7
)

Facilities that can be logged to. This describes the type of message that is logged. The facility may determine how the message is handled, and where it is stored.

Variables

var DefaultWriterOptions = &WriterOptions{
	Facility: syslog.LOG_DAEMON,
}

DefaultWriterOptions contains the default WriterOptions that are used when a nil parameter is passed to the Writer initialization.

Types

type Handler

type Handler struct {
	Handler slog.Handler
	Writer  *Writer
}

Handler implements a slog.Handler that logs to syslog. It embeds a slog.Handler to perform the formatting of messages, and a Writer that the slog.Handler writes to.

func NewHandler

func NewHandler(opts *WriterOptions, handlerFunc func(io.Writer) slog.Handler) (*Handler, error)

NewHandler initializes a Handler based on another handler. The other handler must be created by the handlerFunc parameter, which is called immediately.

func NewJSONHandler

func NewJSONHandler(opts *WriterOptions, slogOpts *slog.HandlerOptions) (*Handler, error)

NewJSONHandler creates a Handler that logs messages to the syslog using slog.JSONHandler. If opts is `nil`, DefaultWriterOptions is used. See slog.NewJSONHandler for details on the JSONHandler.

func NewTextHandler

func NewTextHandler(opts *WriterOptions, slogOpts *slog.HandlerOptions) (*Handler, error)

NewTextHandler creates a Handler that logs messages to the syslog using slog.TextHandler. If opts is `nil`, DefaultWriterOptions is used. See slog.NewTextHandler for details on the TextHandler.

func (*Handler) Enabled

func (s *Handler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level.

func (*Handler) Handle

func (s *Handler) Handle(ctx context.Context, record slog.Record) (err error)

Handle calls the Handle function of the underlying slog.Handler with the log level communicated to the embedded Writer.

func (*Handler) WithAttrs

func (s *Handler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new slog.Handler with the given attributes set.

func (*Handler) WithGroup

func (s *Handler) WithGroup(name string) slog.Handler

WithGroup returns a new slog.Handler with the given group appended to the existing groups.

type Writer

type Writer struct {
	*syslog.Writer
	// contains filtered or unexported fields
}

Writer is an extended syslog.Writer with support for slog.Level.

func NewWriter

func NewWriter(opts *WriterOptions) (*Writer, error)

NewWriter initializes and connects to the log server defined by the given options. If the given options are `nil`, DefaultWriterOptions are used.

func (*Writer) WithLevel

func (s *Writer) WithLevel(level slog.Level, fn func())

WithLevel runs the given function while the default log level is set to the given value. The log level is restored to the default value afterward.

func (*Writer) Write

func (s *Writer) Write(p []byte) (int, error)

Write data to the syslog using the configured log level. When called in [WithLevel], this function uses the level defined in that function.

func (*Writer) WriteLevel

func (s *Writer) WriteLevel(level slog.Level, p []byte) error

WriteLevel writes a message to the syslog with the given level.

type WriterOptions

type WriterOptions struct {
	// Tag contains the syslog tag (log prefix) used by the Writer.
	// If left empty, os.Args[0] is used.
	Tag string

	// Network contains the network to use for connecting to a remote server.
	// If left empty, the Writer will connect to the local syslog server.
	Network string

	// Address contains the remote address of the remote server.
	Address string

	// Facility contains the facility of the Writer.
	// This defaults to FacilityKern.
	Facility syslog.Priority

	// Level contains the default level of the Writer.
	// This defaults to slog.LevelInfo.
	Level slog.Level
}

WriterOptions contains options for the syslog Writer.