com.wily.introscope.server.webservicesapi.metricsdata
Interface IMetricsDataService

All Known Implementing Classes:
MetricsDataServiceSoapBindingStub

public interface IMetricsDataService

This web service provides methods to get statistics data for specified metrics from Introscope Enterprise Manager.

Specifying metrics: Metrics in Introscope are specified as a combination of Agent Name (the unique name of the agent that is reporting that metric) and a Metric Name.

Agent Names always consist of 3 parts separated by '|' character - host name, process name, and agent name. For example - "MachineFoo|Weblogic|WeblogicAgent".

Metric Names are hierarchical and are separated by '|' character as well. The last part of the Metric Name is seprated by ':' character. For example - "EJB|Session|FooBean:Average Response Time (ms)".

To specify a metric to query statistics, you will have to specify both the Agent Name and the Metric Name. You can either query statistics for an individual metric by specifying the exact Agent Name and Metric Name, or you can query statistics for multiple metrics in one call by specifying a regular expression for the Agent Name and/or Metric Name. Introscope supports standard Perl regular expression syntax.

Note: Keep in mind that the more generic regular expressions you specify for your metrics, the more number of metric statistics will be returned in one call. That can cause OutOfMemory errors both on your Enterprise Manager and on your Web Services client. Such large queries can also cause significant slowdown on the EnterpriseManager. To avoid these situations, Enterprise Manager clamps the maximum number of metrics that are matched for one web service query (the default is 10000, and it can be configured on the EM).

Specifying data granularity: You can query statistics at different granularity levels. The minimum granularity provided by Introscope is 15 seconds. This can be specified using the "dataFrequency" parameter. The value of the "dataFrequency" parameter must be in multiples of 15 seconds. The queries return one record for each "timeslice" in your specified time range. For example, if you specified a time range of 2 hours and a data frequency of 1-hour there will be 2 timeslices and 2 records will be returned. But if you specified a time range of 2 hours and a data frequency of 1-minute, there will be 120 timeslices and 120 records will be returned.

Note: You have to be very careful about the performance impact when specifying data granularity in your queries. For example, if you ask for 2 weeks of dats for 1000 metrics at 15-second data frequency, it will likely cause OutOfMemory errors on both the EM and your web services client. Such large queries can also cause significant slowdown on the EnterpriseManager. For queries that ask for data for a very large time range, 1-hour granularity is recommended.


Method Summary
 DTimeslicedResultSetMetricData[] getLiveMetricData(java.lang.String agentRegex, java.lang.String metricPrefix)
          Gets live metric data for specified metrics, for a specified time range.
 DTimesliceGroupedMetricData[] getMetricData(java.lang.String agentRegex, java.lang.String metricRegex, java.util.Date startTime, java.util.Date endTime, int dataFrequency)
          Gets statistics data for specified metrics, for a specified time range.
 DTimesliceGroupedMetricData[] getTopNMetricData(java.lang.String agentRegex, java.lang.String metricRegex, java.util.Date startTime, java.util.Date endTime, int dataFrequency, int topNCount, boolean decreasingOrder)
          Gets statistics data for specified metrics, for a specified time range.
 

Method Detail

getMetricData

DTimesliceGroupedMetricData[] getMetricData(java.lang.String agentRegex,
                                            java.lang.String metricRegex,
                                            java.util.Date startTime,
                                            java.util.Date endTime,
                                            int dataFrequency)
                                            throws java.rmi.RemoteException,
                                                   IntroscopeWebServicesException
Gets statistics data for specified metrics, for a specified time range.

Parameters:
agentRegex - Agent regular expression. It can be an exact Agent Name as well.
metricRegex - Metric regular expression. It can be an exact Agent Name as well.
startTime - Time range start
endTime - Time range end
dataFrequency - Data frequency in seconds
Returns:
Array of records - one record for each timeslice. Each record will have data for all the matched metrics for that timeslice.
Throws:
java.rmi.RemoteException
IntroscopeWebServicesException

getLiveMetricData

DTimeslicedResultSetMetricData[] getLiveMetricData(java.lang.String agentRegex,
                                                   java.lang.String metricPrefix)
                                                   throws java.rmi.RemoteException,
                                                          IntroscopeWebServicesException
Gets live metric data for specified metrics, for a specified time range.

Parameters:
agentRegex - Agent regular expression. It can be an exact Agent Name as well.
metricRegex - Metric regular expression. It can be an exact Agent Name as well.
Returns:
Array of records - one record for each timeslice. Each record will have data for all the matched metrics for that timeslice.
Throws:
java.rmi.RemoteException
IntroscopeWebServicesException

getTopNMetricData

DTimesliceGroupedMetricData[] getTopNMetricData(java.lang.String agentRegex,
                                                java.lang.String metricRegex,
                                                java.util.Date startTime,
                                                java.util.Date endTime,
                                                int dataFrequency,
                                                int topNCount,
                                                boolean decreasingOrder)
                                                throws java.rmi.RemoteException,
                                                       IntroscopeWebServicesException
Gets statistics data for specified metrics, for a specified time range. All numeric metric that maatch are sorted by the specified sorting order and then clamped to the specified top-N count. All non-numeric metrics that match are returned as well without sorting and clamping. For example, if you specify top-N count as 10, and 20 numeric metrics and 15 non-numeric metrics match the query, the top 10 numeric metrics and all the non-numeric metrics will be returned.

Parameters:
agentRegex - Agent regular expression. It can be an exact Agent Name as well.
metricRegex - Metric regular expression. It can be an exact Agent Name as well.
startTime - Time range start
endTime - Time range end
dataFrequency - Data frequency in seconds
topNCount - The max number of metrics to be returned.
decreasingOrder - Specifies the sorting order.
Returns:
Array of records - one record for each timeslice. Each record will have data for all the matched metrics for that timeslice.
Throws:
java.rmi.RemoteException
IntroscopeWebServicesException


Copyright © 2007 CA Inc. All Rights Reserved.