syslog

Documentation

Overview

Package syslog provides a zapwire preset that ships zap logs as RFC5424 syslog messages (with a JSON message body) to rsyslog, syslog-ng, Vector, Logstash, and other syslog receivers over Unix domain sockets or TCP.

A custom zapcore.Encoder prepends the RFC5424 header — PRI (facility+severity), version, RFC3339 timestamp, hostname, app-name, procid, msgid — to a JSON body encoded by an inner zap JSON encoder, and ships the result through the core Writer via zapwire.Passthrough and a Framer (RFC6587 octet-counting by default, or LF-terminated). The header severity is mapped from the zap level (configurable); all header fields are configurable and sanitized to RFC5424 limits.

Index

• func NewCore(t zapwire.Transport, level zapcore.LevelEnabler, encCfg zapcore.EncoderConfig, ...) (zapcore.Core, *zapwire.Writer, error)
• func NewEncoder(encCfg zapcore.EncoderConfig, opts ...Option) zapcore.Encoder
• func NewWriter(t zapwire.Transport, opts ...Option) (*zapwire.Writer, error)
• type Facility
• type Framer
  • func NewFramer(f Framing) Framer
  • func (f Framer) Frame(dst []byte, payloads [][]byte) ([]byte, error)
• type Framing
• type Option
  • func WithAppName(a string) Option
  • func WithBOM(on bool) Option
  • func WithFacility(f Facility) Option
  • func WithFraming(f Framing) Option
  • func WithHostname(h string) Option
  • func WithMsgID(m string) Option
  • func WithProcID(p string) Option
  • func WithSeverityMapper(fn func(zapcore.Level) Severity) Option
  • func WithZapwireOptions(opts ...zapwire.Option) Option
• type Severity

Functions

func NewCore

func NewCore(
	t zapwire.Transport,
	level zapcore.LevelEnabler,
	encCfg zapcore.EncoderConfig,
	opts ...Option,
) (zapcore.Core, *zapwire.Writer, error)

NewCore wires NewEncoder + NewWriter into a ready core plus its writer, which the caller must Close. A single opts list feeds both ends (each option sets only the fields it owns).

Parameters:

• t: transport to ship messages over; must be non-nil
• level: minimum level an entry must meet to be encoded
• encCfg: zap JSON encoder config for the message body
• opts: syslog options

Returns:

• zapcore.Core: an RFC5424-encoding core writing into the syslog writer
• *zapwire.Writer: the underlying writer; the caller must Close it
• error: a non-nil error if the writer cannot be built

func NewEncoder

func NewEncoder(encCfg zapcore.EncoderConfig, opts ...Option) zapcore.Encoder

