csm

Documentation

Overview

Package csm provides the Client Side Monitoring (CSM) client which enables sending metrics via UDP connection to the CSM agent. This package provides control options, and configuration for the CSM client. The client can be controlled manually, or automatically via the SDK's Session configuration.

Enabling CSM client via SDK's Session configuration

The CSM client can be enabled automatically via SDK's Session configuration. The SDK's session configuration enables the CSM client if the AWS_CSM_PORT environment variable is set to a non-empty value.

The configuration options for the CSM client via the SDK's session configuration are:

• AWS_CSM_PORT=<port number> The port number the CSM agent will receive metrics on.

• AWS_CSM_HOST=<hostname or ip> The hostname, or IP address the CSM agent will receive metrics on. Without port number.

Manually enabling the CSM client

The CSM client can be started, paused, and resumed manually. The Start function will enable the CSM client to publish metrics to the CSM agent. It is safe to call Start concurrently, but if Start is called additional times with different ClientID or address it will panic.

r, err := csm.Start("clientID", ":31000")
if err != nil {
	panic(fmt.Errorf("failed starting CSM:  %v", err))
}

When controlling the CSM client manually, you must also inject its request handlers into the SDK's Session configuration for the SDK's API clients to publish metrics.

sess, err := session.NewSession(&aws.Config{})
if err != nil {
	panic(fmt.Errorf("failed loading session: %v", err))
}

// Add CSM client's metric publishing request handlers to the SDK's
// Session Configuration.
r.InjectHandlers(&sess.Handlers)

Controlling CSM client

Once the CSM client has been enabled the Get function will return a Reporter value that you can use to pause and resume the metrics published to the CSM agent. If Get function is called before the reporter is enabled with the Start function or via SDK's Session configuration nil will be returned.

The Pause method can be called to stop the CSM client publishing metrics to the CSM agent. The Continue method will resume metric publishing.

// Get the CSM client Reporter.
r := csm.Get()

// Will pause monitoring
r.Pause()
resp, err = client.GetObject(&s3.GetObjectInput{
	Bucket: aws.String("bucket"),
	Key: aws.String("key"),
})

// Resume monitoring
r.Continue()

Index

• Constants
• Variables
• func AddressWithDefaults(host, port string) string
• type Reporter
  • func Get() *Reporter
  • func Start(clientID string, url string) (*Reporter, error)
  • func (rep *Reporter) Continue()
  • func (rep *Reporter) InjectHandlers(handlers *request.Handlers)
  • func (rep *Reporter) Pause()

Examples

• Start

Constants

const (
	// DefaultPort is used when no port is specified.
	DefaultPort = "31000"

	// DefaultHost is the host that will be used when none is specified.
	DefaultHost = "127.0.0.1"
)

const (
	APICallMetricHandlerName        = "awscsm.SendAPICallMetric"
	APICallAttemptMetricHandlerName = "awscsm.SendAPICallAttemptMetric"
)

Client side metric handler names

Variables

var (
	// MetricsChannelSize of metrics to hold in the channel
	MetricsChannelSize = 100
)

Functions

func AddressWithDefaults

func AddressWithDefaults(host, port string) string

AddressWithDefaults returns a CSM address built from the host and port values. If the host or port is not set, default values will be used instead. If host is "localhost" it will be replaced with "127.0.0.1".

Types

type Reporter

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

Reporter will gather metrics of API requests made and send those metrics to the CSM endpoint.

func Get

func Get() *Reporter

Get will return a reporter if one exists, if one does not exist, nil will be returned.

func Start

func Start(clientID string, url string) (*Reporter, error)

Start will start a long running go routine to capture client side metrics. Calling start multiple time will only start the metric listener once and will panic if a different client ID or port is passed in.

r, err := csm.Start("clientID", "127.0.0.1:31000")
if err != nil {
	panic(fmt.Errorf("expected no error, but received %v", err))
}
sess := session.NewSession()
r.InjectHandlers(sess.Handlers)

svc := s3.New(sess)
out, err := svc.GetObject(&s3.GetObjectInput{
	Bucket: aws.String("bucket"),
	Key: aws.String("key"),
})

Example

package main

import (
	"fmt"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/csm"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/s3"
)

func main() {
	r, err := csm.Start("clientID", ":31000")
	if err != nil {
		panic(fmt.Errorf("failed starting CSM:  %v", err))
	}

	sess, err := session.NewSession(&aws.Config{})
	if err != nil {
		panic(fmt.Errorf("failed loading session: %v", err))
	}

	r.InjectHandlers(&sess.Handlers)

	client := s3.New(sess)
	client.GetObject(&s3.GetObjectInput{
		Bucket: aws.String("bucket"),
		Key:    aws.String("key"),
	})

	// Pauses monitoring
	r.Pause()
	client.GetObject(&s3.GetObjectInput{
		Bucket: aws.String("bucket"),
		Key:    aws.String("key"),
	})

	// Resume monitoring
	r.Continue()
}

func (*Reporter) Continue

func (rep *Reporter) Continue()

Continue will reopen the metric channel and allow for monitoring to be resumed. It is safe to call concurrently with other calls to Continue, but if called concurently with Pause can lead to unexpected state.

func (*Reporter) InjectHandlers

func (rep *Reporter) InjectHandlers(handlers *request.Handlers)

InjectHandlers will will enable client side metrics and inject the proper handlers to handle how metrics are sent.

InjectHandlers is NOT safe to call concurrently. Calling InjectHandlers multiple times may lead to unexpected behavior, (e.g. duplicate metrics).

// Start must be called in order to inject the correct handlers
r, err := csm.Start("clientID", "127.0.0.1:8094")
if err != nil {
	panic(fmt.Errorf("expected no error, but received %v", err))
}

sess := session.NewSession()
r.InjectHandlers(&sess.Handlers)

// create a new service client with our client side metric session
svc := s3.New(sess)

func (*Reporter) Pause

func (rep *Reporter) Pause()

Pause will pause the metric channel preventing any new metrics from being added. It is safe to call concurrently with other calls to Pause, but if called concurently with Continue can lead to unexpected state.