Initial commit

Author: prozz

README.md

@@ -1,2 +1,20 @@
 # aws-embedded-metrics-golang
-Go implementation of AWS CloudWatch Embedded Metric Format
+
+Golang 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 calls as it just logs JSON to stdout
+- built in support for Lambda functions default dimensions and properties (happy to accept PR for EC2 support)
+- no need for defining additional dependencies (or mocks in tests) to report metrics from inside your code
+
+Examples:
+```
+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("commander", "Muldrotha")).
+    MetricAs("wins", 1499, emf.Count).Log()
+```
+

emf/emf.go

@@ -0,0 +1,24 @@
+// 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.
+type Metadata struct {
+	Timestamp int64             `json:"Timestamp"`
+	Metrics   []MetricDirective `json:"CloudWatchMetrics"`
+}
+
+// MetricDirective struct as defined in AWS Embedded Metrics Format spec.
+type MetricDirective struct {
+	Namespace  string             `json:"Namespace"`
+	Dimensions []DimensionSet     `json:"Dimensions"`
+	Metrics    []MetricDefinition `json:"Metrics"`
+}
+
+// DimensionSet as defined in AWS Embedded Metrics Format spec.
+type DimensionSet []string
+
+// MetricDefinition struct as defined in AWS Embedded Metrics Format spec.
+type MetricDefinition struct {
+	Name string         `json:"Name"`
+	Unit MetricUnit `json:"Unit,omitempty"`
+}

emf/logger.go

