Documentation ¶
Overview ¶
Package sllm is the 2nd iteration of the reference implementation for the Structured Logging Lightweight Markup format.
The goal is to create a human-readable format for the message part of log entries that also makes the parameters in the log message reliably machine-readable. This is a task generally performed by markup languages. However, sllm is intended to be much less intrusive than, for example, XML or JSON. The traditional log message:
2019/01/11 19:32:44 added 7 ⨉ Hat to shopping cart by John Doe
would become something like (depending on the choice of parameter names)
2019/01/11 19:32:44 added `count:7` ⨉ `item:Hat` to shopping cart by `user:John Doe`
This is still readable by humans but can also be parsed reliably by machines. Machine reading would not fail even if the message template changes the order of the parameters. Careful choice of parameter names can make the messages even more meaningful.
This package is no logging library—it provides functions to create and parse sllm messages.
Example ¶
// Positional arguments Fprint(os.Stdout, "added `count` ⨉ `item` to shopping cart by `user`\n", Argv("", 7, "Hat", "John Doe"), ) // Named arguments Fprint(os.Stdout, "added `count` ⨉ `item` to shopping cart by `user`\n", Named("", map[string]any{ "count": 7, "item": "Hat", "user": "John Doe", }), )
Output: added `count:7` ⨉ `item:Hat` to shopping cart by `user:John Doe` added `count:7` ⨉ `item:Hat` to shopping cart by `user:John Doe`
Index ¶
- Constants
- func Bprint(wr *bytes.Buffer, tmpl string, args ArgPrintFunc) (int, error)
- func Error(tmpl string, args ...any) error
- func Expand(buf []byte, tmpl string, args ArgPrintFunc) ([]byte, error)
- func ExtractParams(appendTo []string, tmpl string) ([]string, error)
- func Fprint(wr io.Writer, tmpl string, args ArgPrintFunc) (int, error)
- func Parse(msg string, tmpl *bytes.Buffer, onArg func(name, value string) error) error
- func ParseMap(msg string, tmpl *bytes.Buffer) (map[string][]string, error)
- func Sprint(tmpl string, args ArgPrintFunc) (string, error)
- type ArgPrintFunc
- type ArgWriter
- func (w *ArgWriter) Write(p []byte) (n int, err error)
- func (w *ArgWriter) WriteInt(i int) (n int, err error)
- func (w *ArgWriter) WriteInt64(i int64) (n int, err error)
- func (w *ArgWriter) WriteString(s string) (n int, err error)
- func (w *ArgWriter) WriteTime(t time.Time, f TimeFormat) (n int, err error)
- type IllegalArgIndex
- type SyntaxError
- type TimeFormat
- type UndefinedArg
Examples ¶
Constants ¶
const Tdefault = Tdate
Variables ¶
This section is empty.
Functions ¶
func Bprint ¶
Bprint uses Expand to print the sllm message to an in-memory buffer. Bprint is somewhat faster than Print.
func Error ¶
Example ¶
fmt.Println(Error("this is just `an` message with missing `param`", "error")) fmt.Println(Error("this will `fail", "dummy"))
Output: this is just `an:error` message with missing `param:<?>` [sllm:syntax error in `tmpl:this will ``fail`:`pos:11`:`desc:unterminated argument`]
func Expand ¶
func Expand(buf []byte, tmpl string, args ArgPrintFunc) ([]byte, error)
Expand appends a message to buf by expanding all arguments of the given template tmpl. The actual process of expanding an argument is left to ArgPrintFunc args.
See also Args and Map
func ExtractParams ¶
ExtractParams extracs the parameter names from template tmpl and appends them to appendTo.
func Parse ¶
Parse parses a sllm message create by Expand and calls onArg for every `name:value` parameter it finds in the message. When a non-nil buffer is passed as tmpl Parse will also reconstruct the original template into the buffer. Note that the template is appended to tmpl's content.
func ParseMap ¶
ParseMap uses Parse to create a map with all parameters assigned to an argument in the passed message msg. ParseMap can also reconstruct the template when passing a Buffer to tmpl.
Example ¶
var tmpl bytes.Buffer m, _ := ParseMap( "added `count:7` ⨉ `item:Hat` to shopping cart by `user:John Doe`", &tmpl, ) fmt.Println(tmpl.String()) for k, v := range m { fmt.Printf("%s:[%s]\n", k, v) }
Output: added `count` ⨉ `item` to shopping cart by `user` count:[[7]] item:[[Hat]] user:[[John Doe]]
Types ¶
type ArgPrintFunc ¶
ArgPrintFunc is used by the Expand function to process an argument when it appears in the expand process of a template. Expand will pass the index idx and the name of the argument to expand, i.e. write into the writer wr. A ArgPrintFunc returns the number of bytes writen and—just in case—an error.
NOTE: The writer wr of type ArgWriter will escape whatever ArgPrintFunc writes so that the template escape symbol '`' remains recognizable.
See also Args and Map
func Argv ¶
func Argv(u string, av ...any) ArgPrintFunc
type ArgWriter ¶
type ArgWriter []byte
ArgWriter is used by Expand to escape the argument when written as a value of a parameter. It is assumed that a user of this package should not use this type directly. However the type will be needed if one wants to provide an own ArgPrintFunc.
Example ¶
var ew ArgWriter ew.Write([]byte("foo")) fmt.Println(string(ew)) ew = ew[:0] ew.Write([]byte("`bar`")) fmt.Println(string(ew)) ew = ew[:0] ew.Write([]byte("b`az")) fmt.Println(string(ew))
Output: foo ``bar`` b``az
func (*ArgWriter) Write ¶
Write escapes the content so that it can be reliably recognized in a sllm message, i.e. replace each single backtick '`' with two backticks.
func (*ArgWriter) WriteInt64 ¶ added in v2.1.1
type IllegalArgIndex ¶
type IllegalArgIndex int
func (IllegalArgIndex) Error ¶
func (err IllegalArgIndex) Error() string
type SyntaxError ¶
type SyntaxError struct { // Tmpl is the errornous template string Tmpl string // Pas is the byte position within the template string Pos int // Err is the description of the error Err string }
SyntaxError describes errors of the sllm template syntax in a message template.
func (SyntaxError) Error ¶
func (err SyntaxError) Error() string
type TimeFormat ¶ added in v2.1.1
type TimeFormat int
Example ¶
t := time.Date(2023, 05, 04, 21, 43, 1, 2003000, time.UTC) buf := ArgWriter([]byte{}) buf.WriteTime(t, Tdefault) fmt.Println(string(buf)) buf = buf[:0] buf.WriteTime(t, Tdate|Tyear|Tmicros) fmt.Println(string(buf)) buf = buf[:0] buf.WriteTime(t, Tdate|Tyear|Tmillis) fmt.Println(string(buf))
Output: May 04 21:43:01 2023 May 04 21:43:01.002003 2023 May 04 21:43:01.002
const ( Tdate TimeFormat = 1 << iota Tyear TUTC Tmillis Tmicros )
func (TimeFormat) Format ¶ added in v2.1.1
func (tf TimeFormat) Format(t time.Time) timeFormatter
type UndefinedArg ¶
type UndefinedArg string
func (UndefinedArg) Error ¶
func (err UndefinedArg) Error() string