golf

package module
v0.0.0-...-02c07f1 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2018 License: MIT Imports: 14 Imported by: 25

README

golf

GoDoc Build Status codecov.io

Golf is an MIT-licensed Go client library for servers supporting the Graylog Extended Log Format (GELF, https://www.graylog.org/resources/gelf-2/).

If you run into any issues with the library or have any feature requests, please create issues for them!

As this library is very new, the API could still change. I don't expect it to change much because I'm pretty happy with how it is now but if anyone has suggestions easier ways to use the library via API changes I would be open to it.

Test coverage is an ongoing process!

Features

  • GELF 1.1 support
  • Native Go implementation
  • Supports Logger-level and Message-level attributes

Installation

The recommended way to install is via http://gopkg.in

go get gopkg.in/aphistic/golf.v0
...
import "gopkg.in/aphistic/golf.v0"

Golf can also be installed the standard way as well

go get github.com/aphistic/golf
...
import "github.com/aphistic/golf"

Examples

For brevity a lot of error checking has been omitted from these examples, be sure you do your checks!

The standard way to implement the golf library is by creating a Client, connecting to a server and creating Loggers off that Client:

package main

import (
    "gopkg.in/aphistic/golf.v0"
)

func main() {
    c, _ := golf.NewClient()
    c.Dial("udp://192.168.30.150")

    l, _ := c.NewLogger()
    // Attributes set at the Logger level will automatically be included
    // on each message sent from that Logger.  This is helpful if there's
    // any consistent information you don't want to include every time you
    // log a message.
    l.SetAttr("facility", "golf.example")
    l.SetAttr("instance_id", 12345)

    for idx := 1; idx <= 10; idx++ {
        l.Dbgm(map[string]interface{}{
            "msg_attr1": 1234,
        }, "Test message %v", idx)
    }

    c.Close()
}

It is also possible to set a Logger as the default for the golf library so you don't need to keep track of a main Logger manually:

package main

import (
    "gopkg.in/aphistic/golf.v0"
)

func main() {
    c, _ := golf.NewClient()
    c.Dial("udp://192.168.30.150")

    l, _ := c.NewLogger()
    // Set l as the default logger
    golf.DefaultLogger(l)
    // Attributes set at the Logger level will automatically be included
    // on each message sent from that Logger.  This is helpful if there's
    // any consistent information you don't want to include every time you
    // log a message.
    l.SetAttr("facility", "golf.example")
    l.SetAttr("instance_id", 12345)

    for idx := 1; idx <= 10; idx++ {
        // Use the default logger to send the message
        golf.Dbgm(map[string]interface{}{
            "msg_attr1": 1234,
        }, "Test message %v", idx)
    }

    c.Close()
}

You can use the query parameter "compress" in the Dial URL, with one of the following value:

  • none
  • zlib
  • gzip
udp://192.168.30.150?compress=none

Default is gzip compression.

Documentation

Overview

Provides logging capabilities using the GELF (https://www.graylog.org/resources/gelf-2/) log format

Example 
c, _ := NewClient()
c.Dial("udp://localhost")

l, _ := c.NewLogger()
l.SetAttr("facility", "example.facility")

wait := make(chan int)
go func() {
	for idx := 1; idx <= 10; idx++ {
		l.Dbgm(
			map[string]interface{}{
				"attr1": "val1",
				"attr2": 1234},
			"Test %v",
			idx)
		idx += 1
	}
	wait <- 1
}()
<-wait

Output:
Example (DefaultLogger) 
c, _ := NewClient()
c.Dial("udp://localhost")

l, _ := c.NewLogger()
l.SetAttr("facility", "example.facility")
DefaultLogger(l)

wait := make(chan int)
go func() {
	for idx := 1; idx <= 10; idx++ {
		Dbgm(
			map[string]interface{}{
				"attr1": "val1",
				"attr2": 1234},
			"Test %v",
			idx)
		idx += 1
	}
	wait <- 1
}()
<-wait

Output:

Index

Examples

Constants

View Source 
const (
	COMP_NONE = iota // No compression
	COMP_GZIP        // gzip compression
	COMP_ZLIB        // zlib compression
)

Compression type to use for GELF messages that are sent

View Source 
const (
	LEVEL_EMERG  = iota // Emergency
	LEVEL_ALERT         // Alert
	LEVEL_CRIT          // Critical
	LEVEL_ERR           // Error
	LEVEL_WARN          // Warning
	LEVEL_NOTICE        // Notice
	LEVEL_INFO          // Informational
	LEVEL_DBG           // Debug
)

Levels to be used when logging messages. These match syslog levels as the GELF spec specifies.

Variables

View Source 
var (
	ErrChunkTooSmall = errors.New("chunk size is too small, it must be at least 13")
)

Functions

func Alert 

func Alert(msg string) error

Log a message 'msg' at LEVEL_ALERT level on the default logger

func Alertf 

func Alertf(format string, va ...interface{}) error

Log a message at LEVEL_ALERT with 'format' populated with values from 'va' on the default logger

func Alertm 

func Alertm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_ALERT with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func Crit 

func Crit(msg string) error

Log a message 'msg' at LEVEL_CRIT level on the default logger

func Critf 

func Critf(format string, va ...interface{}) error

Log a message at LEVEL_CRIT with 'format' populated with values from 'va' on the default logger

func Critm 

func Critm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_CRIT with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func Dbg 

func Dbg(msg string) error

Log a message 'msg' at LEVEL_DBG level on the default logger

func Dbgf 

func Dbgf(format string, va ...interface{}) error

Log a message at LEVEL_DBG with 'format' populated with values from 'va' on the default logger

func Dbgm 

func Dbgm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_DBG with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func DefaultLogger 

func DefaultLogger(l *Logger)

Set the default Logger. Any calls to log messages not associated with a specific Logger (such as calling l.Dbg()) will use the default logger.

func Emerg 

func Emerg(msg string) error

Log a message 'msg' at LEVEL_EMERG level on the default logger

func Emergf 

func Emergf(format string, va ...interface{}) error

Log a message at LEVEL_EMERG with 'format' populated with values from 'va' on the default logger

func Emergm 

func Emergm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_EMERG with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func Err 

func Err(msg string) error

Log a message 'msg' at LEVEL_ERR level on the default logger on the default logger

func Errf 

func Errf(format string, va ...interface{}) error

Log a message at LEVEL_ERR with 'format' populated with values from 'va' on the default logger

func Errm 

func Errm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_ERR with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func Info 

func Info(msg string) error

Log a message 'msg' at LEVEL_INFO level on the default logger

func Infof 

func Infof(format string, va ...interface{}) error

Log a message at LEVEL_INFO with 'format' populated with values from 'va' on the default logger

func Infom 

func Infom(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_INFO with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func Notice 

func Notice(msg string) error

Log a message 'msg' at LEVEL_NOTICE level on the default logger

func Noticef 

func Noticef(format string, va ...interface{}) error

Log a message at LEVEL_NOTICE with 'format' populated with values from 'va' on the default logger

func Noticem 

func Noticem(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_NOTICE with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func Warn 

func Warn(msg string) error

Log a message 'msg' at LEVEL_WARN level on the default logger

func Warnf 

func Warnf(format string, va ...interface{}) error

Log a message at LEVEL_WARN with 'format' populated with values from 'va' on the default logger

func Warnm 

func Warnm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_WARN with 'format' populated with values from 'va' on the default logger. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient() (*Client, error)

Create a new Client instance with the default values for ClientConfig: 

 {
	ChunkSize: 1420,
	Compression: COMP_GZIP,
 }

func NewClientWithConfig 

func NewClientWithConfig(config ClientConfig) (*Client, error)

Create a new Client instance with the given ClientConfig

func (*Client) Close 

func (c *Client) Close() error

Close the connection to the server. This call will block until all the currently queued messages for the client are sent.

func (*Client) Dial 

func (c *Client) Dial(uri string) error

Connect to a GELF server at the given URI.

func (*Client) NewLogger 

func (c *Client) NewLogger() (*Logger, error)

Create a new Logger associated with the Client. Any messages logged with this Logger (and any Logger cloned from this) will be sent to Client.

func (*Client) QueueMsg 

func (c *Client) QueueMsg(msg *Message) error

Queue the given message at the end of the message queue

type ClientConfig 

type ClientConfig struct {
	ChunkSize   int // The data size for each chunk sent to the server
	Compression int // Compression to use for messagec.
}

Configuration used when creating a server instance

type Logger 

type Logger struct {
	// contains filtered or unexported fields
}

A Logger is a set of attributes associated with a Client. When a message is sent with the Logger, the attributes from that Logger will be added to the message.

func (*Logger) Alert 

func (l *Logger) Alert(msg string) error

Log a message 'msg' at LEVEL_ALERT level

func (*Logger) Alertf 

func (l *Logger) Alertf(format string, va ...interface{}) error

Log a message at LEVEL_ALERT with 'format' populated with values from 'va'

func (*Logger) Alertm 

func (l *Logger) Alertm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_ALERT with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) Attr 

func (l *Logger) Attr(name string) interface{}

Retrieve the current value of the Logger level attribute named 'name'. Returns nil if the attribute was not found

func (*Logger) Clone 

func (l *Logger) Clone() *Logger

Create a new Logger with a shallow copy of the original Logger's attributes

func (*Logger) Crit 

func (l *Logger) Crit(msg string) error

Log a message 'msg' at LEVEL_CRIT level

func (*Logger) Critf 

func (l *Logger) Critf(format string, va ...interface{}) error

Log a message at LEVEL_CRIT with 'format' populated with values from 'va'

func (*Logger) Critm 

func (l *Logger) Critm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_CRIT with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) Dbg 

func (l *Logger) Dbg(msg string) error

Dbg logs message 'msg' at LEVEL_DBG level

func (*Logger) Dbgf 

func (l *Logger) Dbgf(format string, va ...interface{}) error

Log a message at LEVEL_DBG with 'format' populated with values from 'va'

func (*Logger) Dbgm 

func (l *Logger) Dbgm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_DBG with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) Emerg 

func (l *Logger) Emerg(msg string) error

Log a message 'msg' at LEVEL_EMERG level

func (*Logger) Emergf 

func (l *Logger) Emergf(format string, va ...interface{}) error

Log a message at LEVEL_EMERG with 'format' populated with values from 'va'

func (*Logger) Emergm 

func (l *Logger) Emergm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_EMERG with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) Err 

