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 ¶
Examples ¶
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 ¶
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 ¶
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()
}
Output:
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 ¶
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)
Source Files