pmonframe XML Network Interface

Abstract First Steps XML Network Interface Java Doc Real World Example FAQ Download Contact

XML Network Interface

The XML network interface of a pmonframe server supports ten different commands for retrieving metadata and measured values; however, the following commands are the only ones needed in most cases:

The command getDataCollectionDirectory returns information about all data collections which are provided by a pmonframe server. This also includes instructions to the client about how to draw and label the charts.
One of the commands getValues, getLatestValuesSinceSeconds or getLatestValuesSinceTimestamp, which cause the measured values of one data collection to be transmitted from the server to the client.

In addition, to ensure that the measurements received at the client side are always accurate, it is recommended that you also use the two following commands, taking into consideration the usage hints and notes related to them:

getOperable
getOsTimestamp

Several commands can be placed inside the same XML request in order to optimize the number of requests which are made to a pmonframe server. Example:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command>getOsTimestamp</command>
  <command identifier="CPU" seconds="300">getLatestValuesSinceSeconds</command>
  <command identifier="MEMORY" seconds="300">getLatestValuesSinceSeconds</command>
  <command identifier="TCP-EST" seconds="300">getLatestValuesSinceSeconds</command>
  <command identifier="TCP-TIMEWAIT" seconds="300">getLatestValuesSinceSeconds</command>
</clientRequest>

Command #1: getServerInfo

Description: Get common information about the pmonframe server which (optionally) can be displayed to an end-user.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command>getServerInfo</command>
</clientRequest>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <serverInfo>
    <abbreviation>EXSRV</abbreviation>
    <description></description>
  </serverInfo>
</serverResponse>

abbreviation: The abbreviation of the pmonframe server
description: A description about what the pmonframe server measures

Command #2: getOperable

Description: Normally a pmonframe server is always operable; however, if a pmonframe server detects a severe and/or permanent internal error, it may change its state to inoperable. Background: if no new measured values are collected for a period of time, this allows you to distinguish between the situation where there are no new measured values, and where the server has stopped collection due to an internal error.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command>getOperable</command>
</clientRequest>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <operable>true</operable>
</serverResponse>

operable: true or false. True = the pmonframe server is operable (currently in measuring state)

Command #3: getOsTimestamp

Description: Get a timestamp about the current date and time of the pmonframe server. Background: a pmonframe client can compare a locally-taken (actual) timestamp with the timestamp of the pmonframe server in order to detect if the current date and time of the pmonframe server operating system is not correctly adjusted. In such a case the client may calculate the time difference and use this time difference to correct the timestamps of the received measuring data.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command>getOsTimestamp</command>
</clientRequest>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <osTimestamp>1264108031953</osTimestamp>
</serverResponse>

osTimestamp: Timestamp of the current date and time of the pmonframe server (milliseconds elapsed since January 1, 1970)

Command #4: getDataCollectionDirectory

Description: Get information (metadata) about all data collections which are provided by a pmonframe server. Note: this command allows the implementation of generic client programs which do not need to know in advance anything about how to process and display the measured data.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command>getDataCollectionDirectory</command>
</clientRequest>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <dataCollectionDirectory>
    <measurementCollectionMetadata>
      <identifier>CPU</identifier>
      <title>CPU</title>
      <subtitle></subtitle>
      <yAxisLabel>Percent</yAxisLabel>
      <dataType>percent</dataType>
      <maxCapacity>1000</maxCapacity>
    </measurementCollectionMetadata>
    <measurementCollectionMetadata>
      <identifier>DISKIO</identifier>
      <title>DISK I/O</title>
      <subtitle>Local I/O without SAN</subtitle>
      <yAxisLabel>I/O per Second</yAxisLabel>
      <dataType>integer</dataType>
      <maxCapacity>1000</maxCapacity>
    </measurementCollectionMetadata>
  </dataCollectionDirectory>
</serverResponse>

dataCollectionDirectory: List of all measurement collections for which values are measured by the pmonframe server.
measurementCollectionMetadata: Contains the definition (metadata) of a measurement collection.
identifier: Unique identifier of the measurement collection. Note: the identifier is only unique per pmonframe server. Several pmonframe servers may use identical identifiers.
title: Title of the measurement collection.
subtitle: Subtitle of the measurement collection, or an empty string if no subtitle is available.
yAxisLabel: The label of the y-axis.
dataType: The data type of the measurement collection. Possible return values are "float" or "double" or "percent" or "integer" or "long" or "XMLtext".
maxCapacity: Maximum capacity of measured values, stored at the server side inside this measurement collection. If the maximum capacity of values is reached on the server, older values are deleted when new values are added.

Command #5: getDataCollectionEntry

Description: Get information (metadata) about a particular data collection provided by a pmonframe server. This command is similar to command #4 but requires that the pmonframe client knows in advance the identifier of the measurement collection.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command identifier="CPU">getDataCollectionEntry</command>
</clientRequest>

identifier: Unique identifier of the measurement collection.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <measurementCollectionMetadata>
    <identifier>CPU</identifier>
    <title>CPU</title>
    <subtitle></subtitle>
    <yAxisLabel>Percent</yAxisLabel>
    <dataType>percent</dataType>
    <maxCapacity>1000</maxCapacity>
  </measurementCollectionMetadata>
</serverResponse>

This data structure is almost identical to the data structure returned by command #4. You can directly request the definition (metadata) of a measurement collection if you know the identifier in advance.

Command #6: getValues

