README
¶
journal
Native Go output to the systemd journal socket.
Documentation
¶
Index ¶
- Constants
- func AttrKeyValid(key string) error
- func CheckConnection() error
- func Entry(pri Priority, msg string, attrs []Attr)
- func SetGlobalCommonAttr(attr []Attr)
- func SetGlobalConn(c *Conn)
- func SetGlobalErrHandler(errHandler func(err error))
- func WireWrite(buf *net.Buffers, w io.Writer, attrs []Attr) error
- type Attr
- type AttrKey
- type Conn
- type InvalidAttrKey
- type InvalidAttrKeyReason
- type Priority
Constants ¶
const ( // WellKnownSocketPath is where we generally expect to find the systemd // journal daemon's socket. WellKnownSocketPath = "/run/systemd/journal/socket" )
Variables ¶
This section is empty.
Functions ¶
func AttrKeyValid ¶
AttrKeyValid checks the given attribute key and returns an error if there is a fault with it.
func CheckConnection ¶
func CheckConnection() error
CheckConnection returns nil if the connection to the journal is OK, or an error otherwise. It will attempt to establish a connection to the journal if there is not already one in progress.
func Entry ¶
Entry writes a journal entry via the global connection. It will establish a connection as necessary.
Note: to avoid allocation / garbage, ensure attrs has capacity for an extra 2+len(GlobalCommonAttr) values.
func SetGlobalCommonAttr ¶
func SetGlobalCommonAttr(attr []Attr)
SetGlobalCommonAttr sets common attributes which will be added to every entry sent through the global connection.
func SetGlobalConn ¶
func SetGlobalConn(c *Conn)
SetGlobalConn can be used to override the default connection to the journal that is used by the global logging functions (the ones which do not directly operate on a Conn).
func SetGlobalErrHandler ¶
func SetGlobalErrHandler(errHandler func(err error))
SetGlobalErrHandler allows overriding the default error handler that is called when the connection fails. The default will attempt to reconnect to the journal socket after a short delay.
func WireWrite ¶
WireWrite is the lowest-level routine. It writes a journal entry using the native wire protocol documented at https://systemd.io/JOURNAL_NATIVE_PROTOCOL/ . Invalid attributes are silently skipped. It appends to buf as needed.
As long as w supports the net.buffersWriter interface, the write will be atomic, and this function is safe to use across goroutines. Otherwise, writes may be interleaved.
Types ¶
type Attr ¶
Attr represents a key/value pair ("attribute"), several of which comprise a journal entry.
func StringAttr ¶
StringAttr captures the common paradigm of building an Attr from a string.
func (Attr) UseTextProto ¶
UseTextProto returns true if we can use the text protocol to encode the message on the wire. It is heuristic; it will only consider messages of ≤ 128 bytes. Following guidance at https://systemd.io/JOURNAL_NATIVE_PROTOCOL/ it is intended to make for nice strace(1) traces.
type AttrKey ¶
type AttrKey struct {
// contains filtered or unexported fields
}
AttrKey holds the key part of a key/value (attribute) pair. Passing an uninitialised (or invalid) AttrKey to other journal methods will cause the attribute to be ignored; check for errors from NewAttrKey to ensure that your keys are valid ahead of time.
func MustAttrKey ¶
MustAttrKey returns an AttrKey for the given string. If the string is not a valid systemd attribute key, it returns an invalid AttrKey that will cause the attribute not to be emitted to the journal.
func NewAttrKey ¶
NewAttrKey initialises and returns an AttrKey that may be used when constructing key/value (attribute) pairs for logging. If the key is invalid, then an error will be returned (and the returned key value will be invalid, and any attribute using that key will silently be omitted from the logs). Rules for valid attribute keys:
- must not be empty;
- must not begin with an underscore '_';
- must only contain uppercase ASCII 'A'–'Z', digits '0'–'9', or underscores;
- must be < 256 characters.
type Conn ¶
type Conn struct {
// Common attributes which are emitted for all messages.
Common []Attr
// ErrHandler is called if there is an error writing to the log. If nil,
// the error is silently discarded.
ErrHandler func(error)
// contains filtered or unexported fields
}
Conn represents an active, open connection to the systemd journal that is ready to write log entries.
func Connect ¶
Connect to the systemd journal. If the path string is empty, then it uses the well-known socket path.
func (*Conn) Entry ¶
Entry emits a log entry. It will add PRIORITY and MESSAGE key/value pairs as well as any Common attributes.
func (*Conn) EntryErr ¶
EntryErr is like Entry, but will propagate errors to the caller, rather than using the built-in error handler.
func (*Conn) WriteAttrs ¶
WriteAttrs is a low-level method which writes a journal entry comprised of only the given set of attributes.
type InvalidAttrKey ¶
type InvalidAttrKey struct {
Key string
Reason InvalidAttrKeyReason
}
InvalidAttrKey details why a given attribute key is invalid.
func (*InvalidAttrKey) Error ¶
func (iak *InvalidAttrKey) Error() string
type InvalidAttrKeyReason ¶
type InvalidAttrKeyReason int
const ( AttrKeyEmpty InvalidAttrKeyReason = iota AttrKeyTrusted AttrKeyLength AttrKeyInvalidChars )
func (InvalidAttrKeyReason) String ¶
func (iar InvalidAttrKeyReason) String() string
type Priority ¶
type Priority int
Priority is the "level" or severity of the message.
Source Files