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() Deprecated: aws-sdk-go is deprecated. Use aws-sdk-go-v2. See https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-go-v1-on-july-31-2025/.
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.