logplexc

README

logplexc

Golang Logplex Client Driver

This library handles interactions with Logplex, and is able to be imported to send logs.

For documentation, see Godoc

Documentation

Overview

Package logplexc provides Logplex clients that can be linked into other Go programs.

Most users will want to use logplexc.Client, which implements a concurrent client, including periodic flushing, dropping, statistics accumulation, and request-level parallelism. logplexc.Client is built with logplexc.MiniClient.

To use the client, call NewClient with a configuration structure:

cfg := logplexc.Config{
	Logplex:	    "https://t:123@my.logplex.example.com",
	HttpClient:	    client,
	RequestSizeTrigger: 100 * KB,
	Concurrency:	    3,
	Period:		    3 * time.Second,
}

c, err := logplexc.NewClient(&cfg)
defer c.Close()
// Messages will be periodically flushed.
c.BufferMessage(...)

Those with advanced needs will want to use the low level logplexc.MiniClient, which implements log formatting, buffering, and HTTP POSTing.

Index

• type Bundle
• type Client
  • func NewClient(cfg *Config) (*Client, error)
  • func (m *Client) BufferMessage(priority int, when time.Time, host string, procId string, log []byte) error
  • func (m *Client) Close()
  • func (m *Client) Statistics() (s Stats)
• type Config
• type MiniClient
  • func NewMiniClient(cfg *MiniConfig) (client *MiniClient, err error)
  • func (c *MiniClient) BufferMessage(priority int, when time.Time, host string, procId string, log []byte) MiniStats
  • func (c *MiniClient) Post(b *Bundle) (*http.Response, error)
  • func (c *MiniClient) Statistics() MiniStats
  • func (c *MiniClient) SwapBundle() Bundle
• type MiniConfig
• type MiniStats
• type Stats
• type TimeTriggerBehavior

Types

type Bundle

type Bundle struct {
	MiniStats
	// contains filtered or unexported fields
}

A bundle of log messages. Bundles are used to act as buffers of multiple log records as well as the unit of work for submittted to Logplex.

type Client

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

A Logplex embeddable client implementation that includes concurrency, dropping, and statistics gathering.

func NewClient

func NewClient(cfg *Config) (*Client, error)

func (*Client) BufferMessage

func (m *Client) BufferMessage(
	priority int, when time.Time, host string, procId string,
	log []byte) error

func (*Client) Close

func (m *Client) Close()

func (*Client) Statistics

func (m *Client) Statistics() (s Stats)

type Config

type Config struct {
	Logplex            url.URL
	HttpClient         http.Client
	RequestSizeTrigger int
	Concurrency        int
	Period             time.Duration

	// Optional: Can be set for advanced behaviors like triggering
	// Never or Immediately.
	TimeTrigger TimeTriggerBehavior
}

type MiniClient

type MiniClient struct {
	// Configuration that should not be mutated after creation
	MiniConfig
	// contains filtered or unexported fields
}

MiniClient implements a low-level, synchronous Logplex client. It can format messages and gather statistics. Most uses of logplexc are anticipated to use logplexc.Client.

func NewMiniClient

func NewMiniClient(cfg *MiniConfig) (client *MiniClient, err error)

func (*MiniClient) BufferMessage

func (c *MiniClient) BufferMessage(
	priority int, when time.Time, host string, procId string,
	log []byte) MiniStats

Buffer a message for best-effort delivery to Logplex.

Return the critical statistics on what has been buffered so far so that the caller can opt to PostMessages() and empty the buffer.

No effort is expended to clean up bad bytes disallowed by syslog, as Logplex has a length-prefixed format.

func (*MiniClient) Post

func (c *MiniClient) Post(b *Bundle) (*http.Response, error)

Send a Bundle of logs to Logplex via HTTP POST.

func (*MiniClient) Statistics

func (c *MiniClient) Statistics() MiniStats

Copy the statistics structure embedded in the client.

func (*MiniClient) SwapBundle

func (c *MiniClient) SwapBundle() Bundle

Swap out the bundle of logs for a fresh one, so that buffering can continue again immediately. It's the caller's perogative to submit the returned, completed Bundle to logplex.

type MiniConfig

type MiniConfig struct {
	// The configuration is by-value to prevent most kinds of accidental
	// sharing of modifications between clients.  Also, modification of
	// the URL is compulsary in the constructor, and it's not desirable to
	// modify the version passed by the user as a side effect of
	// constructing a client instance.
	Logplex    url.URL
	HttpClient http.Client
}

Configuration of a MiniClient.

type MiniStats

type MiniStats struct {
	NumberFramed uint64
	Buffered     int
}

Running statistics on MiniClient operation

type Stats

type Stats struct {
	// Number of concurrent requests at the time of retrieval.
	Concurrency int32

	// Total messages submitted
	Total uint64

	// Incremented when a message is ignored outright because of
	// too much work being done already.
	Dropped uint64

	// Incremented when a log post request is not known to have
	// succeeded and one has given up waiting.
	Cancelled uint64

	// Incremented when a log post request is responded to,
	// affirming that the messages have been rejected.
	Rejected uint64

	// Incremented only when a positive response is received from
	// logplex.
	Successful uint64

	TotalRequests   uint64
	DroppedRequests uint64
	CancelRequests  uint64
	RejectRequests  uint64
	SuccessRequests uint64
}

type TimeTriggerBehavior

type TimeTriggerBehavior byte

const (
	// Carefully choose the zero-value so it is a reasonable
	// default, so that a user requesting the other behaviors --
	// which do not need a time -- can write things like:
	// TimeTrigger{Behavior: TimeTriggerImmediate} without
	// specifying a Period.
	TimeTriggerPeriodic TimeTriggerBehavior = iota
	TimeTriggerImmediate
	TimeTriggerNever
)