E-mail
Overview
This page covers how to set up and monitor your Amazon EC2 infrastructure using the GroundWork Cloud Hub AWS connector. The connection requires a unique set of parameters (e.g., endpoint, credentials). You will need your GroundWork server and virtual environment connector parameters handy.
CONTENTS | RELATED RESOURCES |
WAS THIS PAGE HELPFUL? |
1.0 Adding a New Connection
To access Cloud Hub, log in to GroundWork Monitor as an Administrator and select (1) GroundWork Administration > GroundWork Cloud Hub.
The initial Cloud Hub screen is used to (2) Add new, or Start, Stop, Modify, obtain Status for, or Delete configured connectors.
The Start option enables a configured connector to begin the discovery and data collection process. If you decide you do not want to monitor a particular region, simply select Stop for the corresponding connector, the connectors configuration will be maintained for a subsequent start. Modify opens the Configuration page with a link to the Metrics screen. Status provides connection status information including error details. If a configured connector fails to connect, a connector-specific service will be updated to a Warning state, or Critical if you run out of retries (hosts will still become Unreachable and services Unknown if retries are exhausted). To stop and completely Delete a connection, see How to delete hosts. To keep a Cloud Hub connector configuration and temporarily suspend its monitoring, see Black List.
To (3) add a new connection click +Add corresponding to the Amazon AWS connector icon. You will need to create a new connection in this way for each region to be monitored.
Figure: Adding a connection
Next, in the configuration page (shown below) you will need to enter both the GroundWork server and remote server parameters. The data the GroundWork server receives comes from the remote virtualization server. The information is pulled from the API on a periodic basis based on the check interval that is set.
The (1) Groundwork Server is where Cloud Hub will store AWS metrics. Often, this is the same server as where Cloud Hub is running. However, Cloud Hub can also be run in a distributed environment, on its own node in a GroundWork cluster. Here we enter the GroundWork server parameters, each described in the first table below.
Next enter values for the remote (2) AWS Connector shown below and described in the second table.
Validate both server configurations by selecting the (3) Test buttons which will check if the connections are accessible with the given credentials. A dialog will be displayed with either a success message or, if the server cannot be contacted, an error message will be displayed with information describing why the connection failed. When a successful connection is made, the Connection Status buttons will change to green.
(4) Views are optional features of AWS. These features are the core components, or services that are managed by AWS. Views include Storage View shows instances according to the Amazon EBS resources where they are assigned, Network View shows instances as they are assigned to Virtual Private Cloud subnets and Relational Database Service (RDS) metrics, Custom View enables a query that will retrieve all active custom CloudWatch metrics in the zone being connected.
The AWS connector now provides custom metrics as a way to have your applications report performance into an arbitrary metric that you can design. You can tell EC2 what you want to keep track of and have your applications send what is being tracked to Amazon to record regularly. Each of these services has their own rich set of metrics. By default, all services are selected. If checked, service will be monitored. AWS also provides Cluster and Host metrics which can be optionally collected. If there are one or more clusters or hosts in the system, they will be automatically detected and collected. If you were collecting metrics for a service, and then unchecked that AWS service, the existing hosts and metrics stored in the GroundWork server will be deleted. When unchecked the metrics will be deleted.
And after the remote server parameters have been entered and verified, click (5) Save in the upper right corner to save and write the entries to an XML file in the GroundWork server /usr/local/groundwork/config/cloudhub directory. The Cloud Hub connector is assigned an agent ID and that in turn becomes a record locator in Foundation when you begin monitoring. After the credentials have been validated select the Metrics link (top navigation) to start customizing metrics for the connection.
Figure: AWS connector
Table: GroundWork server values
| Version | Indicates the minimum GroundWork Monitor version needed. In other words, a version below the indicated value is incompatible. |
| Hostname | The host name or IP address where a Groundwork server is running. A port number should not be entered here. If Groundwork is running on the same server, you can enter localhost. |
| Username | The provisioned Username granted API access on the GroundWork server. |
| Token | The corresponding API Token (password) for the given Username on the GroundWork server, see GroundWork Administration > GroundWork License > Webservices API Account Info Token (encrypted). |
| SSL | Check this box if the GroundWork server is provisioned with a secure HTTPS transport. |
| Merge Hosts | If checked, this option combines all metrics of same named hosts under one host. For example, if there is a Nagios configured host named demo1 and a Cloud Hub discovered host named demo1, the services for both configured and discovered hosts will be combined under the hostname demo1 (case-sensitive). |
| Monitor | Enables connection to be monitored. |
Table: AWS server values
| Display Name | This is the configuration’s name displayed in the list of Cloud Hub connectors on the Cloud Hub home page. |
| AWS Region Endpoint | This is the Web Service endpoint for a region (e.g., us-west-2.amazonaws.com for region Oregon). Create a connector like this for each region deployed to point to the endpoint for that region. The endpoint is where you access the CloudWatch API. |
| Enable AIM Roles | |
| AWS Access Key ID | This can also be a common user name set up for command line access (does not have to be the master account). It should be clear that the user name must be assigned rights to the region that you wish to monitor. |
| AWS Secret Access Key |
This can also be a common password set up for command line access (does not have to be the master account). It should be clear that the password must be assigned rights to the region that you wish to monitor. |
| Enable HostGroup Tagging? |
Check this option to enable support for Amazon EC2 and EBS tagging as a mapping mechanism for host groups, defined in the next directive. |
| Hostgroup Tag Name |
Cloud Hub can map your AWS resource tags to GroundWork host groups. This entry represents the key name for the GroundWork tag. All instances with this tag key will be mapped to the GroundWork Monitor host group (e.g., gwhostgroup) with the EC2 tag value (e.g., GWHostGroup). There may be multiple host groups with the same tag name and tag names are case-sensitive. Refer to Appendix A: Host Group Tagging on this page for a detailed description of this feature. |
| Enable SSL | Check this box if the Amazon server is configured for secure HTTPS. |
| Cloud Hub Interval (min) | This is the polling interval for collecting monitoring data from the virtual instance and sending it to the GroundWork server. It defines how often Cloud Hub will query Amazon CloudWatch for change updates. The value is in minutes. |
| Infinite Retries | This entry is the number of retries for the connection and sets a limit on how many attempts are made after a failure. If you set this to -1, the retrying goes on forever. The number set indicates how many connections are attempted before the connection is left inactive (until you restart it). |
| Retry Limit | This entry is the number of retries for the connection and sets a limit on how many attempts are made after a failure. The number set indicates how many connections are attempted before the connection is left in an inactive state. At this point, the connection is suspended and you will need to manually restart it. When a retry limit is exhausted, all hosts managed by this connection are set to the monitor status Unreachable and all services for the matched hosts are set to the status of Unknown. |
2.0 Navigating
From the Configuration page, navigations are on displayed in the top navigation bar:
From here, you can navigate to:
- Home - Cloud Hub home page
- Metrics - Metrics configuration page associated with this Cloud Hub connection
- Configuration - Cloud Hub configuration page
When creating a new AWS configuration, the Metrics link is not visible until you successfully save the configuration parameters. Once you are satisfied with your configuration settings, click Save, then click the Metrics link in the navigation bar to start customizing your metrics for this connection. Also, the Save button is not enabled until all required fields are validated. If you make changes on the configuration page, and forget to save, you will be prompted.
3.0 Determining Metrics To Be Monitored
The AWS Metrics page is where you customize the lists of metrics being gathered for a connection. Out of the box, a complete list of metrics is provided for clusters, hosts, and AWS services. You can customize these metric lists by adding metrics to the list, deleting metrics, as well as creating calculated metric fields called Synthetic metrics.
The Metrics page is displayed in groups of metrics grouped by Cluster, Host, and AWS Service collections. The counts of metrics are displayed in the Group bar, and summarized by:
- # metrics per group
- # active metrics per group
- # synthetic metrics per group
A metric is considered inactive if it is not monitored.
Figure: AWS metrics
You can configure the metrics for any group by clicking on the (1) group bar. Each row in the grid represents a metric. Metrics can be added, edited or deleted. You can directly edit metrics in the grid or use the advanced metric dialog by clicking the (2) Edit button and then configuring all properties of a metric in the dialog. When editing metrics in the grid directly, you will need to click the (3) Save button in the top navigation to commit your changes to Cloud Hub. To add new metrics use (4) Add Normal Metric or Add Synthetic Metric.
For example, if we click on the EC2 Compute (9 metrics, active, synthetic) group bar, the display automatically expands to show all metrics for the EC2 Compute group.
Figure: EC2 Compute
The grid displays the following fields:
| Monitor? | Check this if you want to enable monitoring of this metric. |
| Graph? | Check this if you want to graph the values of this metric in time series |
| Metric Name | The exact AWS metric name or a AWS metric expression. This field is read-only. Click the Edit button to modify it. |
| Display Name | Overrides the metric name and stores the metric in GroundWork as a service with this name. |
| Warning Threshold | Metric value that will trigger a GroundWork Warning alert. |
| Critical Threshold | Metric value that will trigger a GroundWork Critical alert. |
 | For additional information regarding Amazon EBS, Amazon RDS, and Amazon CloudWatch Custom metrics see Appendix B: Notes on AWS Metrics. |
