cloudwatchwriter

README

cloudwatchwriter

Package to enable sending logs from zerolog to AWS CloudWatch.

Usage

This library assumes that you have IAM credentials to allow you to talk to AWS CloudWatch Logs. The specific permissions that are required are:

• CreateLogGroup,
• CreateLogStream,
• DescribeLogStreams,
• PutLogEvents.

If these permissions aren't assigned to the user who's IAM credentials you're using then this package will not work. There are two exceptions to that:

• if the log group already exists, then you don't need permission to CreateLogGroup;
• if the log stream already exists, then you don't need permission to CreateLogStream.

Standard use case

If you want zerolog to send all logs to CloudWatch then do the following:

import (
	"fmt"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/credentials"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/mec07/cloudwatchwriter"
	"github.com/rs/zerolog/log"
)

const (
    region = "eu-west-2"
    logGroupName = "log-group-name"
    logStreamName = "log-stream-name"
)

// setupZerolog sets up the main zerolog logger to write to CloudWatch instead
// of stdout. It returns an error or the CloudWatchWriter.Close method which
// blocks until all the logs have been processed.
func setupZerolog(accessKeyID, secretKey string) (func(), error) {
	sess, err := session.NewSession(&aws.Config{
		Region:      aws.String(region),
		Credentials: credentials.NewStaticCredentials(accessKeyID, secretKey, ""),
	})
	if err != nil {
		return nil, fmt.Errorf("session.NewSession: %w", err)
	}

	cloudWatchWriter, err := cloudwatchwriter.New(sess, logGroupName, logStreamName)
	if err != nil {
		return nil, fmt.Errorf("cloudwatchwriter.New: %w", err)
	}

	log.Logger = log.Output(cloudWatchWriter)
	return cloudWatchWriter.Close, nil
}

If you want to ensure that all your logs are sent to CloudWatch during the shut down sequence of your program then you can defer the cloudWatchWriter.Close() function in main. The Close() function blocks until all the logs have been processed. If you prefer to use AWS IAM credentials that are saved in the usual location on your computer then you don't have to specify the credentials, e.g.:

sess, err := session.NewSession(&aws.Config{
    Region:      aws.String(region),
})

For more details, see: https://docs.aws.amazon.com/sdk-for-go/api/aws/session/. See the example directory for a working example.

Write to CloudWatch and the console

What I personally prefer is to write to both CloudWatch and the console, e.g.

cloudWatchWriter, err := cloudwatchwriter.New(sess, logGroupName, logStreamName)
if err != nil {
    return fmt.Errorf("cloudwatchwriter.New: %w", err)
}
consoleWriter := zerolog.ConsoleWriter{Out: os.Stdout}
log.Logger = log.Output(zerolog.MultiLevelWriter(consoleWriter, cloudWatchWriter))

Create a new zerolog Logger

Of course, you can create a new zerolog.Logger using this too:

cloudWatchWriter, err := cloudwatchwriter.New(sess, logGroupName, logStreamName)
if err != nil {
    return fmt.Errorf("cloudwatchwriter.New: %w", err)
}
logger := zerolog.New(cloudWatchWriter).With().Timestamp().Logger()

and of course you can create a new zerolog.Logger which can write to both CloudWatch and the console:

cloudWatchWriter, err := cloudwatchwriter.New(sess, logGroupName, logStreamName)
if err != nil {
    return fmt.Errorf("cloudwatchwriter.New: %w", err)
}
consoleWriter := zerolog.ConsoleWriter{Out: os.Stdout}
logger := zerolog.New(zerolog.MultiLevelWriter(consoleWriter, cloudWatchWriter)).With().Timestamp().Logger()

Changing the default settings

Batch interval

The logs are sent in batches because AWS has a maximum of 5 PutLogEvents requests per second per log stream (https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html). The default value of the batch period is 5 seconds, which means it will send the a batch of logs at least once every 5 seconds. Batches of logs will be sent earlier if the size of the collected logs exceeds 1MB (another AWS restriction). To change the batch frequency, you can set the time interval between batches to a smaller or larger value, e.g. 1 second:

