Documentation
¶
Overview ¶
Package syslog forwards log lines to a remote syslog server over UDP or TCP. It is a self-contained leaf (stdlib only, no Culvert coupling) extracted from the flat package main per ADR-0002. The structured-entry writers take `any` (the entry is only JSON-marshalled) so the forwarder needn't know the concrete audit/request-log struct types.
Two formats are supported:
RFC 3164 (BSD syslog) — legacy, accepted everywhere. RFC 5424 (IETF syslog) — modern SIEMs prefer this for structured data, microsecond timestamps, and proper UTF-8 BOM handling.
Priority: facility=1 (user-level), severity=6 (informational) → PRI=14. Audit events are sent at severity=5 (notice) → PRI=13.
Delivery is ASYNCHRONOUS: senders format the line and enqueue it on a bounded channel; a single drain goroutine (started by NewWriter) owns the connection, the reconnect/backoff state machine, and every network write. The request path therefore never takes the connection mutex and never blocks on a socket — a slow or wedged TCP collector costs the caller a channel send, with overflow counted in Drops rather than propagated as proxy latency. Ordering is preserved (one drain goroutine).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer forwards log lines to a remote syslog server over UDP or TCP.
A Writer built by NewWriter delivers asynchronously via queue/drainLoop; a zero-value Writer (tests build these directly) has a nil queue and falls back to the synchronous writeMsg path, so the delivery state machine stays directly testable.
func NewWriter ¶
NewWriter dials the syslog server and returns a ready Writer. format selects the wire format: "rfc3164" (default) or "rfc5424".
func (*Writer) Close ¶
Close stops the drain goroutine (flushing already-queued lines within flushTimeout) and releases the connection. Idempotent; concurrent sends after Close count as drops. On an async Writer the connection is owned and released by the drain goroutine; Close waits up to closeWait for it — if a wedged collector outlasts even that, Close returns and the goroutine releases the conn when its write deadline fires.
func (*Writer) Drops ¶ added in v1.0.39
Drops reports the number of messages dropped because the collector was unreachable or not draining, the delivery queue overflowed, or the Writer was already closed. Monotonic per Writer; delivery is otherwise silent-best-effort, so this is the only loss signal.
func (*Writer) WriteAudit ¶
WriteAudit sends a structured audit entry as a JSON syslog message at severity=5 (notice), which most SIEMs map to a security-relevant priority. The entry is only JSON-marshalled, so any serializable value is accepted.
func (*Writer) WriteRequest ¶
WriteRequest sends a structured request-log entry as a JSON syslog message at PRI=14 (facility=1 user-level, severity=6 informational).
Source Files