Appendix A: Host Group Tagging
To help manage and group your EC2 instances and EBS images, AWS allows you to assign your own metadata to each resource in the form of tags. A tag is a key and value pair of user defined strings that can be assigned to AWS resources as mapping mechanism for host groups. Tags enable you to categorize your AWS resources in different ways, for example, by purpose, owner, or environment. This is useful when you have many resources of the same type — you can quickly identify a specific resource based on the tags you've assigned to it. For example, with a tag Key name of GWHostGroup, and a tag Value gwservers, all instances assigned the tag key GWHostGroup{ are placed in the host group called gwservers.
Tagging Notes
- Host Groups are deleted when empty as is the case for all such host groups automatically created by Cloud Hub.
- A host can be in more than one group, so if you create tagging and only want to display the tagged group - you can allow access to specific Host Groups and Service Groups in the portal membership management. For example, restricting user operator to just the gwservers host group would result in the Cloud Hub discovered host groups to not display in such applications as Status.
- Tag key and value strings are case-sensitive.
- Resources (e.g., EC2 instances, EBS volumes) can have one or more (up to 50) tags each.
Enabling Tagging
Cloud Hub can map your AWS resource tags to GroundWork Host Groups. To utilize this feature you need to enable tagging and set a Host Group tag name. To enable tagging, go to the connection configuration and check the Enable HostGroup Tagging? checkbox. In the next field, enter a Host Group Tag Name to match a tag key name configured in EC2.
Configuring Tagging in the Console
Along with the Cloud Hub configuration above, to tag EC2 instances or EBS volumes you will need to configure tags in the EC2 console.
Launch and sign in to the Amazon EC2 console at https://console.aws.amazon.com/ec2. If necessary, in the upper right corner change the location of the resources to the desired region. In the navigation pane, select Tags. Click the Manage Tags button. Select the instances you would like to tag (e.g., checked in blue) and assign a tag key (e.g., GWHostGroup) and a tag value (e.g., gwservers), and select Add Tag.
The tag key (e.g., GWHostGroup) is then used in the Cloud Hub connector configuration (from above), and the tag value (e.g., gwservers) becomes the name of the host group for the associated instances. Alternatively, you can navigate to individual EC2 instances and assign tags specifically to that one instance from the Tag tab. Similarly, Elastic Block Store volumes can also be assigned tags.
Appendix B: Notes on AWS Metrics
Elastic Block Store (EBS) Metrics
- EBS metrics are now attached to corresponding hosts. A host can have one or more EBS metrics. Previously, EBS metrics were gathered in their own groups which was causing unused volume metrics to be reported.
- EBS metric naming has been changed to prefix service names on EC2 instance with: EBS.{volume-name}.{metricname}
- EBS metrics are only added to EC2 instances when Storage View on the connection configuration page is enabled
- EBS host groups and hosts have been removed
- When unchecking Storage View, all EBS services are deleted
- Supported EBS metrics:
- EBS.VolumeIdleTime - Total seconds spent by in Idle time on EBS device
- EBS.VolumeQueueLength - Total Read and Write Operations on EBS device
- EBS.VolumeReadBytes - Total Bytes Read on EBS device
- EBS.VolumeReadOps - Total Read Operations on EBS device
- EBS.VolumeTotalReadTime - Total seconds spent by Read operations completed on EBS device
- EBS.VolumeTotalWriteTime - Total seconds spent by Write operations completed on EBS device
- EBS.VolumeWriteBytes - Total Bytes Written on an EBS device
- EBS.VolumeWriteOps - Total Write Operations on EBS device
Relational Database Service (RDS) Metrics
- When Storage View is enabled, RDS hosts are added to a host group named AWS-RDS:storage
- No unused RDS volume metrics are reported, such as volumes that exist in the zone but are not attached to any running instance
- When unchecking Storage View, all RDS hosts and services are deleted, and the RDS host group is deleted
- RDS metrics are only associated with an RDS host
- Supported RDS metrics:
- RDS.BinLogDiskUsage - Disk space occupied by binary logs on the master RDS node
- RDS.DatabaseConnections - Number of database connections currently in use on RDS
- RDS.DiskQueueDepth - Number of outstanding IOs (read/write requests) waiting to access RDS disks
- RDS.FreeStorageSpace - Amount (bytes) of available Storage space on RDS service
- RDS.FreeableMemory - Amount (bytes) of available RAM on RDS service
- RDS.NetworkReceiveThroughput - Incoming (Receive) network traffic on the DB instance in bytes/second, includes both database and RDS traffic
- RDS.NetworkTransmitThroughput - Outgoing (Transmit) network traffic on the DB instance in bytes/second, includes both database and RDS traffic
- RDS.ReadIOPS - Average number of disk I/O read operations per second (RDS)
- RDS.ReadLatency - Average amount of time in seconds taken per disk Read I/O operation (RDS)
- RDS.ReadThroughput - Average number of bytes read from disk per second (RDS)
- RDS:ReplicaLag - Amount of time a Read Replica DB Instance lags behind the source DB Instance
- RDS.SwapUsage - Amount (bytes) of swap space used on the DB instance
- RDS.WriteIOPS - Average number of disk I/O write operations per second (RDS)
- RDS.WriteLatency - Average amount of time in seconds taken per disk Write I/O operation (RDS)
- RDS.WriteThroughput - Average number of bytes written to disk per second (RDS)
CloudWatch Custom Metrics
Amazon CloudWatch is a monitoring service for AWS cloud resources and the applications you run on AWS. Amazon CloudWatch is used to collect and track metrics for all standard AWS resources such as EC2 instances, Relational Database Service (RDS), and Elastic Block Store (EBS) storage volumes.
Additionally, CloudWatch can be extended to gather Custom Metrics generated by your applications and services and monitor these metrics for you. If your application is generating custom metrics, to have GroundWork Cloud Hub retrieve these metrics you'll need to turn on Custom View in your AWS connection configuration.
At the top of the screen click Refresh Custom to retrieve a list of custom metrics from your application.
It is best practice to use namespaces when registering your custom metrics with CloudWatch. This can help you separate your custom metrics from other metrics in the system. In the Cloud Hub configuration, you can treat these metrics like any other.