AWS SDK for PHP
Developer Guide

Set Up SDK Metrics for the AWS SDK for PHP Version 3

The following steps demonstrate how to set up SDK Metrics for the AWS SDK for PHP. These steps pertain to an Amazon EC2 instance running Amazon Linux for a client application that is using the AWS SDK for PHP. SDK Metrics is also available for your production environments if you enable it while configuring the AWS SDK for PHP.

To use SDK Metrics, run the latest version of the CloudWatch agent. Learn how to Configure the CloudWatch Agent for SDK Metrics in the Amazon CloudWatch User Guide.

For more details about IAM Permissions for SDK Metrics, check out the IAM Permissions for SDK Metrics for AWS SDK for PHP article.

To set up SDK Metrics with the AWS SDK for PHP, follow these instructions:

  1. Create an application with an AWS SDK for PHP client to use an AWS service.

  2. Host your project on an Amazon EC2 instance or in your local environment.

  3. Install and use the latest version of the AWS SDK for PHP.

  4. Install and configure a CloudWatch agent on an EC2 instance or in your local environment.

  5. Authorize SDK Metrics to collect and send metrics.

  6. Enable SDK Metrics for the AWS SDK for PHP.

For more information, see the following:

Enable SDK Metrics for the AWS SDK for PHP

By default, SDK Metrics is turned off, host is set to '127.0.0.1' and the port is set to 31000. The following are the default parameters.

//default values [ 'enabled' => false, 'host' => '127.0.0.1', 'port' => 31000, ]

Enabling SDK Metrics is independent of configuring your credentials to use an AWS service.

You can enable SDK Metrics by passing in a client configuration option, setting environment variables, or by using the AWS Shared config file.

Order of Precedence

The order of precedence is as follows (1 overrides 2-3, etc.):

  1. Client configuration option

  2. Environment variables

  3. AWS Shared config file

Option 1: Client Configuration Option

You can pass in a csm option to your client constructor to enable and set the configuration options. This option can be an associative array, an instance of \Aws\ClientSideMonitoring\ConfigurationInterface, a callable that provides an instance of \Aws\ClientSideMonitoring\ConfigurationInterface, or the boolean value of false.

Associative array:

$client = new \Aws\S3\S3Client([ 'region' => 'your-region', 'version' => 'latest', 'csm' => [ 'enabled' => true, 'host' => 'my.host', 'port' => 1234, 'client_id' => 'My Application' ] ]);

Instance of \Aws\ClientSideMonitoring\ConfigurationInterface:

$client = new \Aws\S3\S3Client([ 'region' => 'your-region', 'version' => 'latest', 'csm' => new \Aws\ClientSideMonitoring\Configuration( true, 'my.host', 1234, 'My Application' ) ]);

Callable:

$client = new \Aws\S3\S3Client([ 'region' => 'your-region', 'version' => 'latest', 'csm' => function() { return new \Aws\ClientSideMonitoring\Configuration( true, '127.0.0.1', 1234, 'My Application' ); } ]);

Boolean `false`:

$client = new \Aws\S3\S3Client([ 'region' => 'your-region', 'version' => 'latest', 'csm' => false ]);

Option 2: Set Environment Variables

The SDK first checks the profile specified in the environment variable under AWS_PROFILE to determine if SDK Metrics is enabled.

To turn on SDK Metrics, add the following to your environmental variables.

export AWS_CSM_ENABLED=true

Other configuration settings are available. For more information about using shared files, see Using Credentials from Environment Variables.

Note

Enabling SDK Metrics does not configure your credentials to use an AWS service. To do that, see Credentials for the AWS SDK for PHP Version 3.

Option 3: AWS Shared Config File

If no CSM configuration is found in the environment variables, the SDK looks for your default AWS profile field. If AWS_DEFAULT_PROFILE is set to something other than default, update that profile. To enable SDK Metrics, add csm_enabled to the shared config file located at ~/.aws/config.

[default] csm_enabled = true [profile aws_csm] csm_enabled = true

Other configuration settings are available. For more information about using AWS Shared files, see Using the AWS Credentials File and Credential Profiles.

Note

Enabling SDK Metrics does not configure your credentials to use an AWS service. To do that, see Credentials for the AWS SDK for PHP Version 3.

Update a CloudWatch Agent

To make changes to the host or port ID, you need to set the values and then restart any AWS jobs that are currently active.

Option 1: Client Configuration Option

See Option 1 above under "Enable SDK Metrics for the AWS SDK for PHP" for examples of how to set the client configuration csm option to modify CSM settings.

Option 2: Set Environment Variables

Most AWS services use the default port. But if the service you want SDK Metrics to monitor uses a unique port, add AWS_CSM_PORT=[port_number], to the host's environment variables. Additionally, a different host can be specified using the AWS_CSM_HOST environment variable.

export AWS_CSM_ENABLED=true export AWS_CSM_PORT=1234 export AWS_CSM_HOST=192.168.0.1

Option 3: AWS Shared Config File

Most services use the default port. But if your service requires a unique port ID, add csm_port = [port_number] to ~/.aws/config. A non-default host can be configured using csm_host.

[default] csm_enabled = false csm_host = 123.4.5.6 csm_port = 1234 [profile aws_csm] csm_enabled = false csm_host = 123.4.5.6 csm_port = 1234

Restart SDK Metrics

To restart a job, run the following commands.

amazon-cloudwatch-agent-ctl –a stop; amazon-cloudwatch-agent-ctl –a start;

Disable SDK Metrics

To turn off SDK Metrics, set csm_enabled to false in your environment variables, or in your AWS Shared config file located at ~/.aws/config. Then restart your CloudWatch agent so that the changes can take effect.

Set csm_enabled to false

Note

Note the order of precedence listed above. For example, if SDK Metrics is enabled in the environment variables but disabled in the config file, the SDK Metrics remains enabled.

Option 1: Client configuration

$client = new \Aws\S3\S3Client([ 'region' => 'your-region', 'version' => 'latest', 'csm' => false ]);

Option 2: Environment Variables

export AWS_CSM_ENABLED=false

Option 3: AWS Shared Config File

[default] csm_enabled = false [profile aws_csm] csm_enabled = false

Stop SDK Metrics and Restart CloudWatch agent

To disable SDK Metrics, use the following command.

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a stop && echo "Done"

If you are using other CloudWatch features, restart CloudWatch with the following command.

amazon-cloudwatch-agent-ctl –a start;