func (l *Logger) Err(msg string) error

Log a message 'msg' at LEVEL_ERR level

func (*Logger) Errf 

func (l *Logger) Errf(format string, va ...interface{}) error

Log a message at LEVEL_ERR with 'format' populated with values from 'va'

func (*Logger) Errm 

func (l *Logger) Errm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_ERR with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) Info 

func (l *Logger) Info(msg string) error

Log a message 'msg' at LEVEL_INFO level

func (*Logger) Infof 

func (l *Logger) Infof(format string, va ...interface{}) error

Log a message at LEVEL_INFO with 'format' populated with values from 'va'

func (*Logger) Infom 

func (l *Logger) Infom(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_INFO with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) NewMessage 

func (l *Logger) NewMessage() *Message

Create a new message associated with a Logger. When the message is sent, it will use the attributes associated with the Logger it was created from in addition to its own

func (*Logger) Notice 

func (l *Logger) Notice(msg string) error

Log a message 'msg' at LEVEL_NOTICE level

func (*Logger) Noticef 

func (l *Logger) Noticef(format string, va ...interface{}) error

Log a message at LEVEL_NOTICE with 'format' populated with values from 'va'

func (*Logger) Noticem 

func (l *Logger) Noticem(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_NOTICE with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

func (*Logger) RemAttr 

func (l *Logger) RemAttr(name string)

Remove the attribute named 'name' from the Logger level of attributes

func (*Logger) SetAttr 

func (l *Logger) SetAttr(name string, val interface{})

Set an attribute named 'name' to the value 'val' at the Logger level of attributes

func (*Logger) Warn 

func (l *Logger) Warn(msg string) error

Log a message 'msg' at LEVEL_WARN level

func (*Logger) Warnf 

func (l *Logger) Warnf(format string, va ...interface{}) error

Log a message at LEVEL_WARN with 'format' populated with values from 'va'

func (*Logger) Warnm 

func (l *Logger) Warnm(attrs map[string]interface{}, format string, va ...interface{}) error

Log a message at LEVEL_WARN with 'format' populated with values from 'va'. The attributes from 'attrs' will be included with the message, overriding any that may be set at the Logger level

type Message 

type Message struct {
	Level        int                    // Log level for the message (see LEVEL_DBG, etc)
	Hostname     string                 // Hostname of the client
	Timestamp    *time.Time             // Timestamp for the message. Populated automatically if left nil
	ShortMessage string                 // Short log message
	FullMessage  string                 // Full message (optional). Can be used for things like stack traces.
	Attrs        map[string]interface{} // A list of attributes to add to the message
	// contains filtered or unexported fields
}

A message to be serialized and sent to the GELF server

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.