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)
  • func (lg *Logger) Close()
  • func (lg *Logger) Log(t time.Time, s string)

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

	// Default value is false and this will try to create LogGroup in Cloudwatch, if the value is true
	AutoCreateLogGroup bool

	// 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 struct {
	// contains filtered or unexported fields
}

A Logger represents a single CloudWatch Logs log group.

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.

func (*Logger) Close

func (lg *Logger) Close()

Close drains all enqueued log messages and writes them to CloudWatch Logs. This method blocks until all pending log messages are written.

The Logger is not meant to be used anymore after this method is called. Doing so will result in a panic. Create a new Logger if you wish to write more logs.

func (*Logger) Log

func (lg *Logger) Log(t time.Time, s string)

Log enqueues a log message to be written to a log stream.

The log message must be less than 1,048,550 bytes, and the time must not be more than 2 hours in the future, 14 days in the past, or older than the retention period of the log group.

This method is safe for concurrent access by multiple goroutines.