NewEncoder builds the RFC5424 zapcore.Encoder. It copies encCfg (a value parameter, so the caller's config is untouched) and sets SkipLineEnding=true so the inner JSON body carries no trailing terminator (spec §3.1). Pair it with NewWriter (Passthrough + the syslog Framer) to build a core yourself, or use NewCore.

Parameters:

• encCfg: zap JSON encoder config for the message body (its LineEnding is overridden)
• opts: syslog options (WithFacility, WithHostname, WithSeverityMapper, WithBOM, …)

Returns:

• zapcore.Encoder: the RFC5424 encoder

func NewWriter

func NewWriter(t zapwire.Transport, opts ...Option) (*zapwire.Writer, error)

NewWriter builds a zapwire.Writer for the syslog path: Passthrough + the syslog Framer over t. Only WithFraming and WithZapwireOptions take effect here; header/severity/BOM options are no-ops (supply those to NewEncoder for a BYO-core path). Pair with NewEncoder to build a core yourself (e.g. inside zapcore.NewTee).

Parameters:

• t: transport to ship messages over; must be non-nil
• opts: syslog options (WithFraming, WithZapwireOptions take effect)

Returns:

• *zapwire.Writer: the writer; the caller owns it and must Close it
• error: a non-nil error from the underlying zapwire.New

Types

type Facility

type Facility int

Facility is a syslog facility (RFC5424 §6.2.1), valid range 0..23.

const (
	KERN Facility = iota
	USER
	MAIL
	DAEMON
	AUTH
	SYSLOG
	LPR
	NEWS
	UUCP
	CRON
	AUTHPRIV
	FTP
	NTP
	LOGAUDIT
	LOGALERT
	CLOCK
	LOCAL0
	LOCAL1
	LOCAL2
	LOCAL3
	LOCAL4
	LOCAL5
	LOCAL6
	LOCAL7
)

Syslog facilities. PRI = int(facility)*8 + int(severity).

type Framer

type Framer struct {
	// contains filtered or unexported fields
}

Framer wraps each per-entry SYSLOG-MSG payload for an octet stream. It implements zapwire.Framer.

func NewFramer

func NewFramer(f Framing) Framer

NewFramer returns a Framer using f (the zero Framing value, OctetCounting, is the default).

Parameters:

• f: the framing method (OctetCounting or LFTerminated)

Returns:

• Framer: a framer for the chosen method

func (Framer) Frame

func (f Framer) Frame(dst []byte, payloads [][]byte) ([]byte, error)

Frame appends each payload to dst, framed per the configured method. MSG-LEN in octet-counting mode is the byte length of the payload. It implements zapwire.Framer.

Parameters:

• dst: buffer to append to; may be nil or a pooled slice to reuse
• payloads: per-entry SYSLOG-MSG payloads (one in sync mode, N when batched)

Returns:

• []byte: dst extended with the framed payloads
• error: always nil (kept for the zapwire.Framer contract)

type Framing

type Framing int

Framing selects the RFC 6587 stream-framing method for syslog over a byte stream.

const (
	// OctetCounting prefixes each message with its byte length: "MSG-LEN SP SYSLOG-MSG"
	// (RFC 6587 §3.4.1). The default — unambiguous and robust to any payload byte.
	OctetCounting Framing = iota
	// LFTerminated terminates each message with a single '\n' (RFC 6587 §3.4.2,
	// non-transparent framing). Simpler, but safe only when the message contains no LF.
	LFTerminated
)

type Option

type Option func(*options)

Option configures a syslog preset. Header/severity/BOM options affect NewEncoder and NewCore; WithFraming and WithZapwireOptions affect NewWriter and NewCore.

func WithAppName

func WithAppName(a string) Option

WithAppName sets the APP-NAME field (default the process name); empty → "-".

func WithBOM

func WithBOM(on bool) Option

WithBOM prepends a UTF-8 BOM to the MSG (strict RFC5424 MSG-UTF8). Default off — a leading BOM trips naive JSON consumers.

func WithFacility

func WithFacility(f Facility) Option

WithFacility sets the syslog facility (default LOCAL0). An out-of-range value falls back to LOCAL0 at construction.

func WithFraming

func WithFraming(f Framing) Option

WithFraming selects the stream framing (default OctetCounting).

func WithHostname

func WithHostname(h string) Option

WithHostname sets the HOSTNAME field (default os.Hostname()); empty → "-".

func WithMsgID

func WithMsgID(m string) Option

WithMsgID sets the MSGID field (default "-").

func WithProcID

func WithProcID(p string) Option

WithProcID sets the PROCID field (default the OS pid); empty → "-".

func WithSeverityMapper

func WithSeverityMapper(fn func(zapcore.Level) Severity) Option

WithSeverityMapper overrides the zap-level → syslog-severity mapping. The result is clamped to 0..7 per entry. A nil mapper is ignored (the default is kept).

func WithZapwireOptions

func WithZapwireOptions(opts ...zapwire.Option) Option

WithZapwireOptions forwards core zapwire options (mode, buffer, timeouts, …).

type Severity

type Severity int

Severity is a syslog severity (RFC5424 §6.2.1), valid range 0..7.

const (
	Emergency Severity = iota
	Alert
	Critical
	Error
	Warning
	Notice
	Informational
	Debug
)

Syslog severities, most-to-least severe.