Managing and Monitoring over REST
Apama provides a Representational State Transfer (REST) HTTP API with which you can monitor Apama components. The monitoring capabilities are available to third-party managing and monitoring tools or to any application that supports sending and receiving XML documents, or receiving JSON documents, over the HTTP protocol.
Apama components expose several URIs which can be used to either monitor or manage different parts of the system. Some are exposed by most Apama components. These are the generic management URIs. Some are exposed only by specific types of components. For example, a correlator running on the default port of 15903 will expose a URI at http://localhost:15903/correlator/status. If an HTTP GET is issued against the URI, the correlator will return a document with the current status of the correlator. The format of this document is depicted by the header set in the request, that is, application/xml for XML and application/json for JSON.
Most URIs are purely for informational purposes and will only respond to HTTP GET requests, and interacting with them will not change the state of the component. However, some URIs allow the state of the correlator to be modified. This is currently supported for XML only. They will respond to one or more of the other HTTP methods. For example, the /logLevel URI will accept an HTTP PUT request containing an XML document describing what the log level of the component should be set to. Note that in this case, it will also accept a GET request which will report the current log level of the component, in keeping with REST principles.
All requests and responses over these interfaces have the same, simple elements:
In XML, these elements are:
prop
map
list
All elements have a name attribute. The prop element simply represents a name-value pair with the name contained in the name attribute and the value being the content of the element. The map element is an unordered list of named elements which might be any of the three sets of elements, though it is quite typically simply a map of prop elements. See the /info URI as an example. The list is very similar to the map element except that here the order is typically regarded as significant. All responses from these URIs have a top-level element with the name apama-response and similar all requests which are sent to these URIs should have a top-level element with the name apama-request. If there is an error, then a response called apama-exception will be returned.
In JSON, these elements are:
map {}
list []
All elements have a name-value pair. Name and value are separated by a colon (:) with the name to the left and the value to the right of the colon. The map element, which is represented by curly brackets, is an unordered list of named elements which might be any of map or list elements. See the /info URI as an example. The list element, which is represented by square brackets, is very similar to the map element except that here the order is typically regarded as significant. If there is an error, then a response with the error message is returned, for example, {"apamaErrorMessage":"Not found"}.
For both formats, the /connections URL is a good example of all these elements being used together:
In XML, the top-level element is a
map which has two children, both
list elements, called
senders and
receivers. Each list contains a
map element for each sender and receiver. Each sender or receiver has a set of
prop elements.
In JSON, the top-level element is a
map {} which has two children, both
list [] elements, called
senders and
receivers. Each list contains a
map {} element for each sender and receiver. Each sender or receiver has a set of name-value pairs.
Method | URI | Supported Format | Description |
GET | /info | XML, JSON | Summary information about the component including its name, version, etc. |
GET | /ping | XML | Check if the component is running. |
GET | /deepPing | XML | Check if the component is running. |
GET | /logLevel | XML, JSON | Display the current log level of the component. |
PUT | /logLevel | XML | Issues a request to change the log level of the component. Not supported for dashboard servers. |
GET | /connections | XML, JSON | Display the connections to the component. For dashboard servers, this is always empty. |
GET | /info/argv | XML | Display the arguments that were specified when the component was started. |
GET | /info/envp | XML | Display the names and values of the environment variables in use. |
GET | /info/sysprop | XML, JSON | Dashboard servers only. Display the names and values of the Java system properties of the component. |
GET | /info/categories | XML | Display the categories available; for example argv and envp. |
GET | /correlator/status | XML, JSON | Display the runtime status of a running correlator and the user-defined status values. |
GET | /correlator/info | XML, JSON | Display information about the state of a running event correlator. |
GET | /correlator/types | XML, JSON | Display all the types currently known to the correlator. |
GET | /correlator/appLogging | XML, JSON | Display information around the application logging at different levels. |
GET | /iaf/status | XML, JSON | Summary information about the IAF component. |
Two examples are provided below, one for JSON and another for XML. Each example shows only a possible hierarchy of a response. To get the actual format of the response for each request, it is recommended that you actually make the request.
Example for JSON:
{
"Key1": [
{"Key1.1.1":"Value1.1.1","Key1.1.2":"Value1.1.2"},
{"Key1.2.1":"Value1.2.1","Key1.2.2":"Value1.2.2"}
],
"Key2":[],
"Key3":
[
{"Key3.1.1":"Value3.1.1","Key3.1.2":[]}
],
"Key4":[]
}
Example for XML:
