AWS Developer Tools Blog

Metric Configuration in AWS SDK for Java

As we mentioned in an earlier blog, you can now enable the automatic generation of performance metrics when using the AWS SDK for Java, and have them automatically uploaded to Amazon CloudWatch for monitoring purposes. Sometimes, however, you may want to generate more fine-grained metrics, such as per-host and per-JVM metrics, that are not enabled by default. Or, you may want to customize the name space for the metrics uploaded to Amazon CloudWatch to something more meaningful to your use cases. This is where you may find the metric configuration options helpful.

What options are available?

Here is a quick summary of five metric configuration options that you may find useful:

Option Description Default
metricNameSpace The metric namespace. “AWSSDK/Java”
includePerHostMetrics If specified, additional metrics will be generated on a per-host basis. Per-host level metric is disabled.
jvmMetricName If specified, additional metrics will be generated on a per-JVM basis. Per-JVM level metric is disabled.
credentialFile Used to specify an AWS credential property file for uploading metrics to Amazon CloudWatch. The default mechanism of DefaultAWSCredentialsProviderChain is used.
cloudwatchRegion The Amazon CloudWatch region for metrics uploading purposes. “us-east-1”

Are there any sample metric configurations?

Here are three sample metric configurations via system properties.

Sample 1: How to enable per host metrics

Suppose you are running the same application on multiple hosts, and you want to

  1. specify your own metric name space of “MyApp”
  2. generate additional metrics on a per-host basis
  3. make use of a AWS credential property file that resides at “/path/cred.property” on each host
  4. upload the metrics to the Amazon CloudWatch region “us-west-2”

You can do so by specifying the system property:

-Dcom.amazonaws.sdk.enableDefaultMetrics=metricNameSpace=MyApp,
  includePerHostMetrics,credentialFile=/path/cred.property,
  cloudwatchRegion=us-west-2

(All in a single line with no space.)

That’s it—per host metric will be enabled once the JVM is started.

Sample 2: How to enable both per-host and per-JVM metrics

This is similar to sample 1, but suppose your application involves running two instances of JVMs, both accessing AWS on each host. Now, you may want to generate metrics not only on a per-host basis, but also on a per-JVM basis. We can do so by giving the two JVMs different names. Let’s name the first JVM “Gamma”, and the second “Delta”. For the first JVM, this translates to specifying the system property:

-Dcom.amazonaws.sdk.enableDefaultMetrics=metricNameSpace=MyApp,
  includePerHostMetrics,credentialFile=/path/cred.property,
  cloudwatchRegion=us-west-2,jvmMetricName=Gamma

Similarly, for the second JVM:

-Dcom.amazonaws.sdk.enableDefaultMetrics=metricNameSpace=MyApp,
  includePerHostMetrics,credentialFile=/path/cred.property,
  cloudwatchRegion=us-west-2,jvmMetricName=Delta

(All in a single line with no space.)

Note the two specifications above differ only in the value of jvmMetricName. You should then be able to visualize the metrics aggregated at the respective levels in the Amazon CloudWatch console.

Sample 3: How to enable per-JVM but not per-host metrics

This is almost the same as sample 2. All you need to do is to remove the includePerHostMetrics option, like so for the first JVM:

-Dcom.amazonaws.sdk.enableDefaultMetrics=metricNameSpace=MyApp,
  credentialFile=/path/cred.property,
  cloudwatchRegion=us-west-2,jvmMetricName=Gamma

For the second JVM:

-Dcom.amazonaws.sdk.enableDefaultMetrics=metricNameSpace=MyApp,
  credentialFile=/path/cred.property,
  cloudwatchRegion=us-west-2,jvmMetricName=Delta

(All in a single line with no space.)

More details are available in the javadoc of AwsSdkMetrics, and the metric package summary. That’s all for now. Hope you find these options useful, and happy monitoring !