Amazon CloudWatch Getting Started Guide API Version 2010-08-01
Amazon CloudWatch Getting Started Guide
Amazon Web Services
Amazon CloudWatch Getting Started Guide
Amazon CloudWatch: Getting Started Guide Amazon Web Services Copyright © 2013 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront, Cloudfront, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
Amazon CloudWatch Getting Started Guide
Get Started with Amazon CloudWatch ................................................................................................... 1 Sign Up for CloudWatch ......................................................................................................................... 2 Set Up the Command Line Interface ...................................................................................................... 3 Publish Metrics to CloudWatch ............................................................................................................... 7 Get Statistics From CloudWatch ........................................................................................................... 10 View Graphs with the Console .............................................................................................................. 11 Where Do I Go from Here? ................................................................................................................... 14 Other Ways to Access Amazon CloudWatch ........................................................................................ 14 Continue Using the Command Line Interface ............................................................................. 14 Using the Console ....................................................................................................................... 15 Use an Existing Library ............................................................................................................... 15 Code Directly to the Web Service API ......................................................................................... 15 Learn More about Amazon CloudWatch ............................................................................................... 15 Monitoring EC2 Instances ........................................................................................................... 15 Creating an Alarm ....................................................................................................................... 15 Please Provide Feedback ..................................................................................................................... 17 Document History ................................................................................................................................. 18 About This Guide .................................................................................................................................. 19
API Version 2010-08-01 4
Amazon CloudWatch Getting Started Guide
Get Started with Amazon CloudWatch Amazon CloudWatch is a web service that enables you to collect, view, and analyze metrics. You can get started with Amazon CloudWatch by performing the tasks shown in the following diagram. You'll use both the CloudWatch Command Line Interface (CLI) and the AWS Management Console, a point-and-click web-based interface.
This guide walks you through a few basic Amazon CloudWatch procedures, such as setting up the CLI, publishing metrics, retrieving statistics, and viewing graphs on the console.
API Version 2010-08-01 1
Amazon CloudWatch Getting Started Guide
Sign Up for CloudWatch
If you already have an AWS account, skip to the next procedure. If you don't already have an AWS account, use the following procedure to create one.
Note When you create an account, AWS automatically signs up the account for all services. You are charged only for the services you use.
To sign up for an AWS account 1. 2.
Go to http://aws.amazon.com, and then click Sign Up. Follow the on-screen instructions. Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.
Now you are ready to download the command line tools.
API Version 2010-08-01 2
Amazon CloudWatch Getting Started Guide Install the Command Line Tools
Set Up the Command Line Interface
Topics • Install the Command Line Tools (p. 3) • Configure the CLI for Your Credentials (p. 4) • Test Your Configuration (p. 5)
Install the Command Line Tools To use the commands described in this guide, you must install and configure the command line tools.
To install the Amazon CloudWatch command line tools 1.
Download the command line tools from Amazon CloudWatch Tools.
2.
Save and unpack the Amazon CloudWatch archive to a convenient location on your workstation.
3.
Enter the command java -version to determine the version of Java installed on your workstation. If you do not have version 1.5 or newer, download and install a newer version from http://www.java.com.
4.
Set the JAVA_HOME environment variable to point to your Java installation. The following is an example of how to set this environment variable in Linux and UNIX. $ export JAVA_HOME=
The following is an example of the syntax in Windows. C:\> set JAVA_HOME=
API Version 2010-08-01 3
Amazon CloudWatch Getting Started Guide Configure the CLI for Your Credentials
5.
Make the following addition to your PATH environment variable. On Linux and UNIX, you can update your PATH as follows: $ export PATH=$PATH:$JAVA_HOME/bin
Note The export command applies only to the current shell session. To permanently create or update an environment variable, include the command in a start-up script. For example, if you use Bash shell, you can include commands in your ~/.bashrc or /etc/profile file. On Windows the syntax is slightly different: C:\> set PATH=%PATH%;%JAVA_HOME%\bin
Note The Windows environment variables are reset when you close the command window. You might want to set them permanently with the setx command. 6.
Set the AWS_CLOUDWATCH_HOME environment variable to the location where you unpacked the Amazon CloudWatch archive. On Linux and UNIX, you can set this environment variable as follows: $ export AWS_CLOUDWATCH_HOME=
On Windows the syntax is slightly different: C:\> set AWS_CLOUDWATCH_HOME=
7.
Make the following addition to your PATH environment variable. On Linux and UNIX, you can update your PATH as follows: $ export PATH=$PATH:$AWS_CLOUDWATCH_HOME/bin
On Windows the syntax is slightly different: C:\> set PATH=%PATH%;%AWS_CLOUDWATCH_HOME%\bin
Configure the CLI for Your Credentials You must provide your AWS credentials before you can use the Amazon CloudWatch CLI. There are two types of access keys: access key IDs and secret access keys. You should have stored your access keys in a safe place when you created them. Although you can retrieve your access key ID from the Your Security Credentials page, you can't retrieve your secret access key. Therefore, if you can't find your secret access key, you'll need to create new access keys before you can use the CLI tools. You can either specify your credentials with the --aws-credential-file parameter every time you issue a command or you can create an environment variable that points to the credential file on your local system. If the environment variable is properly configured, you can omit the --aws-credential-file API Version 2010-08-01 4
Amazon CloudWatch Getting Started Guide Test Your Configuration
parameter when you issue a command. The following procedure describes how to create a credential file and a corresponding AWS_CREDENTIAL_FILE environment variable.
To set up security credentials for the CLI 1.
2.
Add your access key ID and secret access key to the file named credential-file-path.template, located in the folder where you installed the Amazon CloudWatch CLI. Rename the file and save it to a convenient location on your workstation. • If you are using Linux or UNIX, set the file permissions as follows: $ chmod 600
• On Windows, you do not need to change the file permissions.
3.
Set the AWS_CREDENTIAL_FILE environment variable to the fully-qualified path of the credential file you just created. • On Linux and UNIX, you can set this environment variable as follows: $ export AWS_CREDENTIAL_FILE=
• On Windows, you can set this environment variable as follows: C:\> set AWS_CREDENTIAL_FILE=
Test Your Configuration To test your installation and configuration of Amazon CloudWatch 1.
On your workstation, open a new command prompt.
2.
Type the command mon-cmd.
3.
You should see output similar to the following: Command Name
Description
-----------mon-delete-alarms mon-describe-alarm-history mon-describe-alarms mon-describe-alarms-for-metric mon-disable-alarm-actions mon-enable-alarm-actions mon-get-stats mon-list-metrics mon-put-data mon-put-metric-alarm
----------Delete alarms Describe alarm history Describe alarms fully. Describe all alarms ... a single metric Disable all actions for a given alarm Enable all actions for a given alarm Get metric statistics List user's metrics Put metric data Create new alarm or update existing one
API Version 2010-08-01 5
Amazon CloudWatch Getting Started Guide Test Your Configuration
mon-set-alarm-state mon-version
Manually set the state of an alarm Prints the version ... tool and the API
For help on a specific command, type ' --help'
This completes your installation and configuration of the Amazon CloudWatch command line tools.
API Version 2010-08-01 6
Amazon CloudWatch Getting Started Guide Define the Data Configuration
Publish Metrics to CloudWatch
Topics • Define the Data Configuration (p. 7) • Add Metrics to Amazon CloudWatch (p. 8) Now that you have installed the Amazon CloudWatch CLI, you're ready to publish metrics to CloudWatch. You'll use the command line tools to publish a single metric for a hypothetical application named GetStarted.
Define the Data Configuration In the following example, you'll publish data points that track the request latency for the application. Choose names for your metric and namespace that make sense to you. For this example, name the metric RequestLatency and place all of the data points into the GetStarted namespace. You'll publish several data points that collectively represent three hours of latency data. The raw data comprises fifteen request latency readings distributed over three hours. Each reading is in milliseconds: • Hour one: 87, 51, 125, 235 • Hour two: 121, 113, 189, 65, 89 • Hour three: 100, 47, 133, 98, 100, 328
You can publish data to Amazon CloudWatch as single data points or as an aggregated set of data points called a statistic set. You'll publish the data points from hour one as single data points. Hour
Raw Data
1
87
API Version 2010-08-01 7
Amazon CloudWatch Getting Started Guide Add Metrics to Amazon CloudWatch
Hour
Raw Data
1
51
1
125
1
235
For the data from hours two and three, you'll aggregate the data points and publish a statistic set for each hour.
Note You can aggregate metrics to a granularity as low as one minute. You can publish the aggregated data points to Amazon CloudWatch as a set of statistics with four predefined keys: Sum, Minimum, Maximum, and SampleCount. The key values are shown in the following table. Hour
Raw Data
Sum
Minimum
Maximum
SampleCount
2
121, 113, 189, 65, 89
577
65
189
5
3
100, 47, 133, 98, 100, 328
806
47
328
6
Add Metrics to Amazon CloudWatch After you have defined your data configuration, you are ready to begin adding data.
Note When you use the mon-put-data command, you must use a date range within the past two weeks. There is currently no function to delete data points. Amazon CloudWatch automatically deletes data points with a timestamp more than two weeks old. The mon-put-data command has several parameters with abbreviated forms for faster data entry. The following table contains the abbreviated forms of the relevant mon-put-data parameters. You can use these abbreviated forms to simplify data entry. Parameter
Abbreviated Form
--metric-name
-m
--namespace
-n
--timestamp
-t
--statisticValues
-s
--unit
-u
--value
-v
API Version 2010-08-01 8
Amazon CloudWatch Getting Started Guide Add Metrics to Amazon CloudWatch
To publish data points to Amazon CloudWatch 1.
Open a command prompt and enter the following commands, but replace the time stamp with a time stamp that represents two hours in the past in Universal Coordinated Time (UTC). mon-put-data -m RequestLatency 87 -u Milliseconds mon-put-data -m RequestLatency 51 -u Milliseconds mon-put-data -m RequestLatency 125 -u Milliseconds mon-put-data -m RequestLatency 235 -u Milliseconds
-n "GetStarted" -t 2010-10-29T20:30:00Z -v -n "GetStarted" -t 2010-10-29T20:30:00Z -v -n "GetStarted" -t 2010-10-29T20:30:00Z -v -n "GetStarted" -t 2010-10-29T20:30:00Z -v
Amazon CloudWatch returns a response only when it cannot execute the command. 2.
Enter the second data point, but this time use a time stamp one hour later than the first one in Universal Coordinated Time (UTC). mon-put-data -m RequestLatency -n "GetStarted" -t 2010-10-29T21:30:00Z -s "Sum=577,Minimum=65,Maximum=189,SampleCount=5" -u Milliseconds
3.
Enter the last data point, but this time omit the time stamp to get the current time (the default value). mon-put-data -m RequestLatency -n "GetStarted" -s "Sum=806,Minimum=47,Maxim um=328,SampleCount=6" -u Milliseconds
The mon-put-data command has a number of other options. For more information, go to mon-put-data in the Amazon CloudWatch Developer Guide. After adding metrics, you can get statistics.
API Version 2010-08-01 9
Amazon CloudWatch Getting Started Guide
Get Statistics From CloudWatch
Now that you have published metrics to Amazon CloudWatch, you are ready to retrieve statistics that are based on those metrics. In each of the following examples, --metric-name, --namespace, and --statistics are the only required parameters.
To retrieve statistics with the command line tools •
Specify a --start-time far enough in the past to cover the earliest time stamp that you published. You can omit the --end-time parameter because it defaults to the current time. The --headers parameter provides the table headers. mon-get-stats -n GetStarted -m RequestLatency -s "Average" --start-time 2010-10-29T00:00:00Z --headers
Amazon CloudWatch returns the following: Time 2010-10-29 20:30:00 2010-10-29 21:30:00 2010-10-29 22:17:00
Average 124.5 115.4 134.33333333333334
Unit Milliseconds Milliseconds Milliseconds
If you want to see your statistics in a visual format, you can use the AWS Management Console to view graphs.
API Version 2010-08-01 10
Amazon CloudWatch Getting Started Guide
View Graphs with the Console
You can use the AWS Management Console to view statistical graphs.
To view graphs of your statistics on the console 1.
Sign in to the AWS Management Console and open the Amazon CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
2.
In the Navigation pane, click Metrics. Metrics opens in the right pane.
API Version 2010-08-01 11
Amazon CloudWatch Getting Started Guide
3.
In the Metrics pane, select GetStarted from the Viewing drop-down list box.
4.
In the Metrics pane, select the check box next to the RequestLatency metric name. The graph refreshes, and should look like the following screen capture.
5.
If you want to change the graph, choose different values from the Statistic and Period drop-down list boxes.
6.
You can also create an alarm for this metric by clicking Create Alarm.
API Version 2010-08-01 12
Amazon CloudWatch Getting Started Guide
API Version 2010-08-01 13
Amazon CloudWatch Getting Started Guide AWS Account and Security Credentials
Where Do I Go from Here? Topics • AWS Account and Security Credentials (p. 14) • Other Ways to Access Amazon CloudWatch (p. 14) • Learn More about Amazon CloudWatch (p. 15) • Amazon CloudWatch Resources (p. 15) Amazon CloudWatch offers features we haven't covered in this guide, such as creating your own alarms, and integrating with both Auto Scaling and Simple Notification Service (SNS). This section provides links to additional resources, which can help you deepen your understanding and use of Amazon CloudWatch.
AWS Account and Security Credentials So far you signed up for the service, got an AWS account and security credentials, and then completed a short exercise covering the essential product functions. Now that you're finished with the exercise, we recommend that you check with an administrator or coworker in your organization to determine if he or she already has an AWS account and security credentials for you to use in future interactions with AWS. If you're an account owner or administrator and want to know more about AWS Identity and Access Management, go to the product description at http://aws.amazon.com/iam or to the technical documentation at Using IAM.
Other Ways to Access Amazon CloudWatch This Getting Started Guide shows you how to use the CLI to publish metrics and get statistics. You can continue using Amazon CloudWatch through the CLI, or try one of the other interfaces.
Continue Using the Command Line Interface The command line interface includes functions not only for publishing metrics and getting statistics, but also for creating alarms. These command line tools are a fast way to execute all the Amazon CloudWatch functions without coding to the API or using a library.
API Version 2010-08-01 14
Amazon CloudWatch Getting Started Guide Using the Console
Using the Console The AWS Management Console includes many other functions besides viewing statistics about metrics you have published. To learn more about how to use Amazon CloudWatch through the console, go to the Amazon CloudWatch Developer Guide. The console also has online Help to assist you (just click the Help button in the console).
Use an Existing Library If you prefer to use Amazon CloudWatch through a programmatic interface, there are libraries and resources available for the following languages: • Java • PHP • Python • Ruby • Windows and .NET For libraries and sample code in all languages, go to Amazon EC2 Sample Code & Libraries.
Code Directly to the Web Service API If you want to write code directly to the Amazon CloudWatch Query API, go to the Amazon CloudWatch Developer Guide. The guide describes how to create and authenticate API requests, and how to use Amazon CloudWatch through the API. For a complete description of all the API actions, go to the Amazon CloudWatch API Reference.
Learn More about Amazon CloudWatch This section lists additional features of Amazon CloudWatch and where to get more information.
Monitoring EC2 Instances You can enable monitoring when you first create an EC2 instance or at any time thereafter. Shortly after monitoring is enabled, you can retrieve statistics about the instance with the CLI, the Query API, or the AWS Management Console. For more information, go to the Amazon CloudWatch Developer Guide.
Creating an Alarm You can create alarms that monitor specific metrics gathered from an EC2 instance. When a metric breaches a threshold, the alarm can send an email message through the Simple Notification Service (SNS) or trigger an Auto Scaling activity. For more information, go to the Amazon CloudWatch Developer Guide.
Amazon CloudWatch Resources The following table lists related resources that you'll find useful as you work with Amazon CloudWatch.
API Version 2010-08-01 15
Amazon CloudWatch Getting Started Guide Amazon CloudWatch Resources
Resource
Description
Amazon CloudWatch Technical FAQ
The FAQ covers the top 20 questions developers have asked about this product.
Release notes
The release notes give a high-level overview of the current release. They specifically note any new features, corrections, and known issues.
AWS Developer Resource Center
A central starting point to find documentation, code samples, release notes, and other information to help you build innovative applications with AWS.
AWS Management Console
The console allows you to perform most of the functions of Amazon CloudWatch and various other AWS products without programming.
Amazon CloudWatch Discussion Forums Community-based forum for developers to discuss technical questions related to Amazon CloudWatch. AWS Support Center
The home page for AWS Technical Support, including access to our Developer Forums, Technical FAQs, Service Status page, and Premium Support.
AWS Premium Support
The primary web page for information about AWS Premium Support, a one-on-one, fast-response support channel to help you build and run applications on AWS Infrastructure Services.
Amazon CloudWatch product information The primary web page for information about Amazon CloudWatch. Contact Us
A central contact point for inquiries concerning AWS billing, account, events, abuse, etc.
API Version 2010-08-01 16
Amazon CloudWatch Getting Started Guide
Please Provide Feedback Your input is important to help make our documentation helpful and easy to use. Please tell us about your experience getting started with Amazon CloudWatch by completing our Getting Started Survey. Thank you.
API Version 2010-08-01 17
Amazon CloudWatch Getting Started Guide
Document History This documentation is associated with the 2010-08-01 release of Amazon CloudWatch. This guide was last updated on 15 August 2013. The following table describes the important changes since the last release of the Amazon CloudWatch Getting Started Guide. Change
Description
Release Date
Removed Content
Removed the verification step from the Publish Metrics to CloudWatch (p. 7) section because verification is not necessary. The Amazon CloudWatch Command Line Interface returns a response if it cannot create a metric.
6 June 2011
Public Release This is the first release of the Amazon CloudWatch Getting Started Guide.
API Version 2010-08-01 18
10 May 2011
Amazon CloudWatch Getting Started Guide
About This Guide This is the Amazon CloudWatch Getting Started Guide. It was last updated on August 15, 2013. Amazon CloudWatch is often referred to within this guide as "CloudWatch"; all copyrights and legal protections still apply.
API Version 2010-08-01 19