@@ -0,0 +1,224 @@
+package emf
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+)
+
+// Logger for metrics with default Context.
+type Logger struct {
+	out            io.Writer
+	timestamp      int64
+	defaultContext Context
+	contexts       []*Context
+	values         map[string]interface{}
+}
+
+// Context gives ability to add another MetricDirective section for Logger.
+type Context struct {
+	metricDirective MetricDirective
+	values          map[string]interface{}
+}
+
+// New creates logger printing to os.Stdout, perfect for Lambda functions.
+func New() *Logger {
+	return NewFor(os.Stdout)
+}
+
+// NewFor creates logger printing to any suitable writer.
+func NewFor(out io.Writer) *Logger {
+	values := make(map[string]interface{})
+
+	// set default properties for lambda function
+	fnName := os.Getenv("AWS_LAMBDA_FUNCTION_NAME")
+	if fnName != "" {
+		values["executionEnvironment"] = os.Getenv("AWS_EXECUTION_ENV")
+		values["memorySize"] = os.Getenv("AWS_LAMBDA_FUNCTION_MEMORY_SIZE")
+		values["functionVersion"] = os.Getenv("AWS_LAMBDA_FUNCTION_VERSION")
+		values["logStreamId"] = os.Getenv("AWS_LAMBDA_LOG_STREAM_NAME")
+	}
+
+	// only collect traces which have been sampled
+	amznTraceID := os.Getenv("_X_AMZN_TRACE_ID")
+	if strings.Contains(amznTraceID, "Sampled=1") {
+		values["traceId"] = amznTraceID
+	}
+
+	return &Logger{
+		out:            out,
+		defaultContext: newContext(values),
+		values:         values,
+		timestamp:      time.Now().UnixNano() / int64(time.Millisecond),
+	}
+}
+
+// Dimension helps builds DimensionSet.
+type Dimension struct {
+	Key, Value string
+}
+
+// NewDimension creates Dimension from key/value pair.
+func NewDimension(key, value string) Dimension {
+	return Dimension{
+		Key:   key,
+		Value: value,
+	}
+}
+
+// Namespace sets namespace on default context.
+func (l *Logger) Namespace(namespace string) *Logger {
+	l.defaultContext.Namespace(namespace)
+	return l
+}
+
+// Property sets property.
+func (l *Logger) Property(key, value string) *Logger {
+	l.values[key] = value
+	return l
+}
+
+// Dimension adds single dimension on default context.
+func (l *Logger) Dimension(key, value string) *Logger {
+	l.defaultContext.metricDirective.Dimensions = append(
+		l.defaultContext.metricDirective.Dimensions, DimensionSet{key})
+	l.values[key] = value
+	return l
+}
+
+// DimensionSet adds multiple dimensions on default context.
+func (l *Logger) DimensionSet(dimensions ...Dimension) *Logger {
+	var set DimensionSet
+	for _, d := range dimensions {
+		set = append(set, d.Key)
+		l.values[d.Key] = d.Value
+	}
+	l.defaultContext.metricDirective.Dimensions = append(
+		l.defaultContext.metricDirective.Dimensions, set)
+	return l
+}
+
+// Metric puts int metric on default context.
+func (l *Logger) Metric(name string, value int) *Logger {
+	l.defaultContext.put(name, value, None)
+	return l
+}
+
+// MetricFloat puts float metric on default context.
+func (l *Logger) MetricFloat(name string, value float64) *Logger {
+	l.defaultContext.put(name, value, None)
+	return l
+}
+
+// MetricAs puts int metric with MetricUnit on default context.
+func (l *Logger) MetricAs(name string, value int, unit MetricUnit) *Logger {
+	l.defaultContext.put(name, value, unit)
+	return l
+}
+
+// MetricFloatAs puts float metric with MetricUnit on default context.
+func (l *Logger) MetricFloatAs(name string, value float64, unit MetricUnit) *Logger {
+	l.defaultContext.put(name, value, unit)
+	return l
+}
+
+// Log prints all Contexts and metric values to chosen output in Embedded Metric Format.
+func (l *Logger) Log() {
+	var metrics []MetricDirective
+	if len(l.defaultContext.metricDirective.Metrics) > 0 {
+		metrics = append(metrics, l.defaultContext.metricDirective)
+	}
+	for _, v := range l.contexts {
+		// TODO check if not empty as above?
+		metrics = append(metrics, v.metricDirective)
+	}
+	l.values["_aws"] = Metadata{
+		Timestamp: l.timestamp,
+		Metrics:   metrics,
+	}
+	buf, _ := json.Marshal(l.values)
+	_, _ = fmt.Fprintln(l.out, string(buf))
+}
+
+// NewContext creates new context for given logger.
+func (l *Logger) NewContext() *Context {
+	c := newContext(l.values)
+	l.contexts = append(l.contexts, &c)
+	return &c
+}
+
+// Namespace sets namespace on given context.
+func (c *Context) Namespace(namespace string) *Context {
+	c.metricDirective.Namespace = namespace
+	return c
+}
+
+// Dimension adds single dimension on given context.
+func (c *Context) Dimension(key, value string) *Context {
+	c.metricDirective.Dimensions = append(c.metricDirective.Dimensions, DimensionSet{key})
+	c.values[key] = value
+	return c
+}
+
+// DimensionSet adds multiple dimensions on given context.
+func (c *Context) DimensionSet(dimensions ...Dimension) *Context {
+	var set DimensionSet
+	for _, d := range dimensions {
+		set = append(set, d.Key)
+		c.values[d.Key] = d.Value
+	}
+	c.metricDirective.Dimensions = append(c.metricDirective.Dimensions, set)
+	return c
+}
+
+// Metric puts int metric on given context.
+func (c *Context) Metric(name string, value int) *Context {
+	return c.put(name, value, None)
+}
+
+// MetricFloat puts float metric on given context.
+func (c *Context) MetricFloat(name string, value float64) *Context {
+	return c.put(name, value, None)
+}
+
+// MetricAs puts int metric with MetricUnit on given context.
+func (c *Context) MetricAs(name string, value int, unit MetricUnit) *Context {
+	return c.put(name, value, unit)
+}
+
+// MetricFloatAs puts float metric with MetricUnit on given context.
+func (c *Context) MetricFloatAs(name string, value float64, unit MetricUnit) *Context {
+	return c.put(name, value, unit)
+}
+
+func newContext(values map[string]interface{}) Context {
+	var defaultDimensions []DimensionSet
+
+	// set default dimensions for lambda function
+	fnName := os.Getenv("AWS_LAMBDA_FUNCTION_NAME")
+	if fnName != "" {
+		defaultDimensions = []DimensionSet{{"ServiceName", "ServiceType"}}
+		values["ServiceType"] = "AWS::Lambda::Function"
+		values["ServiceName"] = fnName
+	}
+
+	return Context{
+		metricDirective: MetricDirective{
+			Namespace:  "aws-embedded-metrics",
+			Dimensions: defaultDimensions,
+		},
+		values: values,
+	}
+}
+
+func (c *Context) put(name string, value interface{}, unit MetricUnit) *Context {
+	c.metricDirective.Metrics = append(c.metricDirective.Metrics, MetricDefinition{
+		Name: name,
+		Unit: unit,
+	})
+	c.values[name] = value
+	return c
+}