Update documentation (#6)

* feat: update docs

* chore: update docs with PR feedback

* fix: update function comment

Author: retgits

.gitignore

@@ -1 +1,42 @@
+# General
 .DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories
+vendor/

README.md

@@ -1,87 +1,86 @@
-# wavefront-lambda-go [![travis build status](https://travis-ci.com/wavefrontHQ/wavefront-lambda-go.svg?branch=master)](https://travis-ci.com/wavefrontHQ/wavefront-lambda-go)
+# wavefront-lambda-go
 
-This is a Wavefront Go wrapper for AWS Lambda to enable reporting standard lambda metrics and custom app metrics directly to wavefront.
+[![travis build status](https://travis-ci.com/wavefrontHQ/wavefront-lambda-go.svg?branch=master)](https://travis-ci.com/wavefrontHQ/wavefront-lambda-go)
+[![Go Report Card](https://goreportcard.com/badge/github.com/wavefrontHQ/wavefront-lambda-go)](https://goreportcard.com/report/github.com/wavefrontHQ/wavefront-lambda-go)
 
-## Requirements
-Go 1.x
+A Go wrapper for AWS Lambda so you can monitor everything from your [Wavefront](https://wavefront.com) dashboard
 
 ## Installation
-```
+
+Using `go get`
+
+```bash
 go get github.com/wavefronthq/wavefront-lambda-go
 ```
 
-## Environment variables
-WAVEFRONT_URL = https://\<INSTANCE>.wavefront.com  
-WAVEFRONT_API_TOKEN = Wavefront API token with Direct Data Ingestion permission.  
-REPORT_STANDARD_METRICS = Set to False or false to not report standard lambda metrics directly to wavefront.  
+## Basic Usage
 
-## Usage
+To connect your Lambda functions to Wavefront, you'll need to set two environment variables, import this module, and wrap your AWS Lambda handler function with `wflambda.Wrapper(handler)`. The environment variables you'll need to set are:
 
-Wrap your AWS Lambda handler function with wavefront_lambda.Wrapper(LambdaHandler).
+* `WAVEFRONT_URL`: The URL of your Wavefront instance (like, `https://myinstance.wavefront.com`).
+* `WAVEFRONT_API_TOKEN`: Your Wavefront API token (see the [docs](https://docs.wavefront.com/wavefront_api.html) how to create an API token).
 
 ```go
 package main
 
 import (
+	"github.com/aws/aws-lambda-go/events"
 	"github.com/aws/aws-lambda-go/lambda"
-	"github.com/rcrowley/go-metrics"
-	"github.com/wavefronthq/go-metrics-wavefront"
-	"github.com/wavefronthq/wavefront-lambda-go"
+	wflambda "github.com/wavefronthq/wavefront-lambda-go" // Import this library
 )
 
-// Lambda handler function that includes the code which will be executed when lambda is invoked.
-func HandleLambdaRequest() {
-	// your code
+func handler() (string, error){
+	return "Hello World", nil
 }
 
 func main() {
-	// Wrap your Lambda Handler Function with wflambda.Wrapper
-	lambda.Start(wflambda.Wrapper(HandleLambdaRequest))
+	// Wrap the handler with wflambda.Wrapper()
+	lambda.Start(wflambda.Wrapper(handler))
 }
 ```
 
-## Standard Lambda Metrics reported by Wavefront Lambda wrapper
+## Standard Point Tags
+
+Point tags are key-value pairs (strings) that are associated with a point. Point tags provide additional context for your data and allow you to fine-tune your queries so the output shows just what you need. The below point tags are sent to Wavefront for each metric.
 
-The Lambda wrapper sends the following standard lambda metrics to wavefront:
+| Point Tag             | Description                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| LambdaArn             | ARN (**Amazon Resource Name**) of the Lambda function.                                     |
+| Region                | AWS Region of the Lambda function.                                                         |
+| accountId             | AWS Account ID from which the Lambda function was invoked.                                 |
+| ExecutedVersion       | The version of Lambda function.                                                            |
+| FunctionName          | The name of Lambda function.                                                               |
+| Resource              | The name and version/alias of Lambda function. (like `DemoLambdaFunc:aliasProd`)           |
+| EventSourceMappings   | AWS Event source mapping Id. (Set in case of Lambda invocation by AWS Poll-Based Services) |
 
-| Metric Name                       |  Type              | Description                                                             |
-| ----------------------------------|:------------------:| ----------------------------------------------------------------------- |
-| aws.lambda.wf.invocations.count   | Delta Counter      | Count of number of lambda function invocations aggregated at the server.|
-| aws.lambda.wf.errors.count        | Delta Counter      | Count of number of errors aggregated at the server.                     |
-| aws.lambda.wf.coldstarts.count    | Delta Counter      | Count of number of cold starts aggregated at the server.                |
-| aws.lambda.wf.duration.value      | Gauge              | Execution time of the Lambda handler function in milliseconds.          |
+## Standard Metrics
 
-The Lambda wrapper adds the following point tags to all metrics sent to wavefront:
+Based on the environment variable `REPORT_STANDARD_METRICS` the wrapper will send standard metrics to Wavefront. Set the variable to to `false` to not send the standard metrics. When the variable is not set, it will use the default value `true`.
 
-| Point Tag             | Description                                                                   |
-| --------------------- | ----------------------------------------------------------------------------- |
-| LambdaArn             | ARN(Amazon Resource Name) of the Lambda function.                             |
-| Region                | AWS Region of the Lambda function.                                            |
-| accountId             | AWS Account ID from which the Lambda function was invoked.                    |
-| ExecutedVersion       | The version of Lambda function.                                               |
-| FunctionName          | The name of Lambda function.                                                  |
-| Resource              | The name and version/alias of Lambda function. (Ex: DemoLambdaFunc:aliasProd) |
-| EventSourceMappings   | AWS Event source mapping Id. (Set in case of Lambda invocation by AWS Poll-Based Services)|
+| Metric Name                       |  Type         | Description                                                             |
+| --------------------------------- | ------------- | ----------------------------------------------------------------------- |
+| aws.lambda.wf.invocations.count   | Delta Counter | Count of number of lambda function invocations aggregated at the server.|
+| aws.lambda.wf.errors.count        | Delta Counter | Count of number of errors aggregated at the server.                     |
+| aws.lambda.wf.coldstarts.count    | Delta Counter | Count of number of cold starts aggregated at the server.                |
+| aws.lambda.wf.duration.value      | Gauge         | Execution time of the Lambda handler function in milliseconds.          |
 
-## Custom Lambda Metrics
+## Custom Metrics
 
-The wavefront Go lambda wrapper reports custom business metrics via API's provided by the [go-metrics-wavefront client] (https://github.com/wavefrontHQ/go-metrics-wavefront).  
-Please refer to the below code sample which shows how you can send custom business metrics to wavefront from your lambda function.
+You can send custom business metrics to Wavefront using the [go-metrics-wavefront](https://github.com/wavefrontHQ/go-metrics-wavefront) client. The below code reports a _counter_, a _delta counter_, and two _gauges_. All metric names should be unique. If you have metrics that you want to track as both _counter_ and _delta counter_, you'll have to add a suffix to one of the metrics. Having the same metric name for any two types of metrics will result in only one time series at the server and thus cause collisions.
 
-### Code Sample
+The code below imported this module and wrapped the _handler_ function argument in _main_ with `wflambda.Wrapper(handler)`. During each execution four metrics are collected and sent to Wavefront with both the [standard point tags](#standard-point-tags) and the point tags created in the handler.
 
 ```go
 package main
 
 import (
 	"github.com/aws/aws-lambda-go/lambda"
 	"github.com/rcrowley/go-metrics"
-	"github.com/wavefronthq/go-metrics-wavefront"
-	"github.com/wavefronthq/wavefront-lambda-go"
+	wavefront "github.com/wavefronthq/go-metrics-wavefront"
+	wflambda "github.com/wavefronthq/wavefront-lambda-go"
 )
 
-// Lambda handler function that includes the code which will be executed when lambda is invoked.
-func HandleLambdaRequest() {
+func handler() {
 	// Point Tags
 	appTags := map[string]string{
 		"key2":   "val1",
@@ -114,10 +113,6 @@ func HandleLambdaRequest() {
 }
 
 func main() {
-	//Wrapping with wflambda.Wrapper
-	lambda.Start(wflambda.Wrapper(HandleLambdaRequest))
+	lambda.Start(wflambda.Wrapper(handler))
 }
 ```
-
-Note: Having the same metric name for any two types of metrics will result in only one time series at the server and thus cause collisions.
-In general, all metric names should be different. In case you have metrics that you want to track as both a Counter and Delta Counter, consider adding a relevant suffix to one of the metrics to differentiate one metric name from another.

handler.go

@@ -6,17 +6,23 @@ import (
 	"reflect"
 )
 
-// Validate the input lambda handler based on source code at
+// validateLambdaHandler validates the lambdaHandler is a valid handler function. When the handler is a valid handler function,
+// the function will check whether one of the arguments is a context. The function returns a non-nil error if lambdaHandler is
+// not a valid handler. When the lambdaHandler is valid, the boolean indicates whether the lambdaHandler has a context parameter.
+// is returned. The code of the function is based on source code at
 // https://github.com/aws/aws-lambda-go/blob/ea03c2814414b2223eff860ed2286a83ed8a195c/lambda/handler.go#L75
 func validateLambdaHandler(lambdaHandler interface{}) (bool, error) {
 	if lambdaHandler == nil {
 		return false, fmt.Errorf("handler is nil")
 	}
 	handlerType := reflect.TypeOf(lambdaHandler)
+
 	// Validate lambdaHandler Kind.
 	if handlerType.Kind() != reflect.Func {
 		return false, fmt.Errorf("handler kind %s is not %s", handlerType.Kind(), reflect.Func)
 	}
+
+	// Check if the lambdaHandler takes a context argument.
 	takesContext, err := validateArguments(handlerType)
 	if err != nil {
 		return false, err
@@ -28,6 +34,11 @@ func validateLambdaHandler(lambdaHandler interface{}) (bool, error) {
 	return takesContext, nil
 }
 
+// validateArguments validates whether the arguments passed as part of the lambdaHandler are valid. A valid lambdaHandler
+// has a maximum of two arguments. When there are two arguments, the first one must be a Context. The function returns
+// true or false depending on whether the lambdaHandler has a context argument. If the arguments are not valid, an error
+// is returned. Detailed information on the valid handler signatures can be found in the AWS Lambda documentation
+// https://docs.aws.amazon.com/lambda/latest/dg/go-programming-model-handler-types.html
 func validateArguments(handler reflect.Type) (bool, error) {
 	handlerTakesContext := false
 	if handler.NumIn() > 2 {
@@ -44,6 +55,11 @@ func validateArguments(handler reflect.Type) (bool, error) {
 	return handlerTakesContext, nil
 }
 
+// validateReturns validates whether the arguments returned by the lambdaHandler are valid or not. A valid lambdaHandler
+// returns a maximum of two arguments. When there are two arguments, the second argument must be of type error. When there
+// is only one argument, that one must be of type error. Detailed information on the valid handler signatures can be found
+// in the AWS Lambda documentation
+// https://docs.aws.amazon.com/lambda/latest/dg/go-programming-model-handler-types.html
 func validateReturns(handler reflect.Type) error {
 	errorType := reflect.TypeOf((*error)(nil)).Elem()
 	if handler.NumOut() > 2 {

reporter.go

@@ -12,21 +12,23 @@ import (
 	"github.com/wavefronthq/go-metrics-wavefront"
 )
 
-// Increment counter if report is true
+// incrementCounter increments the counter by the given value if report is true
 func incrementCounter(counter metrics.Counter, value int64, report bool) {
 	if report {
 		counter.Inc(value)
 	}
 }
 
-// Update gauge value if report is true
+// updateGaugeFloat64 increments the counter by the given value if report is true
 func updateGaugeFloat64(gauge metrics.GaugeFloat64, value float64, report bool) {
 	if report {
 		gauge.Update(value)
 	}
 }
 
-// Register the standard lambda metrics.
+// registerStandardLambdaMetrics creates counters and gauges for the standard AWS Lambda metrics that are reported
+// to Wavefront. Whether or not the metrics are actually sent to Wavefront is determined by the environment variable
+// REPORT_STANDARD_METRICS.
 func registerStandardLambdaMetrics() {
 	// Register cold start counter.
 	csCounter = metrics.NewCounter()
@@ -38,19 +40,19 @@ func registerStandardLambdaMetrics() {
 	invocationsCounterName := wavefront.DeltaCounterName(getStandardLambdaMetricName("invocations"))
 	wavefront.RegisterMetric(invocationsCounterName, invocationsCounter, nil)
 
-	// Register Error counter
+	// Register Error counter.
 	errCounter = metrics.NewCounter()
 	errCounterName := wavefront.DeltaCounterName(getStandardLambdaMetricName("errors"))
 	wavefront.RegisterMetric(errCounterName, errCounter, nil)
 
-	// Register duration gauge
+	// Register duration gauge.
 	durationGauge = metrics.NewGaugeFloat64()
 	wavefront.RegisterMetric(getStandardLambdaMetricName("duration"), durationGauge, nil)
 }
 
-// Method to send all metrics in the registry to wavefront.
+// reportMetrics sends the collected metrics in the registry to Wavefront. With each metric,
+// the point tags listed in the README are sent by the reporter.
 func reportMetrics(ctx context.Context) {
-	// Get standard lambda point tags
 	lc, ok := lambdacontext.FromContext(ctx)
 	if ok {
 		invokedFunctionArn := lc.InvokedFunctionArn
@@ -66,6 +68,7 @@ func reportMetrics(ctx context.Context) {
 			"Region":          splitArn[3],
 			"accountId":       splitArn[4],
 		}
+
 		if splitArn[5] == "function" {
 			hostTags["Resource"] = splitArn[6]
 			if len(splitArn) == 8 {
@@ -90,28 +93,29 @@ func reportMetrics(ctx context.Context) {
 	}
 }
 
-// Util method that returns the standard lambda metric name.
-// Ex:
-// getStandardLambdaMetricName("invocation", true) returns "aws.lambda.wf.invocation_event"
-// getStandardLambdaMetricName("invocations", false) returns "aws.lambda.wf.invocations"
-
+// getStandardLambdaMetricName adds the standard Wavefront prefix (aws.lambda.wf) to the name of the metric and returns
+// the newly created string.
+// for example, getStandardLambdaMetricName("invocations") returns "aws.lambda.wf.invocations"
 func getStandardLambdaMetricName(metric string) string {
-	const metric_prefix string = "aws.lambda.wf."
-	return strings.Join([]string{metric_prefix, metric}, "")
+	const metricPrefix string = "aws.lambda.wf."
+	return strings.Join([]string{metricPrefix, metric}, "")
 }
 
-// Util method to validate the specified environment variables and return if standard lambda Metrics
-// should be collected by the wrapper.
+// getAndValidateLambdaEnvironment validates whether the required environment variables WAVEFRONT_URL and
+// WAVEFRONT_API_TOKEN have been set. If they are not set, the function will panic. The function also checks
+// whether the environment variable REPORT_STANDARD_METRICS has been set to false (it will default to true).
+// to determine if the standard metrics should be reported.
 func getAndValidateLambdaEnvironment() bool {
-	// Validate environment variables required by wavefrontLambda wrapper.
 	server = os.Getenv("WAVEFRONT_URL")
 	if server == "" {
 		log.Panicf("Environment variable WAVEFRONT_URL is not set.")
 	}
+
 	authToken = os.Getenv("WAVEFRONT_API_TOKEN")
 	if authToken == "" {
 		log.Panicf("Environment variable WAVEFRONT_API_TOKEN is not set.")
 	}
+
 	reportStandardLambdaMetrics := os.Getenv("REPORT_STANDARD_METRICS")
 	reportStandardMetrics := true
 	if reportStandardLambdaMetrics == "False" || reportStandardLambdaMetrics == "false" {