Hyperglance comes pre-integrated with Cloudwatch. This integration allows the system to recognise and use pre-existing Cloudwatch metrics in Hyperglance's chart functionality. It is possible, and relatively simple, to change this pre-defined list of Cloudwatch/Hyperglance integrated metrics, either adding new ones or removing some, in Hyperglance. This configurability enables the user to view custom metrics on Hyperglance with relative ease.
1. Adding pre-existing AWS Cloudwatch metrics to Hyperglance
Firstly let's go over the process of adding a metric to Hyperglance's configuration. After we've identified a metric that is not currently being shown in Hyperglance but is available on Cloudwatch we have to collect some information about it. Let's assume we initiate a RDS Table, and we go into Cloudwatch. We would probably see something like:
Let's use the highlighted metric, NetworkReceiveThroughput as the example metric to be added to the Hyperglance configuration. Here's some useful information about this metric, that can be obtained from Cloudwatch:
- Cloudwatch Name: NetworkReceiveThroughput
- Unit: Bytes/Second
This information will be useful when adding the metric into Hyperglance's configuration. The letter is centralized in one XML file called metrics.xml. This file can be found in:
Note: this path may differ from your own Hyperglance installation folder.
This XML file contains all the metrics that Hyperglance accepts from Cloudwatch, regardless of Cloudwatch having more metrics or less. That is, for a metric to be shown in Hyperglance it must be available in Cloudwatch, and correctly configured into Hyperglance. For each metric configured in Hyperglance, if a data mismatch is found between Cloudwatch and Hyperglance, then that metric will NOT be shown.
Briefly going over the XML, we see that there is an entry for each Entity Type that has metrics, out of the box these include:
Other Entity Types may support metrics, however, they have not been included in the out of the box configuration. Each entity type entry (<node-type>) has the following data, associated to it:
- type - The entity type (e.g., EC2-Instance, EBS-Volume)
- core dimension - The base dimension used by Cloudwatch to lookup metrics for this type. A dimension is a name/value pair that helps you to uniquely identify a metric
- metrics - The metrics that Hyperglance will be interested in, for this type
Following our RDS Instance example, the XML contains the following entry:
<node-type> <type>RDS-Instance</type> <core-dimension>DBInstanceIdentifier</core-dimension> <metrics> <metric> ... </metric> </metrics> </node-type>
Most likely, any possible new metric will fall under the previous entity types, so to add a new metric you just have to add an entry to the metrics list. However, if that is not the case, and a new entity type is required, then the the entity type can be found in Hyperglance's attribute panel for that node and the core dimension can be found on the AWS documentation site. For instance, the core dimension for Storage Gateway types is GatewayId. This information was taken from: http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/awssg-metricscollected.html. With this information, we can just add a new <node-type> element in the XML, and add consequent metrics for it. We will not go into greater detail into this process at the moment.
For the metrics themselves, let us go back to the RDS Instance example. The XML entry for this entity type already comes configured with some out of the box metrics, that map into Cloudwatche's own metrics. It does not, nevertheless, have NetworkReceiveThroughput configured into it, so let us add said metric. Metric XML entries (<metric>) have the following structure:
- namespace - The Cloudwatch namespace for this metric
- name - The Cloudwatch metric name
- ui-name - The Hyperglance metric name (exists purely for UI purposes because Cloudwatch metrics may have week names at times)
- unit - The metric's unit
- rollups - A list of rollups. The latter represent the transformation applied to the data values obtained from Cloudwatch. A single metric can have 1 or 5 rollups. These are:
- dimension-groups - A dimension group is a combination of one or more dimensions that can differentiate between different data, for the same metric. We will expatiate this concept when we discuss custom metrics.
To add new metrics we must firstly obtain this information from Cloudwatch. To add NetworkReceiveThroughput to Hyperglance we just have to add an entry in the XML like:
<metric> <namespace>AWS/RDS</namespace> <name>NetworkReceiveThroughput</name> <ui-name>Network Receive Throughput</ui-name> <unit>Bytes/Second</unit> <rollups> <rollup>Average</rollup> <rollup>Maximum</rollup> <rollup>Minimum</rollup> <rollup>Sum</rollup> </rollups> <dimension-groups/> </metric>
Going over each element. The namespace element can be obtained from Cloudwatch, particularly from http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/aws-namespaces.html. The name element is simply the AWS Cloudwatch name for this metric, while the ui-name is the name that will show up on Hyperglance for the specific metric (for a better aesthetic feel). The unit can be seen in the Cloudwatch metric page, as illustrated in the above Cloudwatch Dashboard image. The rollups were, in this case, selected arbitrarily, and are up to each user to decide what fits their needs. Lastly, since this is a simple metric, there are no dimension-groups, represented as an empty element.
Once the metric is defined in the XML, save the changes and restart the Hyperglance server by issuing the command "sudo service wildfly restart" from the CLI. Once the server is back up, you should be able to select the new metric. On Hyperglance you should see something like:
2. Adding metrics when multiple dimensions are involved
Lets assume, by whichever way, a user introduces a new metric for Target Groups into Cloudwatch. Moreover, lets assume that new metric has the following characteristics:
- namespace - AWS/ApplicationELB
- name - TargetResponseTime
- ui-name - Target Response Time
- unit - Seconds
- rollups - Average
Additionally, we needed two dimensions for this metric, TargetGroup and LoadBalancer. The later identify the Load Balancer - Target Group pair that this metric is associated to. As a result a single pair of LoadBalancer-TargetGroup can be viewed as a dimension-group, nevertheless groups don't have a limit on how many dimensions they have. As it stands, one of the dimensions is actually a core dimension (TargetGroup) so LoadBalancer will be an extra dimension.
It would look as follows, on Cloudwatch:
To configure this metric in Hyperglance we must add a new <metric> entry in the XML, alongside metrics for Target-Group node-types. The XML would look like:
<node-type> <type>Target-Group</type> <core-dimension>TargetGroup</core-dimension> <metrics> <metric> <namespace>AWS/ApplicationELB</namespace> <name>TargetResponseTime</name> <ui-name>Target Response Time</ui-name> <unit>Seconds</unit> <rollups> <rollup default="true">Average</rollup> </rollups> <dimension-groups> <group default="true"> <dimension>LoadBalancer</dimension> </group> </dimension-groups> </metric> ... </metrics> </node-type>
Quite similar to the previous example but with more configuration parameters, particularly the dimensions. Each <group> (dimension-group) element aggregates a set of 1 or more <dimension> elements. The latter represent an attribute name on the entity of the type associated to this entry (in this case Target-Group).
And this is all you need if you require extra dimensions besides the main one. Once again, the server must be restarted (sudo service wildfly restart) in order for new the configuration to be taken into consideration. Now, once the respective node is selected, you can see the metric in Hyperglance.