Description: Get all measured values of a particular data collection from a pmonframe server. Note: The maximum number of received values is limited by the capacity of the short time data cache which is defined on the pmonframe server.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command identifier="CPU">getValues</command>
</clientRequest>

identifier: Unique identifier of the measurement collection.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <measurementCollection identifier="CPU" dataType="percent">
    <value timestamp="1264111869140">30.14848</value>
    <value timestamp="1264111871140">25.11351</value>
    <value timestamp="1264111873140">99.38088</value>
    <value timestamp="1264111875140">26.993587</value>
    <value timestamp="1264111877140">26.24304</value>
    <value timestamp="1264111879140">20.346375</value>
  </measurementCollection>
</serverResponse>

identifier: Unique identifier of the measurement collection.
dataType: The data type of the measurement collection. Possible return values are "float" or "double" or "percent" or "integer" or "long" or "XMLtext".
timestamp: Timestamp of the current date and time when the value was measured on the pmonframe server (milliseconds elapsed since January 1, 1970).
value: The value of the measured data.

The values are sorted by time (older values first).

Command #7: getLatestValue

Description: Get the latest (newest) measured value of a particular data collection from a pmonframe server. Note: only one value is returned.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command identifier="CPU">getLatestValue</command>
</clientRequest>

identifier: Unique identifier of the measurement collection.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <measurementCollection identifier="CPU" dataType="percent">
    <value timestamp="1264112499140">15.088451</value>
  </measurementCollection>
</serverResponse>

The data structures is identical to the data structure returned by command #6.
This command returns only the latest measured value (only one value).

Command #8: getLatestValuesSinceSeconds

Description: Get all measured values of a particular data collection from a pmonframe server, collected by the server since the number of specified seconds (counted from the current time on the pmonframe server back to the past). Note: The maximum number of received values may be limited by the capacity of the short time data cache which is defined on the pmonframe server.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command identifier="CPU" seconds="300">getLatestValuesSinceSeconds</command>
</clientRequest>

identifier: Unique identifier of the measurement collection.
seconds: select only (new) values which are measured since the specified number of seconds in the past.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <measurementCollection identifier="CPU" dataType="percent">
    <value timestamp="1264112499140">15.088451</value>
    <value timestamp="1264112501140">37.670822</value>
    <value timestamp="1264112503140">23.983019</value>
    <value timestamp="1264112505140">33.161015</value>
    <value timestamp="1264112507140">52.53739</value>
  </measurementCollection>
</serverResponse>

The data structure is identical to the data structure returned by command #6.
The values are sorted by time (older values first).

Command #9: getLatestValuesSinceTimestamp

Description: Get all measured values of a particular data collection from a pmonframe server which are newer than the specified timestamp. Notes: A client can use the last timestamp of already received values to query for new values only; that is, values collected on the pmonframe server since the time of the last transmitted data received. The maximum number of received values may be limited by the capacity of the short time data cache which is defined on the pmonframe server.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command identifier="CPU" timestamp="1264113995140">getLatestValuesSinceTimestamp</command>
</clientRequest>

identifier: Unique identifier of the measurement collection.
timestamp: select only (new) values which are measured since the specified timestamp (milliseconds elapsed since January 1, 1970, compared at server side).

Hint: you can pass an already received timestamp of a previous request (the last received timestamp of the corresponding measurement collection) to get only measurement values which are collected by the pmonframe server since the previous request was made.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <measurementCollection identifier="CPU" dataType="percent">
    <value timestamp="1264112499140">15.088451</value>
    <value timestamp="1264112501140">37.670822</value>
    <value timestamp="1264112503140">23.983019</value>
    <value timestamp="1264112505140">33.161015</value>
    <value timestamp="1264112507140">52.53739</value>
  </measurementCollection>
</serverResponse>

This data structure is identical to the data structure returned by command #6.
The values are sorted by time (older values first).

Command #10: getPmonframedirectory

Description: Get a list of all "normal" pmonframe servers which are known to the directory server.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<clientRequest>
  <command>getPmonframedirectory</command>
</clientRequest>

Special request to a pmonframe directory server which maintain a repository of all known pmonframe servers.

Hint: A read-to-run pmonframe directory server is already available in Java and can be started by calling one of the following classes from a terminal or from a shell script:
org.pmonframe.server.HttpDirectoryServer or alternatively
org.pmonframe.server.TcpDirectoryServer

See also Java Doc of HttpDirectoryServer and TcpDirectoryServer.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<serverResponse>
  <pmonframedirectory>
    <pmonframeserver>
      <host>pmonsrv1.pmonframe.org</host>
      <port>39002</port>
      <protocol>http</protocol>
      <comment>test server 1</comment>
    </pmonframeserver>
    <pmonframeserver>
      <host>192.16.4.78</host>
      <port>39001</port>
      <protocol>tcp</protocol>
      <comment>test server 2</comment>
    </pmonframeserver>
  </pmonframedirectory>
</serverResponse>

pmonframedirectory: List of all known pmonframe servers.
pmonframeserver: Information about one pmonframe server.
host: DNS name or the TCP/IP address of the pmonframe server.
port: the TCP/IP port on which the pmonframe server is listening.
protocol: the network protocol of the pmonframe server. Possible values are "http" or "tcp"
comment: A comment about the pmonframe server, or an empty value if no comment is available

© 2010 pmonframe.org Licensed under the Apache License, Version 2.0
Unless required by applicable law or agreed to in writing, this web page is published on an "as is" basis, without warranties or conditions of any kind, either express or implied.