#log API reference

Leveled, structured logging. A log.Logger carries a minimum level (debug < info < warn < error), an output format (text / logfmt / json), and a sink; log.info(logger, message, fields) (and the sibling levels) render one record - a timestamp, the level, the message, and the caller's key/value fields - and write it, dropping records below the logger's level.

Sinks: stdout / stderr (both binaries, via io), a file (append, via fs), and an RFC 5424 syslog sink over UDP (net, so the syslog sink needs the default jennifer binary; the console / file sinks work on both). Over io / fs + json + strings + time + os (+ net for syslog).

Import with import "log.j" as log;. See the log guide for prose and examples.

#Functions

#log.at(logger as Logger, level as string, message as string, fields as map of string to string)

Emit a record at an explicit level (skipped if below the logger's level).

Parameters

• logger {Logger} - the logger
• level {string} - "debug", "info", "warn", or "error"
• message {string} - the log message
• fields {map of string to string} - structured key/value fields ({} for none)

Throws

• {Error} - on a sink failure (a positioned fs / net error)

#log.debug(logger as Logger, message as string, fields as map of string to string)

Emit a debug record.

Parameters

• logger {Logger} - the logger
• message {string} - the log message
• fields {map of string to string} - structured fields ({} for none)

#log.error(logger as Logger, message as string, fields as map of string to string)

Emit an error record.

Parameters

• logger {Logger} - the logger
• message {string} - the log message
• fields {map of string to string} - structured fields ({} for none)

#log.fatal(logger as Logger, message as string, fields as map of string to string)

Emit a fatal record and then terminate the program with exit code 1. The "fatal" level ranks above every other, so the record is always emitted regardless of the logger's minimum level.

Parameters

• logger {Logger} - the logger
• message {string} - the log message
• fields {map of string to string} - structured fields ({} for none)

#log.info(logger as Logger, message as string, fields as map of string to string)

Emit an info record.

Parameters

• logger {Logger} - the logger
• message {string} - the log message
• fields {map of string to string} - structured fields ({} for none)

#log.new(level as string, format as string)

A logger writing to standard output.

Parameters

• level {string} - the minimum level ("debug"/"info"/"warn"/"error")
• format {string} - "text", "logfmt", or "json"

Returns {Logger} - the logger

#log.toFile(level as string, format as string, path as string)

A logger appending to a file (created if missing).

Parameters

• level {string} - the minimum level
• format {string} - "text", "logfmt", or "json"
• path {string} - the file path

Returns {Logger} - the logger

#log.toStderr(level as string, format as string)

A logger writing to standard error.

Parameters

• level {string} - the minimum level
• format {string} - "text", "logfmt", or "json"

Returns {Logger} - the logger

#log.toSyslog(level as string, address as string, app as string)

A logger sending RFC 5424 records to a syslog server over UDP. Needs the default jennifer binary (net).

Parameters

• level {string} - the minimum level
• address {string} - the syslog server "host:port" (e.g. "localhost:514")
• app {string} - the APP-NAME tag

Returns {Logger} - the logger

#log.warn(logger as Logger, message as string, fields as map of string to string)

Emit a warn record.

Parameters

• logger {Logger} - the logger
• message {string} - the log message
• fields {map of string to string} - structured fields ({} for none)

#log.with(logger as Logger, fields as map of string to string)

A child logger carrying persistent context fields. Every record emitted through the returned logger includes these fields, merged with any per-call fields (a per-call key of the same name wins). Composes: calling with again on the result merges the new fields on top of the carried ones. The parent logger is unchanged (value semantics).

Parameters

• logger {Logger} - the parent logger
• fields {map of string to string} - the persistent fields to attach

Returns {Logger} - a new logger with the merged persistent fields

#Structs

#log.Logger

A value-semantic logger configuration. Build one with new / toStderr / toFile / toSyslog.