package csm

Import Path
	github.com/aws/aws-sdk-go/aws/csm (on go.dev)

Dependency Relation
	imports 11 packages, and imported by one package


Involved Source Files

	
		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()

	      enable.go
	      metric.go
	      metric_chan.go
	      metric_exception.go
	      reporter.go


Code Examples

	
		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()
		}




Package-Level Type Names (total 8, in which 1 are exported)


	/* sort exporteds by:  |  */
	
		Reporter will gather metrics of API requests made and
		send those metrics to the CSM endpoint.

		
			
		
			
				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.

			
				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)

			
				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.

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


	


Package-Level Functions (total 9, in which 3 are exported)


	
		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".


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


	
		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"),
				})


	


Package-Level Variables (total 3, in which 1 are exported)


	
		MetricsChannelSize of metrics to hold in the channel


	


Package-Level Constants (total 6, in which 4 are exported)


	
		Client side metric handler names


	
		Client side metric handler names


	
		DefaultHost is the host that will be used when none is specified.


	
		DefaultPort is used when no port is specified.