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()
In the call graph viewer below, each node
is a function belonging to this package
and its children are the functions it
calls—perhaps dynamically.
The root nodes are the entry points of the
package: functions that may be called from
outside the package.
There may be non-exported or anonymous
functions among them if they are called
dynamically from another package.
Click a node to visit that function's source code.
From there you can visit its callers by
clicking its declaring func
token.
Functions may be omitted if they were
determined to be unreachable in the
particular programs or tests that were
analyzed.
Constants ¶
const (
DefaultPort = "31000"
DefaultHost = "127.0.0.1"
)
const (
APICallMetricHandlerName = "awscsm.SendAPICallMetric"
APICallAttemptMetricHandlerName = "awscsm.SendAPICallAttemptMetric"
)
Client side metric handler names
Variables ¶
var (
MetricsChannelSize = 100
)
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".
type Reporter struct {
}
Reporter will gather metrics of API requests made and
send those metrics to the CSM endpoint.
func Get() *Reporter
Get will return a reporter if one exists, if one does not exist, nil will
be returned.
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
Code:
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"),
})
r.Pause()
client.GetObject(&s3.GetObjectInput{
Bucket: aws.String("bucket"),
Key: aws.String("key"),
})
r.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 (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.