wflambda

README

wavefront-lambda-go

A Go wrapper for AWS Lambda so you can monitor everything from your Wavefront dashboard.

Installation

Using go get

go get github.com/retgits/wavefront-lambda-go

Prerequisites

• Go (at least Go 1.12)
• A Wavefront API token

Basic Usage

To let your Lambda functions send metrics to Wavefront, you'll need to set two environment variables, import this module, and wrap your AWS Lambda handler function with wfAgent.WrapHandler(handler). The environment variables you'll need to set are:

• WAVEFRONT_URL: The URL of your Wavefront instance (like, https://myinstance.wavefront.com).
• WAVEFRONT_API_TOKEN: Your Wavefront API token (see the docs how to create an API token).

package main

import (
	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
	wflambda "github.com/retgits/wavefront-lambda-go" // Import this library
)

var wfAgent = wflambda.NewWavefrontAgent(&wflambda.WavefrontConfig{})

func handler() (string, error){
	return "Hello World", nil
}

func main() {
	// Wrap the handler with wfAgent.WrapHandler()
	lambda.Start(wfAgent.WrapHandler(handler))
}

Configuration

The wfAgent variable in the previous sample can be configured using both environment variables, as well as values passed into it using the WavefrontConfig struct. If both WavefrontConfig and environment variables have a value for a specific setting, the environment variable takes precedence. The configuration options you can set are:

• Enabled (*bool): Enabled indicates whether metrics are sent to Wavefront. The environment variable WAVEFRONT_ENABLED is also used for this setting.
• Server (*string): Wavefront URL of the form https://<INSTANCE>.wavefront.com. The environment variable WAVEFRONT_URL is also used for this setting.
• Token (*string): Wavefront API token with direct data ingestion permission. The environment variable WAVEFRONT_TOKEN is also used for this setting.
• BatchSize (*int): Max batch of data sent per flush interval. The environment variable WAVEFRONT_BATCH_SIZE is also used for this setting.
• MaxBufferSize (*int): Max size of internal buffers beyond which received data is dropped. The environment variable WAVEFRONT_MAX_BUFFER_SIZE is also used for this setting.
• PointTags (map[string]string): Map of Key-Value pairs (strings) associated with each data point sent to Wavefront.

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.

Standard Point Tags

The below point tags are automatically added to all data sent to Wavefront. You can add more point tags, by passing in a map[string]string when you create a new Wavefront Agent.

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)

Custom Point Tags

While all metrics emitted to Wavefront have the Standard Point Tags mentioned above, you can add custom point tags either while instantiating the agent or inside your handler.

package main

import (
	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
	wflambda "github.com/retgits/wavefront-lambda-go" // Import this library
)

// Create a map to hold additional tags.
// All standard tags are sent to Wavefront too.
var tags = map[string]string{
	"MyTag": "NewTag",
}

var wfAgent = wflambda.NewWavefrontAgent(&wflambda.WavefrontConfig{
	PointTags: tags,
})

func handler() (string, error){
	// You also can add additional point tags from inside your handler function.
	// All standard tags are sent to Wavefront too.
	wfAgent.WavefrontConfig.PointTags["NewPointTag"] = "MyCustomTag"

	return "Hello World", nil
}

func main() {
	// Wrap the handler with wfAgent.WrapHandler()
	lambda.Start(wfAgent.WrapHandler(handler))
}

Metrics

Standard Metrics

The Wavefront Agent will send a set of default metrics to Wavefront when enabled. The metrics reported are:

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	Metric	Execution time of the Lambda handler function in milliseconds.
aws.lambda.wf.mem.total	Metric	The total memory available to the Lambda function in megabytes.
aws.lambda.wf.mem.used	Metric	The memory used by the Lambda function in megabytes.
aws.lambda.wf.mem.percentage	Metric	The percentage of memory used by the Lambda function.

Custom Metrics

You can send custom business metrics to Wavefront using the RegisterMetric() or RegisterCounter() methods. Counters are values that are aggregated at the Wavefront server (like the number of invocations and metrics are pretty much every other numerical value you want to send in.

package main

import (
	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
	wflambda "github.com/retgits/wavefront-lambda-go" // Import this library
)

var wfAgent = wflambda.NewWavefrontAgent(&wflambda.WavefrontConfig{})

func handler() (string, error){
	// Register a new Delta Counter
	wfAgent.RegisterCounter("MyAwesomeCounter", float64(1))

	// Register a new Metric
	wfAgent.RegisterCounter("MeaningOfLife", float64(42))

	return "Hello World", nil
}

func main() {
	// Wrap the handler with wfAgent.WrapHandler()
	lambda.Start(wfAgent.WrapHandler(handler))
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

See the LICENSE file in the repository

Documentation

Index

• type HandlerWrapper
  • func NewHandlerWrapper(handler interface{}, wa *WavefrontAgent) *HandlerWrapper
  • func (hw *HandlerWrapper) Invoke(ctx context.Context, payload interface{}) (response interface{}, err error)
• type WavefrontAgent
  • func NewWavefrontAgent(w *WavefrontConfig) *WavefrontAgent
  • func (wa *WavefrontAgent) RegisterCounter(name string, value float64)
  • func (wa *WavefrontAgent) RegisterMetric(name string, value float64)
  • func (wa *WavefrontAgent) Wrapper(handler interface{}) interface{}
• type WavefrontConfig

Types

type HandlerWrapper

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

HandlerWrapper is the Wavefront Agent handler wrapper

func NewHandlerWrapper

func NewHandlerWrapper(handler interface{}, wa *WavefrontAgent) *HandlerWrapper

NewHandlerWrapper creates a new wrapper containing the Wavefront Agent which will send metrics at the end of the execution of the Lambda function and a wrapper handler

func (*HandlerWrapper) Invoke

func (hw *HandlerWrapper) Invoke(ctx context.Context, payload interface{}) (response interface{}, err error)

Invoke calls the handler, and serializes the response. If the underlying handler returned an error, or an error occurs during serialization, error is returned.

type WavefrontAgent

type WavefrontAgent struct {
	*WavefrontConfig
	// contains filtered or unexported fields
}

WavefrontAgent is the agent instance that communicates with Wavefront.

func NewWavefrontAgent

func NewWavefrontAgent(w *WavefrontConfig) *WavefrontAgent

NewWavefrontAgent returns a new agent.

func (*WavefrontAgent) RegisterCounter

func (wa *WavefrontAgent) RegisterCounter(name string, value float64)

RegisterCounter adds a new DeltaCounter to be sent to Wavefront

func (*WavefrontAgent) RegisterMetric

func (wa *WavefrontAgent) RegisterMetric(name string, value float64)

RegisterMetric adds a new metric to be sent to Wavefront

func (*WavefrontAgent) Wrapper

func (wa *WavefrontAgent) Wrapper(handler interface{}) interface{}

Wrapper wraps the handler

type WavefrontConfig

type WavefrontConfig struct {
	// Enabled indicates whether metrics are sent to Wavefront
	Enabled *bool
	// Wavefront URL of the form https://<INSTANCE>.wavefront.com.
	Server *string
	// Wavefront API token with direct data ingestion permission.
	Token *string
	// Max batch of data sent per flush interval.
	BatchSize *int
	// Max size of internal buffers beyond which received data is dropped.
	MaxBufferSize *int
	// Map of Key-Value pairs (strings) associated with each data point sent to Wavefront.
	PointTags map[string]string
}

WavefrontConfig configures the direct ingestion sender to Wavefront.