public enum AwsSdkMetrics extends java.lang.Enum<AwsSdkMetrics>
The default metric collection of the Java AWS SDK is disabled by default. To
enable it, simply specify the system property
"com.amazonaws.sdk.enableDefaultMetrics" when starting up the JVM.
When the system property is specified, a default metric collector will be
started at the AWS SDK level. The default implementation uploads the
request/response metrics captured to Amazon CloudWatch using AWS credentials
obtained via the DefaultAWSCredentialsProviderChain
.
For additional optional attributes that can be specified for the system property, please read the javadoc of the individual fields of this class for more details.
Instead of via system properties, the default AWS SDK metric collection can
also be enabled programmatically via enableDefaultMetrics()
.
Similarly, metric collection at the AWS SDK level can be disabled via
disableMetrics()
.
Clients who needs to fully customize the metric collection can implement the
SPI MetricCollector
, and then replace the default AWS SDK
implementation of the collector via
setMetricCollector(MetricCollector)
.
Alternatively, for limited customization of the internal collector implementation provided by the AWS SDK, one can extend the internal Amazon CloudWatch metric collector. See the javadoc at com.amazonaws.metrics.internal.cloudwatch.CloudWatchMetricConfig for more details.
Modifier and Type | Class and Description |
---|---|
private static class |
AwsSdkMetrics.MetricRegistry
Used as a registry for the predefined metrics to be captured by the
metric collector at the AWS SDK level.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
AWS_CREDENTAIL_PROPERTIES_FILE
Deprecated.
in favor of
AWS_CREDENTIAL_PROPERTIES_FILE |
static java.lang.String |
AWS_CREDENTIAL_PROPERTIES_FILE
Used to specify an AWS credential property file.
|
static java.lang.String |
CLOUDWATCH_REGION
Used to specify the Amazon CloudWatch region for metrics uploading purposes.
|
private static java.lang.String |
credentialFile |
private static AWSCredentialsProvider |
credentialProvider |
private static java.lang.String |
DEFAULT_METRIC_COLLECTOR_FACTORY |
static java.lang.String |
DEFAULT_METRIC_NAMESPACE |
private static boolean |
defaultMetricsEnabled
True if the system property
#DEFAULT_METRICS_SYSTEM_PROPERTY has
been set; false otherwise. |
private static boolean |
dirtyEnabling
Used to disallow re-entrancy in enabling the default metric collection system.
|
private static java.lang.String |
ENABLE_HTTP_SOCKET_READ_METRIC
Used to explicitly enable
AWSRequestMetrics.Field.HttpSocketReadTime for recording socket read time. |
static java.lang.String |
EXCLUDE_MACHINE_METRICS
Used to exclude the generation of JVM metrics when the AWS SDK default
metrics is enabled.
|
static java.lang.String |
HOST_METRIC_NAME
Used to explicitly specify the host name for metric purposes, instead of
detecting the host name via
InetAddress when the AWS SDK default
metrics is enabled. |
private static java.lang.String |
hostMetricName |
private static boolean |
httpSocketReadMetricEnabled
True if socket read time metric is enabled; false otherwise.
|
static java.lang.String |
INCLUDE_PER_HOST_METRICS
Used to generate per host level metrics when the AWS SDK default
metrics is enabled.
|
static java.lang.String |
JVM_METRIC_NAME
Used to generate per JVM level metrics when the AWS SDK default
metrics is enabled.
|
private static java.lang.String |
jvmMetricName
No JVM level metrics is generated if this field is set to null or blank.
|
private static org.apache.commons.logging.Log |
log |
private static boolean |
machineMetricsExcluded
True if machine metrics is to be excluded; false otherwise.
|
private static java.lang.String |
MBEAN_OBJECT_NAME |
private static MetricCollector |
mc |
static java.lang.String |
METRIC_NAME_SPACE
Used to specify a custom metric name space.
|
static java.lang.String |
METRIC_QUEUE_SIZE
Used to specify the internal in-memory queue size for queuing metrics
data points.
|
private static java.lang.String |
metricNameSpace |
private static java.lang.Integer |
metricQueueSize |
private static boolean |
perHostMetricsIncluded
True if per-host metrics is to be included; false if per-host metrics is
to be excluded when
hostMetricName is not specified. |
static java.lang.String |
QUEUE_POLL_TIMEOUT_MILLI
Used to specify the internal queue polling timeout in millisecond.
|
private static java.lang.Long |
queuePollTimeoutMilli |
private static Regions |
region |
private static java.lang.String |
registeredAdminMbeanName
Object name under which the Admin Mbean of the current classloader is
registered.
|
private static AwsSdkMetrics.MetricRegistry |
registry |
private static boolean |
singleMetricNamespace
True if the same metric namespace is to be used for all levels (such as
JVM level, host-level, etc.) of AWS Cloudwatch Metrics for the Java SDK;
false otherwise.
|
static java.lang.String |
USE_SINGLE_METRIC_NAMESPACE
Used to enable the use of a single metric namespace for all levels of SDK
generated CloudWatch metrics such as JVM level, host level, etc.
|
Modifier and Type | Method and Description |
---|---|
static boolean |
add(MetricType type)
Adds the given metric type to the registry of predefined metrics to be
captured at the AWS SDK level.
|
static <T extends MetricType> |
addAll(java.util.Collection<T> types)
Adds the given metric types to the registry of predefined metrics to be
captured at the AWS SDK level.
|
static void |
disableMetrics()
Convenient method to disable the metric collector at the AWS SDK
level.
|
static boolean |
enableDefaultMetrics()
Starts the default AWS SDK metric collector, but
only if no metric collector is currently in use at the AWS SDK
level.
|
static void |
enableHttpSocketReadMetric()
Used to enable
AWSRequestMetrics.Field.HttpSocketReadTime metric since by default it is disabled. |
static java.lang.String |
getCredentailFile()
Returns the last set AWS credential file, or null if there is none.
|
static AWSCredentialsProvider |
getCredentialProvider()
Returns the credential provider for the default AWS SDK metric implementation.
|
static java.lang.String |
getHostMetricName()
Returns the host name for generating per-host level metrics; or
null or blank if the host is to be automatically detected via
InetAddress . |
(package private) static MetricCollector |
getInternalMetricCollector()
This method should never be called by anyone except the JMX MBean used
for administrative purposes only.
|
static java.lang.String |
getJvmMetricName()
Returns the name of the JVM for generating per-JVM level metrics;
or null or blank if per-JVM level metrics are disabled.
|
static <T extends MetricCollector> |
getMetricCollector() |
static java.lang.String |
getMetricNameSpace()
Returns the metric name space, which is never null or blank.
|
static java.lang.Integer |
getMetricQueueSize()
Returns the internal metric queue size to be used for the default AWS SDK
metric collector; or null if the default is to be used.
|
static java.util.Set<MetricType> |
getPredefinedMetrics()
Returns an unmodifiable set of the current predefined metrics.
|
static java.lang.Long |
getQueuePollTimeoutMilli()
Returns the internal metric queue timeout in millisecond to be used for
the default AWS SDK metric collector; or null if the default is to be
used.
|
static Regions |
getRegion()
Returns the region configured for the default AWS SDK metric collector;
or null if the default is to be used.
|
static java.lang.String |
getRegisteredAdminMbeanName()
Returns the name of the registered admin mbean; or null if the admin
mbean is not currently registered.
|
static <T extends RequestMetricCollector> |
getRequestMetricCollector()
Returns a non-null request metric collector for the SDK.
|
static <T extends ServiceMetricCollector> |
getServiceMetricCollector() |
static boolean |
isDefaultMetricsEnabled()
Returns true if the system property
SDKGlobalConfiguration.DEFAULT_METRICS_SYSTEM_PROPERTY has been
set; false otherwise. |
static boolean |
isHttpSocketReadMetricEnabled()
Returns true if HttpSocketReadMetric is enabled; false otherwise.
|
static boolean |
isMachineMetricExcluded()
Returns true if machine metrics is to be excluded.
|
static boolean |
isMetricAdminMBeanRegistered()
Returns true if the metric admin MBean is currently registered for JMX
access; false otherwise.
|
static boolean |
isMetricsEnabled()
Returns true if metrics at the AWS SDK level is enabled; false
if disabled.
|
static boolean |
isPerHostMetricEnabled()
Returns true if per-host metrics is enabled; false otherwise.
|
static boolean |
isPerHostMetricIncluded()
Returns true if the per-host metrics flag has been set; false otherwise.
|
static boolean |
isSingleMetricNamespace()
Returns true if a single metric name space is to be used for all
levels of SDK generated CloudWatch metrics, including JVM level, host
level, etc.; false otherwise.
|
static boolean |
registerMetricAdminMBean()
Registers the metric admin MBean for JMX access for the current
classloader.
|
static boolean |
remove(MetricType type)
Removes the given metric type from the registry of predefined metrics to
be captured at the AWS SDK level.
|
static <T extends MetricType> |
set(java.util.Collection<T> types)
Sets the given metric types to replace the registry of predefined metrics
to be captured at the AWS SDK level.
|
static void |
setCredentialFile(java.lang.String filepath)
Sets the AWS credential file to be used for accessing Amazon CloudWatch.
|
private static void |
setCredentialFile0(java.lang.String filepath)
Internal method to implement the
setCredentialFile(String) . |
static void |
setCredentialProvider(AWSCredentialsProvider provider)
Sets the credential provider for the default AWS SDK metric
implementation; or null if the default is to be used.
|
static void |
setHostMetricName(java.lang.String hostMetricName)
Sets the host name for generating per-host level metrics.
|
static void |
setJvmMetricName(java.lang.String jvmMetricName)
Sets the name of the JVM for generating per-JVM level metrics.
|
static void |
setMachineMetricsExcluded(boolean excludeMachineMetrics)
Used to set whether the machine metrics is to be excluded.
|
static void |
setMetricCollector(MetricCollector mc)
Sets the metric collector to be used by the AWS SDK, and stop the
previously running collector used by the AWS SDK, if any.
|
static void |
setMetricNameSpace(java.lang.String metricNameSpace)
Sets the metric name space.
|
static void |
setMetricQueueSize(java.lang.Integer size)
Sets the metric queue size to be used for the default AWS SDK metric collector;
or null if the default is to be used.
|
static void |
setPerHostMetricsIncluded(boolean includePerHostMetrics)
Used to set whether the per-host metrics is to be included.
|
static void |
setQueuePollTimeoutMilli(java.lang.Long timeoutMilli)
Sets the queue poll time in millisecond to be used for the default AWS
SDK metric collector; or null if the default is to be used.
|
static void |
setRegion(Regions region)
Sets the region to be used for the default AWS SDK metric collector;
or null if the default is to be used.
|
static void |
setSingleMetricNamespace(boolean singleMetricNamespace)
Used to set whether a single metric name space is to be used for all
levels of SDK generated CloudWatch metrics, including JVM level, host
level, etc.
|
static boolean |
unregisterMetricAdminMBean()
Unregisters the metric admin MBean from JMX for the current classloader.
|
static AwsSdkMetrics |
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.
|
static AwsSdkMetrics[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
private static final org.apache.commons.logging.Log log
public static final java.lang.String DEFAULT_METRIC_NAMESPACE
private static final java.lang.String MBEAN_OBJECT_NAME
private static volatile java.lang.String registeredAdminMbeanName
public static final java.lang.String USE_SINGLE_METRIC_NAMESPACE
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=useSingleMetricNamespace
public static final java.lang.String EXCLUDE_MACHINE_METRICS
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=excludeJvmMetrics
public static final java.lang.String INCLUDE_PER_HOST_METRICS
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=includePerHostMetrics
public static final java.lang.String AWS_CREDENTAIL_PROPERTIES_FILE
AWS_CREDENTIAL_PROPERTIES_FILE
DefaultAWSCredentialsProviderChain
is used.
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties
public static final java.lang.String AWS_CREDENTIAL_PROPERTIES_FILE
DefaultAWSCredentialsProviderChain
is used.
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties
public static final java.lang.String CLOUDWATCH_REGION
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=cloudwatchRegion=us-west-2
public static final java.lang.String METRIC_QUEUE_SIZE
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=metricQueueSize=1000
public static final java.lang.String QUEUE_POLL_TIMEOUT_MILLI
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=getQueuePollTimeoutMilli=60000
public static final java.lang.String METRIC_NAME_SPACE
DEFAULT_METRIC_NAMESPACE
.
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=metricNameSpace=MyNameSpace
public static final java.lang.String JVM_METRIC_NAME
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=jvmMetricName=Tomcat1
public static final java.lang.String HOST_METRIC_NAME
InetAddress
when the AWS SDK default
metrics is enabled. Specifying the host name also has the side effecting
of enabling per host level metrics.
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=hostMetricName=MyHost
private static final java.lang.String DEFAULT_METRIC_COLLECTOR_FACTORY
private static final java.lang.String ENABLE_HTTP_SOCKET_READ_METRIC
AWSRequestMetrics.Field.HttpSocketReadTime
for recording socket read time.
Example: -Dcom.amazonaws.sdk.enableDefaultMetrics=enableHttpSocketReadMetric
private static final boolean defaultMetricsEnabled
#DEFAULT_METRICS_SYSTEM_PROPERTY
has
been set; false otherwise.private static volatile AWSCredentialsProvider credentialProvider
private static volatile boolean machineMetricsExcluded
private static volatile boolean perHostMetricsIncluded
hostMetricName
is not specified. In the
absence of hostMetricName
, the host name will be automatically
detected via InetAddress
.private static volatile boolean httpSocketReadMetricEnabled
AWSRequestMetrics.Field.HttpSocketReadTime
could have a big impact to performance, disabled by default.private static volatile Regions region
private static volatile java.lang.Integer metricQueueSize
private static volatile java.lang.Long queuePollTimeoutMilli
private static volatile java.lang.String metricNameSpace
private static volatile java.lang.String credentialFile
private static volatile java.lang.String jvmMetricName
private static volatile java.lang.String hostMetricName
private static volatile boolean singleMetricNamespace
private static final AwsSdkMetrics.MetricRegistry registry
private static volatile MetricCollector mc
private static boolean dirtyEnabling
public static AwsSdkMetrics[] values()
for (AwsSdkMetrics c : AwsSdkMetrics.values()) System.out.println(c);
public static AwsSdkMetrics valueOf(java.lang.String name)
name
- the name of the enum constant to be returned.java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is nullpublic static boolean isMetricAdminMBeanRegistered()
public static java.lang.String getRegisteredAdminMbeanName()
public static boolean registerMetricAdminMBean()
MBEAN_OBJECT_NAME
but with an
additional suffix in the format of "/public static boolean unregisterMetricAdminMBean()
public static <T extends RequestMetricCollector> T getRequestMetricCollector()
setMetricCollector(MetricCollector)
and the
SDKGlobalConfiguration.DEFAULT_METRICS_SYSTEM_PROPERTY
has been set, then this method
will initialize and return the default metric collector provided by the
AWS SDK on a best-attempt basis.public static <T extends ServiceMetricCollector> T getServiceMetricCollector()
static MetricCollector getInternalMetricCollector()
public static <T extends MetricCollector> T getMetricCollector()
public static void setMetricCollector(MetricCollector mc)
Caller of this method is responsible for starting the new metric collector specified as the input parameter.
mc
- the metric collector to be used by the AWS SDK; or
null if no metric collection is to be performed
at the AWS SDK level.RequestMetricCollector
,
RequestMetricCollector.NONE
public static void setMachineMetricsExcluded(boolean excludeMachineMetrics)
excludeMachineMetrics
- true if machine metrics is to be excluded;
false otherwise.public static void setPerHostMetricsIncluded(boolean includePerHostMetrics)
includePerHostMetrics
- true if per-host metrics is to be included;
false otherwise.public static void enableHttpSocketReadMetric()
AWSRequestMetrics.Field.HttpSocketReadTime
metric since by default it is disabled.public static boolean isDefaultMetricsEnabled()
SDKGlobalConfiguration.DEFAULT_METRICS_SYSTEM_PROPERTY
has been
set; false otherwise.public static boolean isSingleMetricNamespace()
public static void setSingleMetricNamespace(boolean singleMetricNamespace)
singleMetricNamespace
- true if single metric name is to be used; false otherwise.public static boolean isMetricsEnabled()
public static boolean isMachineMetricExcluded()
public static boolean isPerHostMetricIncluded()
public static boolean isPerHostMetricEnabled()
public static boolean isHttpSocketReadMetricEnabled()
public static boolean enableDefaultMetrics()
public static void disableMetrics()
public static boolean add(MetricType type)
public static <T extends MetricType> boolean addAll(java.util.Collection<T> types)
public static <T extends MetricType> void set(java.util.Collection<T> types)
public static boolean remove(MetricType type)
public static java.util.Set<MetricType> getPredefinedMetrics()
public static AWSCredentialsProvider getCredentialProvider()
java.lang.SecurityException
- if called outside the default AWS SDK metric implementation.public static void setCredentialProvider(AWSCredentialsProvider provider)
public static Regions getRegion()
public static void setRegion(Regions region)
public static java.lang.String getCredentailFile()
public static void setCredentialFile(java.lang.String filepath) throws java.io.FileNotFoundException, java.io.IOException
java.io.FileNotFoundException
java.io.IOException
private static void setCredentialFile0(java.lang.String filepath) throws java.io.FileNotFoundException, java.io.IOException
setCredentialFile(String)
.java.io.FileNotFoundException
java.io.IOException
public static java.lang.Integer getMetricQueueSize()
public static void setMetricQueueSize(java.lang.Integer size)
public static java.lang.Long getQueuePollTimeoutMilli()
public static void setQueuePollTimeoutMilli(java.lang.Long timeoutMilli)
public static java.lang.String getMetricNameSpace()
public static void setMetricNameSpace(java.lang.String metricNameSpace)
metricNameSpace
- metric name space which must neither be null or blank.java.lang.IllegalArgumentException
- if the specified metric name space is either null or blank.public static java.lang.String getJvmMetricName()
public static void setJvmMetricName(java.lang.String jvmMetricName)
jvmMetricName
- name of the JVM for generating per-JVM level metrics; or null
or blank if per-JVM level metrics are to be disabled.public static java.lang.String getHostMetricName()
InetAddress
.public static void setHostMetricName(java.lang.String hostMetricName)
hostMetricName
- host name for generating per-host level metrics; or
null or blank if the host is to be automatically detected via
InetAddress
.