List Performance History

Service name: list_performance_history

https://SERVER/api/?apikey=yourAPIkey&service=list_performance_history

&required_parameters=required_parameters

[&optional_parameters=optional_parameters]

Obtains the data relating to all the Performance and Bandwidth Monitoring Checks running on the specified device.

Data is available for 24 hours at 15 minute intervals and for 8 days at hourly intervals. If data is needed for longer then it will need to be stored; for efficiency use the since parameter to only obtain new data.

Note: The Windows Agent supports the Performance Monitoring Check for workstations.

Parameters

Default

0

0

0

0

Example Service Call =list_performance_history

https://SERVER/api/?apikey=yourAPIkey&service=list_performance_history&deviceid=DEVICEID&interval=INTERVAL&since=SINCE

Example Response - Performance Monitoring Check - Processor Queue Length (Windows)

<example>

<result created="2012-04-05T10:48:40+01:00" host="SERVER" status="OK">

<bandwidth>

<host>

 <name>example.com port 12345[Descriptive name of check]</name>

 <host>example.com[IP address or hostname to identify the check]</host>

 <check_id>909090909[id of check]</check_id>

 <receive>2000[threshold rate in whole kB/s]</receive>

 <transmit>2000[threshold rate in whole kB/s]</transmit>

 <history>

 <data>

  <start>2013-09-16 12:00:00[first second of interval]</start>

  <end>2013-09-23 10:59:59[last second of interval, note duration can be more than requested if consecutive intervals have the same values]</end>

  <receive>[actual rate in kB/s e.g. 0.085]</receive>

  <transmit>[actual rate in kB/s e.g. 150.125]<//transmit>

 </data>

 [...more data elements...]

 </history>

</host>

[...more host elements...]

</bandwidth>

<disk_load>

<disk>

 <disk>0 C: D: E:[identification info for the physical disk]</disk>

 <check_id>909090909[id of check]</check_id>

 <read_queue_length>2[threshold queue length, whole items]</read_queue_length>

 <write_queue_length>2[threshold queue length, whole items]</write_queue_length>

 <average_disk_time>50[threshold disk time percentage]</average_disk_time>

 <history>

 <data>

  <start>2013-09-15 12:00:00[start of interval]</start>

  <end>2013-09-15 12:59:59[end of interval]</end>

  <disk_time_average>0.048[average disk time]</disk_time_average>

  <disk_time_max>2.554[maximum disk time]</disk_time_max>

  <read_queue_average>0[average queue length]</read_queue_average>

  <read_queue_max>0.018[maximum queue length, fractional as instantaneous data not available]</read_queue_max>

  <write_queue_average>0.00025[average queue length]</write_queue_average>

  <write_queue_max>0.026[maximum queue length, fractional as instantaneous data not available]</write_queue_max>

 </data>

 [...more data elements...]

 </history>

</disk>

[...more disk elements...]

</disk_load>

<cpu_queue>

<check_id>909090909[id of check]</check_id>

<average_length>2[threshold queue length; whole number]</average_length>

<history>

 <data>

 <start>2013-09-15 12:00:00[start of interval]</start>

 <end>2013-09-15 12:59:59[end of interval]</end>

 <queue_average>0.0795[actual average]</queue_average>

 <queue_max>2[actual maximum]</queue_max>

 </data>

 [...more data elements...]

</history>

</cpu_queue>

<cpu_load>

<check_id>909090909[id of check]</check_id>

<average_load>70[threshold load percentage]</average_load>

<history>

 <data>

 <start>2013-09-16 18:00:00</start>

 <end>2013-09-16 18:59:59</end>

 <cpu>[note the list of CPUs is only included if there are 2, 3 or 4, for a single CPU the load_average and load_max will be reported directly in the data element; for more than 4 CPUs the averages across all of them will be reported in the same way as a single CPU system]

  <cpu_id>1[id of CPU, counts from 1, might not match hardware ids; only if more than 1 CPU]</cpu_id>

  <load_average>0.98825[average load]</load_average>

  <load_max>6.875[maximum load over smallest measurable timeframe]</load_max>

 </cpu>

 <cpu>

  <cpu_id>2</cpu_id>

  <load_average>0.27025</load_average>

  <load_max>4.063</load_max>

 </cpu>

 [...more cpu elements...]

 </data>

 [...more data elements...]

</history>

</cpu_load>

<network_usage>

<interface>

 <adapter>HP NC7782 Gigabit Server Adapter[descriptive name]</adapter>

 <check_id>909090909[id of check]</check_id>

 <average_usage>40[threshold of check, kB/s]</average_usage>

 <history>

 <data>

  <start>2013-09-15 14:00:00[start of interval]</start>

  <end>2013-09-23 10:59:59[end of interval]</end>

  <bandwidth>1250000[maximum bandwidth available]</bandwidth>

  <total_average>0[combined averages of transmit plus receive]</total_average>

  <total_max>0[combined maximums of transmit plus receive]</total_max>

  <transmit_average>0[average transmit throughput]</transmit_average>

  <transmit_max>0[maximum transmit throughput]</transmit_max>

  <receive_average>0[average receive throughput]</receive_average>

  <receive_max>0[maximum receive throughput]</receive_max>

 </data>

 [...more data elements...]

 </history>

