Allow customization of the logger with NewWith

Author: harrisonhjones

.gitignore

@@ -14,4 +14,5 @@
 # Dependency directories (remove the comment below to include it)
 # vendor/
 
+# IDE artifacts
 .idea/

README.md

@@ -6,6 +6,7 @@
 Go implementation of AWS CloudWatch [Embedded Metric Format](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html)
 
 It's aim is to simplify reporting metrics to CloudWatch:
+
 - using EMF avoids additional HTTP API calls to CloudWatch as metrics are logged in JSON format to stdout
 - no need for additional dependencies in your services (or mocks in tests) to report metrics from inside your code
 - built in support for default dimensions and properties for Lambda functions
@@ -14,27 +15,38 @@ It's aim is to simplify reporting metrics to CloudWatch:
 Supports namespaces, setting dimensions and properties as well as different contexts (at least partially).
 
 Usage:
+
 ```
 emf.New().Namespace("mtg").Metric("totalWins", 1500).Log()
 
 emf.New().Dimension("colour", "red").
     MetricAs("gameLength", 2, emf.Seconds).Log()
 
 emf.New().DimensionSet(
-        emf.NewDimension("format", "edh"), 
+        emf.NewDimension("format", "edh"),
         emf.NewDimension("commander", "Muldrotha")).
     MetricAs("wins", 1499, emf.Count).Log()
 ```
 
 You may also use the lib together with `defer`.
+
 ```
 m := emf.New() // sets up whatever you fancy here
 defer m.Log()
 
 // any reporting metrics calls
 ```
 
+Customizing the logger:
+```
+emf.NewWith(
+    emf.WithWriter(os.Stderr), // Log to stderr.
+    emf.WithTimestamp(time.Now().Add(-time.Hour)), // Record past metrics.
+)
+```
+
 Functions for reporting metrics:
+
 ```
 func Metric(name string, value int)
 func Metrics(m map[string]int)
@@ -48,6 +60,7 @@ func MetricsFloatAs(m map[string]float64, unit MetricUnit)
 ```
 
 Functions for setting up dimensions:
+
 ```
 func Dimension(key, value string)
 func DimensionSet(dimensions ...Dimension) // use `func NewDimension` for creating one

emf/emf.go

@@ -1,4 +1,4 @@
-// Spec available here: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html
+// Package emf implements the spec available here: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html
 package emf
 
 // Metadata struct as defined in AWS Embedded Metrics Format spec.

emf/logger.go

@@ -24,13 +24,29 @@ type Context struct {
 	values          map[string]interface{}
 }
 
-// New creates logger printing to os.Stdout, perfect for Lambda functions.
-func New() *Logger {
-	return NewFor(os.Stdout)
+// NewOption defines a function that can be used to customize a logger.
+type NewOption func(l *Logger)
+
+// WithWriter customizes the writer used by a logger.
+func WithWriter(w io.Writer) NewOption {
+	return func(l *Logger) {
+		l.out = w
+	}
 }
 
-// NewFor creates logger printing to any suitable writer.
-func NewFor(out io.Writer) *Logger {
+// WithTimestamp customizes the timestamp used by a logger.
+func WithTimestamp(t time.Time) NewOption {
+	return func(l *Logger) {
+		l.timestamp = t.UnixNano() / int64(time.Millisecond)
+	}
+}
+
+// NewWith creates logger with reasonable defaults for Lambda functions:
+// - Prints to os.Stdout.
+// - Context based on Lambda environment variables.
+// - Timestamp set to the time when NewWith was called.
+// Specify NewOptions to customize the logger.
+func NewWith(opts ...NewOption) *Logger {
 	values := make(map[string]interface{})
 
 	// set default properties for lambda function
@@ -48,12 +64,32 @@ func NewFor(out io.Writer) *Logger {
 		values["traceId"] = amznTraceID
 	}
 
-	return &Logger{
-		out:            out,
+	// create a default logger
+	l := &Logger{
+		out:            os.Stdout,
 		defaultContext: newContext(values),
 		values:         values,
 		timestamp:      time.Now().UnixNano() / int64(time.Millisecond),
 	}
+
+	// apply any options
+	for _, opt := range opts {
+		opt(l)
+	}
+
+	return l
+}
+
+// New creates logger printing to os.Stdout, perfect for Lambda functions.
+// Deprecated: use NewWith instead.
+func New() *Logger {
+	return NewWith(WithWriter(os.Stdout))
+}
+
+// NewFor creates logger printing to any suitable writer.
+// Deprecated: use NewWith and WithWriter instead.
+func NewFor(out io.Writer) *Logger {
+	return NewWith(WithWriter(out))
 }
 
 // Dimension helps builds DimensionSet.
@@ -129,7 +165,7 @@ func (l *Logger) MetricAs(name string, value int, unit MetricUnit) *Logger {
 	return l
 }
 
-// Metrics puts all of the int metrics with MetricUnit on default context.
+// MetricsAs puts all of the int metrics with MetricUnit on default context.
 func (l *Logger) MetricsAs(m map[string]int, unit MetricUnit) *Logger {
 	for name, value := range m {
 		l.defaultContext.put(name, value, unit)

emf/logger_internal_test.go

@@ -0,0 +1,71 @@
+package emf
+
+import (
+	"fmt"
+	"os"
+	"testing"
+	"time"
+)
+
+func TestNewWith(t *testing.T) {
+	tcs := []struct {
+		name     string
+		opts     []NewOption
+		expected *Logger
+	}{
+		{
+			name: "default",
+			expected: &Logger{
+				out:       os.Stdout,
+				timestamp: time.Now().UnixNano() / int64(time.Millisecond),
+			},
+		},
+		{
+			name: "with options",
+			opts: []NewOption{
+				WithWriter(os.Stderr),
+				WithTimestamp(time.Now().Add(time.Hour)),
+			},
+			expected: &Logger{
+				out:       os.Stderr,
+				timestamp: time.Now().Add(time.Hour).UnixNano() / int64(time.Millisecond),
+			},
+		},
+	}
+
+	for _, tc := range tcs {
+		t.Run(tc.name, func(t *testing.T) {
+			actual := NewWith(tc.opts...)
+			if err := loggersEqual(actual, tc.expected); err != nil {
+				t.Errorf("logger does not match: %v", err)
+			}
+		})
+	}
+
+}
+
+// loggersEqual returns a non-nil error if the loggers do not match.
+// Currently it only checks that the loggers' output writer and timestamp match.
+// TODO: expand the checks here as more NewOptions are added.
+func loggersEqual(actual, expected *Logger) error {
+	if actual.out != expected.out {
+		return fmt.Errorf("output does not match")
+	}
+
+	if err := approxInt64(actual.timestamp, expected.timestamp, 100 /* ms */); err != nil {
+		return fmt.Errorf("timestamp %v", err)
+	}
+
+	return nil
+}
+
+func approxInt64(actual, expected, tolerance int64) error {
+	diff := expected - actual
+	if diff < 0 {
+		diff = -diff
+	}
+	if diff > tolerance {
+		return fmt.Errorf("value %v is out of tolerance %v±%v", actual, expected, tolerance)
+	}
+	return nil
+}