logruscloudwatch

README

Logrus CloudWatch

A logrus hook for sending log events to AWS CloudWatch.

Install

go get github.com/innix/logrus-cloudwatch

Usage

This hook uses the AWS SDK for Go V2. If your project is using the legacy V1 SDK, you can still use this hook but it means your project will have a dependency on both versions of the SDK.

package main

import (
	"context"
	"time"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs"
	"github.com/innix/logrus-cloudwatch"
	log "github.com/sirupsen/logrus"
)

func main() {
	// Setup AWS SDK client.
	cfg, err := config.LoadDefaultConfig(context.Background())
	if err != nil {
		log.Fatalf("Could not load AWS config: %v", err)
	}
	client := cloudwatchlogs.NewFromConfig(cfg)

	// Create and register hook.
	hook, err := logruscloudwatch.New(client, nil)
	if err != nil {
		log.Fatalf("Could not create CloudWatch hook: %v", err)
	}
	log.AddHook(hook)

	// Do some logging.
	for i := 0; i < 10; i++ {
		log.WithField("counter", i).Info("Incremented counter.")
		time.Sleep(time.Second * 2)
	}

	// Ensure all logs are sent to CloudWatch before the program exits.
	<-hook.Stop()
}

Specify log group name

The Options struct contains fields for configuring how the hook works, including which CloudWatch log group to write to.

// Create and register hook.
hook, err := logruscloudwatch.New(client, &logruscloudwatch.Options{
    LogGroupName: "/my-project/development",
})
if err != nil {
    log.Fatalf("Could not create CloudWatch hook: %v", err)
}
log.AddHook(hook)

Test

To run the unit tests:

go test ./...

Lint

The project uses golangci-lint for linting. See the .golangci.yml file for configured rules. To run the linter:

golangci-lint run

Documentation

Index

• Variables
• type FieldMap
• type Hook
  • func New(client *cloudwatchlogs.Client, o *Options) (*Hook, error)
  • func (h *Hook) Fire(e *logrus.Entry) error
  • func (h *Hook) Levels() []logrus.Level
  • func (h *Hook) Stop() <-chan struct{}
• type LogFormatter
  • func (f *LogFormatter) Format(entry *logrus.Entry) ([]byte, error)
• type Options

Variables

var ErrStopped = errors.New("logruscloudwatch: hook has been stopped")

ErrStopped is raised when attempting to use the hook after if has been stopped.

Types

type FieldMap

type FieldMap map[fieldKey]string

FieldMap allows customization of the key names for default fields.

type Hook

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

Hook is a logrus.Hook that sends log events to AWS CloudWatch.

func New

func New(client *cloudwatchlogs.Client, o *Options) (*Hook, error)

New creates a new Logrus hook that sends log events to AWS CloudWatch. If the Options value is nil then the default values will be used. See the Options struct for more information on default values.

func (*Hook) Fire

func (h *Hook) Fire(e *logrus.Entry) error

Fire takes a log entry and sends it to CloudWatch. Log entries are sent in batches at fixed intervals, so they might not be immediately sent to CloudWatch when this method is called.

func (*Hook) Levels

func (h *Hook) Levels() []logrus.Level

Levels defines the level of log events that will be sent to CloudWatch. Any log events that is not one of these levels is simply discarded.

func (*Hook) Stop

func (h *Hook) Stop() <-chan struct{}

Stop stops the hook from accepting new log entries and begins a graceful shutdown. It is important to call this method once you're finished using the hook because it releases a background goroutine.

It is recommended to call this method at the end of your program's shutdown procedure, when no further logging will occur. If the hook is stopped but is still registered to a logger, any log entries the hook receives will be ignored. If the Options.ReturnErrorIfStopped field was set to true, then the Fire method will return an ErrStopped error. If set to false, it returns nil.

Stop returns a channel that closes when all remaining buffered log events have been sent to CloudWatch. If it's essential that all log entries are uploaded, call this method when your program is shutting down and wait for the channel to close.

type LogFormatter

type LogFormatter struct {
	// TimestampFormat sets the format used for marshaling timestamps.
	// The format to use is the same than for time.Format or time.Parse from the standard
	// library.
	// The standard Library already provides a set of predefined format.
	TimestampFormat string

	// DisableTimestamp allows disabling automatic timestamps in output.
	DisableTimestamp bool

	// DisableHTMLEscape allows disabling HTML escaping in output.
	DisableHTMLEscape bool

	// DataKey allows users to put all the log entry parameters into a nested dictionary at a given key.
	DataKey string

	// FieldMap allows users to customize the names of keys for default fields.
	// As an example:
	// formatter := &LogFormatter{
	//   	FieldMap: FieldMap{
	// 		 FieldKeyTime:  "@timestamp",
	// 		 FieldKeyLevel: "@level",
	// 		 FieldKeyMsg:   "@message",
	// 		 FieldKeyFunc:  "@caller",
	//    },
	// }
	FieldMap FieldMap

	// CallerPrettyfier can be set by the user to modify the content
	// of the function and file keys in the json data when ReportCaller is
	// activated. If any of the returned value is the empty string the
	// corresponding key will be removed from json fields.
	CallerPrettyfier func(*runtime.Frame) (function string, file string)

	// PrettyPrint will indent all JSON logs.
	PrettyPrint bool

	// LowerCaseLogLevel allows changing the log level value to lower case.
	LowerCaseLogLevel bool

	// ModifyFields can be set by the user to modify the data before it is marshalled into JSON.
	ModifyFields func(data logrus.Fields)
}

LogFormatter formats logs into CloudWatch-friendly JSON. It is based on logrus.JSONFormatter.

func (*LogFormatter) Format

func (f *LogFormatter) Format(entry *logrus.Entry) ([]byte, error)

Format renders a single log entry.

type Options

type Options struct {

	// Levels is the log levels to send to CloudWatch. If not set, all log levels are sent.
	Levels []logrus.Level

	// Formatter is the log formatter used to serialize the log entry before sending it to
	// CloudWatch. If not set, the default formatter will be used, which is a LogFormatter.
	Formatter logrus.Formatter

	// MaxBatchSize is the maximum number of log events to send to CloudWatch in one batch.
	// If not set, the default value of 500 will be used. The maximum allowed value is 10,000.
	MaxBatchSize int

	// ReturnErrorIfStopped is a flag that determines if the Hook.Fire method returns ErrStopped
	// if it's called after the hook has been stopped. If set to false, the Hook.Fire method just
	// returns nil. The default value is false.
	ReturnErrorIfStopped bool

	// LogGroupName is the name of the CloudWatch log group to write to. If not set, one will
	// be automatically generated. The auto-generated name will be the name of the running binary
	// as returned by os.Executable.
	LogGroupName string

	// LogStreamName is the name of the CloudWatch log stream to write to. If not set, one will
	// be automatically generated. The auto-generated name will consist of the local current
	// datetime, the computer name, and a v4 UUID.
	//
	// Here is an example of an auto-generated stream name:
	//     2021-05-19-17-49-05_INNIX-HOME-LAPTOP_cbd2917a-6d77-4bae-8069-7f38c3034ed3
	LogStreamName string
}

Options is the struct used to configure the hook.