Version: v0.0.0-...-852726b Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Mar 16, 2016 License: MIT Imports: 13 Imported by: 3



Package format implements event formatting.

Default Formatters

The HumanMessage and HumanReadable formats are used as default formatters for most of the cue/collector and cue/hosted implementations. These are a good place to start, both for selecting a formatter, and for understanding how to implement custom formats.

Custom Formatting

While the Formatter interface is easy to implement, it's simpler to assemble a format using the existing formatting functions as building blocks. The Join and Formatf functions are particularly useful in this regard. Both assemble a new Formatter based on input formatters. See the predefined formats for examples.


All formatters append to a Buffer. The interface is similar to a bytes.Buffer, but with a simpler API. See the Buffer type documentation for details.



This section is empty.


View Source
var (
	// Message[: Error] key1=val1 key2=val2...
	HumanMessage = Escape(Trim(Join(" ", MessageWithError, HumanContext)))

	// Jan _2 15:04:05 INFO [Shortfile:Line] Message[: Error] key1=val1 key2=val2...
	HumanReadable       = Join(" ", Time(time.Stamp), Level, SourceWithLine, HumanMessage)
	HumanReadableColors = Colorize(HumanReadable)

	// Message[: Error] {"key1":"val1","key2":"val2"}
	JSONMessage = Join(" ", Escape(Trim(MessageWithError)), JSONContext)

Pre-defined Formatters. HumanReadable is a nice default when machine parsing isn't required.


func ContextName

func ContextName(buffer Buffer, event *cue.Event)

ContextName writes event.Context.Name() to the buffer. This is the name provided to cue.NewLogger().

func Error

func Error(buffer Buffer, event *cue.Event)

Error writes event.Error.Error() to the buffer. If event.Error is nil, nothing is written.

func ErrorType

func ErrorType(buffer Buffer, event *cue.Event)

ErrorType writes the dereferenced type name for the event's Error field. If event.Error is nil, nothing is written.

func FQDN

func FQDN(buffer Buffer, event *cue.Event)

FQDN writes the host's fully-qualified domain name (FQDN) to the buffer. If the FQDN cannot be determined, "unknown" is written instead.

func File

func File(buffer Buffer, event *cue.Event)

File writes the source file name that generated the event, path included. If this cannot be determined or frame collection is disabled, it writes cue.UnknownFile ("<unknown file>") instead.

func Function

func Function(buffer Buffer, event *cue.Event)

Function writes the function name that generated the event. If this cannot be determined or frame collection is disabled, it writes cue.UnknownFunction ("<unknown function>") instead.

func Hostname

func Hostname(buffer Buffer, event *cue.Event)

Hostname writes the host's short name to the buffer, domain excluded. If the hostname cannot be determined, "unknown" is written instead.

func HumanContext

func HumanContext(buffer Buffer, event *cue.Event)

HumanContext writes the event.Context key/value pairs in key=value format. This is similar to the format for structured logging prescribed by RFC5424, but suppresses quotes on values that don't contain spaces, quotes, or control characters. Other values are quoted using strconv.Quote.

func JSONContext

func JSONContext(buffer Buffer, event *cue.Event)

JSONContext marshals the event.Context fields into JSON and writes the result.

func Level

func Level(buffer Buffer, event *cue.Event)

Level writes event.Level.String() to the buffer. Hence, it writes "INFO" for INFO level messages, "DEBUG" for DEBUG level messages, and so on.

func Line

func Line(buffer Buffer, event *cue.Event)

Line writes the source line number that generated the event. If this cannot be determined or frame collection is disabled, it writes "0" instead.

func Message

func Message(buffer Buffer, event *cue.Event)

Message writes event.Message to the buffer.

func MessageWithError

func MessageWithError(buffer Buffer, event *cue.Event)

MessageWithError writes event.Message to the buffer, followed by ": " and event.Error.Error(). The latter portions are omitted if event.Error is nil.

func Package

func Package(buffer Buffer, event *cue.Event)

Package writes the package name that generated the event. If this cannot be determined or frame collection is disabled, it writes cue.UnknownPackage ("<unknown package>") instead.

func ReleaseBuffer

func ReleaseBuffer(buffer Buffer)

ReleaseBuffer returns a buffer to the buffer pool. Failing to release the buffer won't cause any harm, as the Go runtime will garbage collect it. However, as of Go 1.6, there's a significant performance gain in pooling and reusing Buffer instances.

func RenderBytes

func RenderBytes(formatter Formatter, event *cue.Event) []byte

RenderBytes renders the given event using formatter.

func RenderString

func RenderString(formatter Formatter, event *cue.Event) string

RenderString renders the given event using formatter.

func ShortFile

func ShortFile(buffer Buffer, event *cue.Event)

ShortFile writes the source file name that generated the event, path omitted. If this cannot be determined or frame collection is disabled, it writes cue.UnknownFile ("<unknown file>") instead.

func SourceWithLine

func SourceWithLine(buffer Buffer, event *cue.Event)

SourceWithLine writes ShortFile, followed by ":" and Line. If these cannot be determined or frame collection is disabled, nothing is written.

func StructuredContext

func StructuredContext(buffer Buffer, event *cue.Event)

StructuredContext marshals the event.Context fields into structured key=value pairs as prescribed by RFC 5424, "The Syslog Protocol".


type Buffer

type Buffer interface {
	// Bytes returns the buffered bytes.
	Bytes() []byte

	// Len Returns the number of buffered bytes.
	Len() int

	// Reset restores the buffer to a blank/empty state.  The underlying byte
	// slice is retained.

	// Append appends the byte slice value to the buffer.
	Append(value []byte)

	// AppendByte appends the byte value to the buffer.
	AppendByte(value byte)

	// AppendRune appends the rune value to the buffer.
	AppendRune(value rune)

	// AppendString appends the string value to the buffer.
	AppendString(value string)

Buffer represents a simple byte buffer. It's similar to bytes.Buffer but with a simpler API and implemented as an interface.

func GetBuffer

func GetBuffer() Buffer

GetBuffer returns an empty buffer from a pool of Buffers. A corresponding "defer ReleaseBuffer()" should be used to free the buffer when finished.

type Formatter

type Formatter func(buffer Buffer, event *cue.Event)

Formatter is the interface used to format Collector output.

func Colorize

func Colorize(formatter Formatter) Formatter

Colorize returns a new formatter that wraps the underlying formatter output in color escape codes by level: DEBUG output is blue, INFO output is green, WARN output is yellow, and ERROR/FATAL output is red. No additional color support is provided, nor will any be added.

func Escape

func Escape(formatter Formatter) Formatter

Escape returns a formatter that escapes all control characters and all whitespace characters other than ' ' (ASCII space) from the input formatter.

func Formatf

func Formatf(format string, formatters ...Formatter) Formatter

Formatf provides printf-like formatting of source formatters. The "%v" placeholder is used to specify formatter placeholders. In the rare event a literal "%v" is required, "%%v" renders the literal. No alignment, padding, or other printf constructs are currently supported, though code contributions are certainly welcome.

func Join

func Join(sep string, formatters ...Formatter) Formatter

Join returns a new Formatter that appends sep between the contents of underlying formatters. Sep is only appended between formatters that write one or more bytes to their buffers.

func Literal

func Literal(s string) Formatter

Literal returns a formatter that always writes s to its buffer.

func Time

func Time(timeFormat string) Formatter

Time returns a formatter that writes the event's timestamp to the buffer using the formatting rules from the time package.

func Trim

func Trim(formatter Formatter) Formatter

Trim returns a formatter that trims leading and trailing whitespace from the input formatter.

func Truncate

func Truncate(formatter Formatter, length int) Formatter

Truncate returns a new formatter that truncates the input formatter after length bytes are written.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL