Metric data created by the controller and applications can assist you when you are troubleshooting issues with the controller or network.
The curl commands in this section interact with the metrics/apps
REST API to display information about metric data collected by the controller. These commands must be used on individual controllers; they do not return information from controller teams.
Metrics are created by controller components or applications and can be of several different types, such as timers, counters, gauges, and histograms.
When the controller component or application creates a metric, it specifies what to do with the resulting metric values. Metric values can be processed in one or more of the following ways:
Metric values that are persisted to disk
For metric values that are persisted to disk:
-
The time-series values for each individual metric can be persisted at intervals of 1, 5, or 15 minutes. Controller administrators configure the default persistence interval using the
MetricManagerComponent
controller component. A controller component or application that creates a metric can override the default persistence interval for that metric. -
Each persisted value represents the value of the metric over the elapsed persistence interval. For example, for a counter that increments from 100 to 145 during a 5-minute interval, the persisted value for the interval is 45, which is the value of the counter at the start of the interval subtracted from the value of the counter at the end of the interval. For each type of metric, there is a different method of computing the persisted value.
-
Because some metric values are not updated at a steady rate, the persisted information for a metric value includes the raw value and the time over which the value accrued. Providing this information enables the metric viewer to normalize data. For example if the counter value was updated only during the last 3 minutes of the 5-minute interval for which it was persisted:
-
The raw value accrued over the interval is 45, which is the value at the start of the interval subtracted from the value at the end of the interval.
-
The persisted value includes both the raw value and the time over which the data was accrued, which is 3 minutes.
-
The persistence interval configured for the metric is 5 minutes.
-
A normalized rate of accrual over the interval is 15 increments per minute (45 increments divided by 3 minutes) or 75 for the entire 5-minute interval.
-
-
Controller administrators use
MetricManagerComponent
controller component to configure the length of time the controller retains persisted metric values on disk. Controller components and applications cannot override this retention period.
Metric values that are exposed via JMX
For metric values that are exposed via JMX:
-
The metric value reported by JMX is the most recently-reported raw value. The value does not include time interval information or any normalization data such as accrual rate. For example, for a counter that increments from 100 to 145 during a 5-minute interval, but only increments during the last 3 minutes of that 5 minute interval, the metric value reported by JMX depends on when you query JMX for the most recent value. For example:
-
The value JMX reports for the metric at the beginning of the interval is 100.
-
The value JMX reports for the metric at the end of the interval is 145.
-
The value JMX reports for the metric at any time during the first 2 minutes of the interval is 100, because, in this example, the counter does not start incrementing until the last 3 minutes of the interval.
-
The value JMX reports for the metric at minute 4 could be any value from 100 through 145 depending on how frequently the counter value is updated by the creating application or component between minute 2 and the end of the interval.
-
Metric values in memory but not persisted to disk or exposed via JMX
For metric values that are retained in memory without being persisted or exposed via JMX:
-
The component or application can expose this metric data in other ways, such as by including the values in the appropriate section of a controller support report . In such cases, the values exposed are the most recent, raw values (as would be shown if they were exposed via JMX) instead of values for a specific time interval (such as values that are persisted to disk).
When a metric is created, it is associated with the following text strings that, taken as a combination, uniquely identify the metric:
You use the application ID as input for metrics
commands that require an application ID in the URL.
-
To list the application IDs for all applications—including those that are part of the controller itself—that have persisted metric data to disk, use the following curl command:
curl --noproxy
controller_ip
-X GET \ --header "X-Auth-Token:token
" --fail -ksSfL \ --url "https://controller_ip
:8443/sdn/v2.0/metrics/apps"
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/apps"
Command output
In this example, only the base controller itself has persisted metric data to disk. The application id is: com.hp.sdn
This example shows the JSON output as returned by the curl command:
{"apps":[{"app_id":"com.hp.sdn","app_name":"HP VAN SDN Controller"}]}
This example shows the JSON output formatted for readability:
{ "apps":[ { "app_id":"com.hp.sdn", "app_name":"HP VAN SDN Controller" } ] }
-
To list all of the metrics available for a specific application, use the following curl command:
curl --noproxy
controller_ip
-X GET \ --header "X-Auth-Token:token
" --fail -ksSfL \ --url "https://controller_ip
:8443/sdn/v2.0/metrics/apps/app_id
\ ?name=name
&primary_tag=primary_tag
&secondary_tag=secondary_tag
"
Optional parameters
Name and value pairs after the ?
character, separated by the &
character, are optional parameters:
The name of the metric. The controller lists only the metrics that have a name that matches the specified value. If you do not specify a name, the controller lists all metrics. |
|
The name of the primary tag. The controller lists only the metrics that have a primary tag that matches the specified value. |
|
The name of the primary tag. The controller lists only the metrics that have a secondary tag that matches the specified value. |
If you specify more than one parameter, the controller lists only those metrics that match all the parameters you specify.
If you do not specify a value for a parameter, the controller does not filter the results based on that parameter.
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/apps/com.hp.sdn"
Command output
This example shows a partial listing of the output from the example command.
The uid
for a metric is the unique identifier assigned to the metric on the controller.
{ "metrics":[ { "app_id":"com.hp.sdn", "type":"RATIO_GAUGE", "name":"cpuLoadSystem", "description":"The recent CPU usage of the system.", "primary_tag":"jvm", "secondary_tag":"operatingSystem", "jmx":false, "persistence":true, "summary_interval":"ONE", "uid":"42f65cd8-03c3-4cad-9788-012d513e3c0f" }, { "app_id":"com.hp.sdn", "type":"GAUGE","name":"committedBytes", "description":"The amount of non-heap memory in bytes committed for the JVM to use.", "primary_tag":"jvm", "secondary_tag":"memoryNonHeap", "jmx":false, "persistence":true, "summary_interval":"ONE", "uid":"b82f5b00-0373-4a23-b5a8-bbda7eec44cb" }, { "app_id":"com.hp.sdn", "type":"GAUGE","name":"countTerminated", "description":"Number of JVM threads that had exited.", "primary_tag":"jvm", "secondary_tag":"threads", "jmx":false, "persistence":true, "summary_interval":"ONE", "uid":"0e9fe62e-01fd-42e9-88a6-f92021a5e786" }, . . . { "app_id":"com.hp.sdn", "type":"ROLLING_COUNTER", "name":"count", "description":"The number of JVM garbage collections actions during the sampling interval.", "primary_tag":"jvm", "secondary_tag":"garbageCollection", "jmx":false, "persistence":true, "summary_interval":"ONE", "uid":"d62c49d4-46b3-4c2c-be60-24f6fa6c6bf6" }, . . .
-
To list the primary tags associated with the metrics persisted by a specific application, use the following curl command:
curl --noproxy
controller_ip
-X GET \ --header "X-Auth-Token:token
" --fail -ksSfL \ --url "https://controller_ip
:8443/sdn/v2.0/metrics/apps/app_id
/primaries\ ?name=metric_name
"
Optional parameters
Name and value pairs after the ?
character, separated by the &
character, are optional parameters:
If you do not specify a value for a parameter, the controller does not filter the results based on that parameter.
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/apps/com.hp.sdn/primaries"
Command output
The only primary tag associated with the controller itself in this example is jvm
.
{ "primaries":[ "jvm" ] }
-
To list the the secondary tags associated with the metrics persisted by a specific application, use the following curl command:
curl --noproxy
controller_ip
-X GET \ --header "X-Auth-Token:token
" --fail -ksSfL \ --url "https://controller_ip
:8443/sdn/v2.0/metrics/apps/app_id
/secondaries\ ?name=name
&primary_tag=primary_tag
"
Optional parameters
Name and value pairs after the ?
character, separated by the &
character, are optional parameters:
The name of the metric. The controller lists only the metrics that have a name that matches the specified value. |
|
The name of the primary tag. The controller lists only the metrics that have a primary tag that matches the specified value. |
If you specify more than one parameter, the controller lists only those metrics that match all the parameters you specify.
If you do not specify a value for a parameter, the controller does not filter the results based on that parameter.
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/apps/com.hp.sdn/secondaries"
Command output
{ "secondaries":[ "nioDirectMemory", "operatingSystem", "threads", "garbageCollection", "memoryNonHeap", "memoryHeap", "memoryTotal", "nioMappedMemory" ] }
-
To list the names of the metrics persisted by a specific application, use the following curl command:
curl --noproxy
controller_ip
-X GET \ --header "X-Auth-Token:token
" --fail -ksSfL \ --url "https://controller_ip
:8443/sdn/v2.0/metrics/apps/app_id
/names\ ?primary_tag=primary_tag
&secondary_tag=secondary_tag
"
Optional parameters
Name and value pairs after the ?
character, separated by the &
character, are optional parameters:
The name of the primary tag. The controller lists only the metrics that have a primary tag that matches the specified value. |
|
The name of the primary tag. The controller lists only the metrics that have a secondary tag that matches the specified value. |
If you specify more than one parameter, the controller lists only those metrics that match all the parameters you specify.
If you do not specify a value for a parameter, the controller does not filter the results based on that parameter.
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/apps/com.hp.sdn/names"
Command output
This example shows a partial listing of the output from the example command.
{ "names":[ "averageBufferUsedBytes", "countDeadlocked", "bufferCapacityBytes", "count", "countNew", "bufferCount", "countWaiting", "fileDescriptorsOpen", "uptimeMs", "countTerminated", "elapsedMs", "countTimedWaiting", "countDaemon", . . . "countBlocked", "committedBytes" ] }
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/431b746e-e62e-4874-a801-b1438eaac635"
Command output
{ "metric":{ "app_id":"com.hp.sdn", "type":"GAUGE", "name":"usedBytes", "description":"The amount of heap memory currently being used by the JVM in bytes.", "primary_tag":"jvm", "secondary_tag":"memoryHeap", "jmx":false, "persistence":true, "summary_interval":"ONE", "uid":"431b746e-e62e-4874-a801-b1438eaac635" } }
More information
Viewing the metrics persisted by a specific application |
curl --noproxy
controller_ip
-X GET \
--header "X-Auth-Token:
token
" --fail -ksSfL \
--url "https://
controller_ip
:8443/sdn/v2.0/metrics/
metric_uid
/values\
?start=
start
&end=
end
&interval=
interval
"
Optional parameters
Name and value pairs after the ?
character, separated by the &
character, are optional parameters:
The earliest time to query for time-series data. The date and time in must be in the format |
|
The most recent time to query for time-series data. The date and time in must be in the format |
|
The interval each returned data point is to represent. This parameter is required if you specify the |
If you do not specify parameters, only the last persisted time-series value for the metric is returned.
Specifying an interval summarizes the data, and enables you to quickly look for anomalous data. For example, instead of viewing 1440 discrete minute-by-minute values for a specific metric over the course of a day, you can request that each returned value represent 60 minutes so that the number of returned values is more manageable and can be more easily inspected.
Summarizing the returned data for a period typically results in larger values for the metrics themselves and larger values for the milliseconds spanned. The computation of the values returned over longer intervals depends upon the type of metric. For example, gauge values are averaged over the data points encompassed in the summary, but counter values are summed over the summary interval.
Command example
curl --noproxy 10.1.1.9 -X GET \
--header "X-Auth-Token:3d61f0d3e61349359e6dbd82ec02c113" --fail -ksSfL \
--url "https://10.1.1.9:8443/sdn/v2.0/metrics/431b746e-e62e-4874-a801-b1438eaac635?start=2014-09-23+18:00&interval=5"
Command output
{ "metric_values":{ "uid":"431b746e-e62e-4874-a801-b1438eaac635", "type":"GAUGE", "datapoint_count":6, "datapoints":[ { "update_time":"Tue Sep 23 18:03:55 PDT 2014", "milliseconds_span":300000, "last":3.274097568E8 }, { "update_time":"Tue Sep 23 18:08:55 PDT 2014", "milliseconds_span":300000, "last":3.133927072E8 }, { "update_time":"Tue Sep 23 18:13:55 PDT 2014", "milliseconds_span":300000, "last":2.154562624E8 }, { "update_time":"Tue Sep 23 18:18:55 PDT 2014", "milliseconds_span":300000, "last":4.192128832E8 }, { "update_time":"Tue Sep 23 18:23:55 PDT 2014", "milliseconds_span":300000, "last":3.864813136E8 }, { "update_time":"Tue Sep 23 18:27:55 PDT 2014", "milliseconds_span":240000, "last":3.847236E8 } ] } }