cwlogger

README

cwlogger

A Go library for easily and reliably writing logs to Amazon CloudWatch Logs.

Documentation

See GoDoc for usage instructions and API documentation.

License

MIT License.

Documentation

Overview

Package cwlogger is a library for reliably writing logs to Amazon CloudWatch Logs.

Features

Batches log messages for efficiency by decreasing the number of API calls.

Handles log stream creation based on log throughput. If too many logs are being written in a short period of time, the CloudWatch Logs API will return a ThrottlingException, which this library handles by creating an additional log stream every time that happens. Subsequent log writes will be distributed throughout all existing log streams.

Handles DataAlreadyAcceptedException and InvalidSequenceTokenException errors by setting the log stream sequence token to the one returned by the error response. For InvalidSequenceTokenException, the request will be retried with the correct sequence token.

Retries PutLogEvents API calls in case of connection failure, or temporary errors on CloudWatch Logs.

Dependencies

The only dependency for this package is the official AWS SDK for Go.

Usage

Use the AWS SDK for Go to configure and create the client.

logger, err := cwlogger.New(&cwlogger.Config{
  LogGroupName: "groupName",
  Client: cloudwatchlogs.New(session.New())
})
// handle err
logger.Log(time.Now(), "log message")

For information on how to configure the AWS client, refer to the AWS documentation at http://docs.aws.amazon.com/sdk-for-go/api/aws/session/.

Index

• type Config
• type Error
  • func (err Error) Error() string
• type Logger
  • func New(config *Config) (Logger, error)

Types

type Config

type Config struct {
	// The Amazon CloudWatch Logs client created with the AWS SDK for Go.
	// Required.
	Client *cloudwatchlogs.CloudWatchLogs

	// The name of the log group to write logs into. Required.
	LogGroupName string

	// OPTIONAL - A prefix to add before the random part of the streamname
	StreamPrefix string

	// An optional function to report errors that couldn't be automatically
	// handled during a PutLogEvents API call and caused a log events to be
	// dropped.
	ErrorReporter func(err error)

	// An optional log group retention time in days. This value is only taken into
	// account when creating a log group that does not yet exist. Set to 0
	// (default) for no retention policy. Refer to the PutRetentionPolicy API
	// documentation for valid values.
	Retention int
}

The Config for the logger.

type Error

type Error struct {
	Code    string
	Message string
}

Error contains the AWS error code and message that caused the PutLogEvents action to fail. Errors reported by the LogGroup ErrorReporter function may be converted into this type.

func (Error) Error

func (err Error) Error() string

type Logger

type Logger interface {
	Log(t time.Time, s string)
	Close()
}

func New

func New(config *Config) (Logger, error)

New creates a new logger.

Creates the log group if it doesn't yet exist, and one initial log stream for writing logs into.

Returns an error if the configuration is invalid, or if either the creation of the log group or log stream fail.