err := cloudWatchWriter.SetBatchInterval(time.Second)

If you set it below 200 milliseconds it will return an error. The batch interval is not guaranteed as two things can alter how often the batches get delivered:

• as soon as 1MB of logs or 10k logs have accumulated, they are sent (due to AWS restrictions on batch size);
• we have to send the batches in sequence (an AWS restriction) so a long running request to CloudWatch can delay the next batch.

Error Handler

Sometimes there are problems communicating with CloudWatch and you may want to do something in these circumstances (e.g. you could even create a new writer, Close() the old one, and attach the new one to your logger). To facilitate user defined error handling you can set an error handler on the CloudWatchWriter:

cloudWatchWriter.SetErrorHandler(func(err error) {
	// do something
})

Acknowledgements

Much thanks has to go to the creator of zerolog (https://github.com/rs/zerolog), for creating such a good logger. Thanks must go to the writer of logrus-cloudwatchlogs (https://github.com/kdar/logrus-cloudwatchlogs) as I found it a helpful resource for interfacing with cloudwatchlogs. Thanks also goes to the writer of this: https://gist.github.com/asdine/f821abe6189a04250ae61b77a3048bd9, which I also found helpful for extracting logs from zerolog.

Documentation

Index

• type CloudWatchLogsClient
• type CloudWatchWriter
  • func New(sess *session.Session, logGroupName, logStreamName string) (*CloudWatchWriter, error)
  • func NewWithClient(client CloudWatchLogsClient, batchInterval time.Duration, ...) (*CloudWatchWriter, error)
  • func (c *CloudWatchWriter) Close()
  • func (c *CloudWatchWriter) SetBatchInterval(interval time.Duration) error
  • func (c *CloudWatchWriter) SetErrorHandler(handler func(error))
  • func (c *CloudWatchWriter) Write(log []byte) (int, error)

Types

type CloudWatchLogsClient

type CloudWatchLogsClient interface {
	DescribeLogStreams(*cloudwatchlogs.DescribeLogStreamsInput) (*cloudwatchlogs.DescribeLogStreamsOutput, error)
	CreateLogGroup(*cloudwatchlogs.CreateLogGroupInput) (*cloudwatchlogs.CreateLogGroupOutput, error)
	CreateLogStream(*cloudwatchlogs.CreateLogStreamInput) (*cloudwatchlogs.CreateLogStreamOutput, error)
	PutLogEvents(*cloudwatchlogs.PutLogEventsInput) (*cloudwatchlogs.PutLogEventsOutput, error)
}

CloudWatchLogsClient represents the AWS cloudwatchlogs client that we need to talk to CloudWatch

type CloudWatchWriter

type CloudWatchWriter struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

CloudWatchWriter can be inserted into zerolog to send logs to CloudWatch.

func New

func New(sess *session.Session, logGroupName, logStreamName string) (*CloudWatchWriter, error)

New returns a pointer to a CloudWatchWriter struct, or an error.

func NewWithClient

func NewWithClient(client CloudWatchLogsClient, batchInterval time.Duration, logGroupName, logStreamName string) (*CloudWatchWriter, error)

NewWithClient returns a pointer to a CloudWatchWriter struct, or an error.

func (*CloudWatchWriter) Close

func (c *CloudWatchWriter) Close()

Close blocks until the writer has completed writing the logs to CloudWatch.

func (*CloudWatchWriter) SetBatchInterval

func (c *CloudWatchWriter) SetBatchInterval(interval time.Duration) error

SetBatchInterval sets the maximum time between batches of logs sent to CloudWatch.

func (*CloudWatchWriter) SetErrorHandler

func (c *CloudWatchWriter) SetErrorHandler(handler func(error))

SetErrorHandler adds a function to be run every time there is an error sending logs to CloudWatch.

func (*CloudWatchWriter) Write

func (c *CloudWatchWriter) Write(log []byte) (int, error)

Write implements the io.Writer interface.