List Performance History: list_performance_history

Service name: list_performance_history

URL

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

&required_parameters=required_parameters

[&optional_parameters=optional_parameters]

Description

Obtains the data relating to all the Server 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.

Parameters

Post Variable

Description

Type

Required

Options

Default

describe

Optional. Returns a description of the service.

boolean

no

true

0

deviceid

The deviceid must be a valid id.

integer

yes

0

0

interval

Interval duration in minutes:

15 (available for up to 24 hours)

60 (available for up to 8 days)

integer

yes

15

60

0

since

If specified only intervals starting at or after this time will be included. UTC, ISO-8601, e.g. 2013-10-21 11:22:33

string

no

0

0

Example Service Call =list_performance_history

https://SERVER/api/?apikey=yourAPItoken&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:

name

descriptive name of the bandwidth check which populated this data

host

the hostname or IP address the data is for

check_id

the check which populated this data

receive

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

transmit

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

history

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

start

first second of the period for which this data applies; UTC, ISO-8601

end

last second of the period for which this data applies; UTC, ISO-8601

receive

float/decimal; average transmission rate (kilobytes per second)

transmit

float/decimal; average transmission rate (kilobytes per second)

 

Performance Monitoring Check - Physical Disk

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

disk

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

check_id

the check which populated this data

read_queue_length

integer; current threshold (from the check)

write_queue_length

integer; current threshold (from the check)

average_disk_time

integer; percentage - current threshold (from the check)

history

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

start

first second of the period for which this data applies; UTC, ISO-8601

end

last second of the period for which this data applies; UTC, ISO-8601

disk_time_average

float/decimal; average disk time (percentage) for the period

disk_time_max

float/decimal; maximum disk time (percentage) for the period

read_queue_average

float/decimal; average read queue length for the period

read_queue_max

float/decimal; maximum read queue length for the period

write_queue_average

float/decimal; average write queue length for the period

write_queue_max

float/decimal; maximum write queue length for the period

 

Performance Monitoring Check - Processor Queue Length

check_id

the check which populated this data

average_length

integer; current threshold (from the check)

history

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

start

first second of the period for which this data applies; UTC, ISO-8601

end

last second of the period for which this data applies; UTC, ISO-8601

average

float/decimal; average queue length for the period

max

float/decimal; maximum queue length for the period

Performance Monitoring Check - Processor Utilization

check_id

the check which populated this data

average_load

integer; current threshold (from the check)

history

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

start

first second of the period for which this data applies; UTC, ISO-8601

end

last second of the period for which this data applies; UTC, ISO-8601

JSON List:

XML: cpu elements

1..4 entries; just an average and maximum if 1 CPU or more than 4 CPUs; separately listed if 2..4 CPUs

cpu_id

integer; 1..4

load_average

float/decimal; average load for the period

load_max

float/decimal; maximum load for the period

Performance Monitoring Check - Network Interface Utilization

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

adapter

name of the network adapter

check_id

the check which populated this data

average_usage

integer; percentage threshold (from the check)

history

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

start

first second of the period for which this data applies; UTC, ISO-8601

end

last second of the period for which this data applies; UTC, ISO-8601

bandwidth

integer; maximum bandwidth for this network interface (kilobytes per second)

total_average

float/decimal; average transmission rate (kilobytes per second)

total_max

float/decimal; maximum transmission rate (kilobytes per second)

transmit_average

float/decimal; average transmission rate (kilobytes per second)

transmit_max

float/decimal; maximum transmission rate (kilobytes per second)

receive_average

float/decimal; average transmission rate (kilobytes per second)

receive_max

float/decimal; maximum transmission rate (kilobytes per second)

Performance Monitoring Check - Memory Usage

check_id

the check which populated this data

available_min

integer; threshold (from the check)

average_pages

integer; threshold (from the check)

average_page_file

integer; threshold (from the check)

non_paged_pool

integer; threshold (from the check)

average_commit

integer; threshold (from the check)

history

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

start

first second of the period for which this data applies; UTC, ISO-8601

end

last second of the period for which this data applies; UTC, ISO-8601

available_average

float/decimal; average available memory during the period (megabytes)

available_min

float/decimal; minimum available memory during the period (megabytes)

commit_charge_average

float/decimal; average commit charge during the period (megabytes)

commit_charge_max

float/decimal; maximum commit charge during the period (megabytes)

page_faults_average

float/decimal; average page faults per second over the period

page_faults_max

float/decimal; maximum page faults per second over the period

file_usage_average

float/decimal; average file usage over the period

file_usage_max

float/decimal; maximum file usage during the period

non_paged

float/decimal; amount of non paged memory during the period

total

integer; total installed physical memory (megabytes)

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.

Example Associated Service Calls
Parameter Call URL Format
DeviceID list_devices_at_client

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

list_servers

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

list_workstations

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

SiteID list_sites https://SERVER/api/?apikey=yourAPItoken&service=list_sites&clientid=CLIENTID
ClientID list_clients https://SERVER/api/?apikey=yourAPItoken&service=list_clients