</interface>

[...more interface elements...]

</network_usage>

<memory_usage>

<check_id>909090909[id of check]</check_id>

<available_min>10[threshold for minimum available memory, MB]</available_min>

<average_pages>20[threshold for page usage]</average_pages>

<average_page_file>70[threshold for paging file]</average_page_file>

<non_paged_pool>100[threshold for non-paged]</non_paged_pool>

<average_commit>0[threshold for commit charge]</average_commit>

<history>

 <data>

 <start>2013-09-15 17:00:00[start of interval]</start>

 <end>2013-09-15 17:59:59[end of interval]</end>

 <available_average>296.5[average memory available, MB]</available_average>

 <available_min>288.5[minimum memory available, MB]</available_min>

 <commit_charge_average>2894.25[average commit charge, MB]</commit_charge_average>

 <commit_charge_max>2900[maximum commit charge, MB]</commit_charge_max>

 <page_faults_average>13[average page faults]</page_faults_average>

 <page_faults_max>303[maximum page faults]</page_faults_max>

 <file_usage_average>44.25[percentage file usage]</file_usage_average>

 <file_usage_max>45[percentage file usage]</file_usage_max>

 <non_paged>63[usage of non-paged memory]</non_paged>

 <total>2047[total physical memory installed which can be used as main memory, MB]</total>

 </data>

</history>

</memory_usage>

</result>

</example>

Fields Description

Bandwidth Monitoring Check

Can contain multiple entries (in XML output these will be host elements), each containing:

descriptive name of the bandwidth check which populated this data

the hostname or IP address the data is for

the check which populated this data

integer; receive rate threshold (from the check) in kilobytes per second

integer; transmit rate threshold (from the check) in kilobytes per second

a list (in XML output these will be data elements), each entry containing:

Performance Monitoring Check - Physical Disk

Can contain multiple entries (in XML output these will be disk elements), each containing:

id of the disk, followed by a list of drives on that disk

the check which populated this data

integer; current threshold (from the check)

integer; current threshold (from the check)

integer; percentage - current threshold (from the check)

a list, each entry (these will be data elements in XML output) containing:

Performance Monitoring Check - Processor Queue Length

the check which populated this data

integer; current threshold (from the check)

a list, each entry (these will be data elements in XML output) containing:

Performance Monitoring Check - Processor Utilization

the check which populated this data

integer; current threshold (from the check)

a list, each entry (these will be data elements in XML output) containing:

Performance Monitoring Check - Network Interface Utilization

Can contain multiple entries (in XML output these will be interface elements), each containing:

name of the network adapter

the check which populated this data

integer; percentage threshold (from the check)

a list (these will be data elements in XML output), each entry containing:

Performance Monitoring Check - Memory Usage

the check which populated this data

integer; threshold (from the check)

integer; threshold (from the check)

integer; threshold (from the check)

integer; threshold (from the check)

integer; threshold (from the check)

a list (these will be data elements in XML output), each entry containing:

Notes

If the data remains identical for multiple consecutive intervals then it will be returned as one long interval, thus the specified interval is the minimum interval length which will be returned.

Any intervals for which the values are unknown are not included in the output. The ordering of data is not guaranteed; ensure you use the start and end fields when reading the data.

All times are UTC. The interval start and end times are not exact due to the various times at which the agent runs the checks and plus the variable durations for reporting and processing such data.

The newest data available will be the last full interval reported which for servers will be recorded during the next interval but for workstations could be sometime later depending on the frequency at which checks are run.

Hourly data is an average of the four 15 minute intervals with which it aligns. The maximums reported are actually averages over the smallest timeframe the agent can obtain data for.

Data intervals are returned with times marking the first second and last second of the interval; note that no performance data has to-the-second precision.

Thresholds reported alongside the history are the current parameters for the relevant check; previous threshold values are not available even though it's possible they have changed during the reported time frame.

Hardware changes could cause significant changes to the data returned, including the number of CPUs listed which is recorded on a per-interval basis.

If the device has multiple checks of same type configured, then you'll see the thresholds and check_id for the one which most recently reported a result; data for the others will be identical, but there could be additional thresholds being monitored; obtain the list of checks from list_checks if such information is needed.

https://SERVER/api/?apikey=yourAPIkey&service=list_devices_at_client&clientid=CLIENTID&devicetype=server

https://SERVER/api/?apikey=yourAPIkey&service=list_servers&siteid=SITEID

https://SERVER/api/?apikey=yourAPIkey&service=list_workstations&siteid=SITEID