Documentation
¶
Overview ¶
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.
Buffers ¶
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.
Index ¶
- Variables
- func ContextName(buffer Buffer, event *cue.Event)
- func Error(buffer Buffer, event *cue.Event)
- func ErrorType(buffer Buffer, event *cue.Event)
- func FQDN(buffer Buffer, event *cue.Event)
- func File(buffer Buffer, event *cue.Event)
- func Function(buffer Buffer, event *cue.Event)
- func Hostname(buffer Buffer, event *cue.Event)
- func HumanContext(buffer Buffer, event *cue.Event)
- func JSONContext(buffer Buffer, event *cue.Event)
- func Level(buffer Buffer, event *cue.Event)
- func Line(buffer Buffer, event *cue.Event)
- func Message(buffer Buffer, event *cue.Event)
- func MessageWithError(buffer Buffer, event *cue.Event)
- func Package(buffer Buffer, event *cue.Event)
- func ReleaseBuffer(buffer Buffer)
- func RenderBytes(formatter Formatter, event *cue.Event) []byte
- func RenderString(formatter Formatter, event *cue.Event) string
- func ShortFile(buffer Buffer, event *cue.Event)
- func SourceWithLine(buffer Buffer, event *cue.Event)
- func StructuredContext(buffer Buffer, event *cue.Event)
- type Buffer
- type Formatter
- func Colorize(formatter Formatter) Formatter
- func Escape(formatter Formatter) Formatter
- func Formatf(format string, formatters ...Formatter) Formatter
- func Join(sep string, formatters ...Formatter) Formatter
- func Literal(s string) Formatter
- func Time(timeFormat string) Formatter
- func Trim(formatter Formatter) Formatter
- func Truncate(formatter Formatter, length int) Formatter
Constants ¶
This section is empty.
Variables ¶
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.
Functions ¶
func ContextName ¶
ContextName writes event.Context.Name() to the buffer. This is the name provided to cue.NewLogger().
func Error ¶
Error writes event.Error.Error() to the buffer. If event.Error is nil, nothing is written.
func ErrorType ¶
ErrorType writes the dereferenced type name for the event's Error field. If event.Error is nil, nothing is written.
func FQDN ¶
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 ¶
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 ¶
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 ¶
Hostname writes the host's short name to the buffer, domain excluded. If the hostname cannot be determined, "unknown" is written instead.
func HumanContext ¶
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 ¶
JSONContext marshals the event.Context fields into JSON and writes the result.
func Level ¶
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 ¶
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 MessageWithError ¶
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 ¶
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 ¶
RenderBytes renders the given event using formatter.
func RenderString ¶
RenderString renders the given event using formatter.
func ShortFile ¶
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 ¶
SourceWithLine writes ShortFile, followed by ":" and Line. If these cannot be determined or frame collection is disabled, nothing is written.
Types ¶
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.
Reset()
// 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.
type Formatter ¶
Formatter is the interface used to format Collector output.
func Colorize ¶
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 ¶
Escape returns a formatter that escapes all control characters and all whitespace characters other than ' ' (ASCII space) from the input formatter.
func Formatf ¶
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 ¶
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 Time ¶
Time returns a formatter that writes the event's timestamp to the buffer using the formatting rules from the time package.
Source Files