July 25, 2016 | Written by: Alexander Pogue
Categorized: Data Analytics | How-tos
Share this post:
Do you want to gain a deeper understanding of your Streams apps running either on-premises or in the Streaming Analytics Bluemix service? The Streams web console enables interactive Streams monitoring. However, the Streams REST API provides powerful programmatic access to detailed metrics for Streams instances, jobs, PEs, and more. The REST API is available wherever you can access the Streams web console.
Note that the Streams REST API deals with the underlying Streams infrastructure and is different than the Streaming Analytics REST API. To learn about Streaming Analytics REST API instead, see Streaming Analytics service instance REST API reference.
This is an introduction to the Streams REST API for both Streams on-premise and Streaming Analytics in the cloud.
You need either a Streams installation or Streaming Analytics Bluemix service to follow along:
Getting the Streams instances REST URI
We start with the instances REST call and dig into other REST calls from there. We derive the URI from the Streams web console URI.
Open the Streams console:
- With on-premise Streams, click the Streams Console icon usually found on the Desktop of an application host.
- With Streams in the cloud, navigate to your Streaming Analytics service in the Bluemix dashboard and click Launch.
The browser window navigates to a URI similar to
[host] part might include a port number, and the
[#anchor] part might or might not be present. Regardless, change this URI to
Open the base URI in a browser and authenticate:
- For on-premise Streams, enter your Streams username and password. The default for Quick Start Edition is `streamsadmin` / `passw0rd`.
- For Streaming Analytics, get the username and password from the service credentials tab of the Streaming Analytics dashboard.
Exploring the Streams REST API
Tip: To format the JSON nicely, find and install a JSON formatter browser extension.
API call to /streams/rest/instances
minimumOSVersion: "Red Hat Enterprise Linux Server release 6.1 (Santiago)",
editionName: "IBM InfoSphere Streams",
productName: "IBM InfoSphere Streams",
Jobs information using the Streams REST API
To get information about jobs in an instance, simply navigate to the URI given under the jobs key in the instances JSON. In the above JSON, that is https://streams-console-c6d1.ng.bluemix.net/streams/rest/instances/955d9eef-024d-4843-8741-cd1627a71cec/jobs. Note that if no jobs are currently running, the API call result will have total: 0 and no job details will be shown. In this case, you can submit a job from the StreamsSPLSamples repository.
API call to /streams/rest/instances/<instanceid>/jobs
This JSON provides details such as the job name, status, health, and more. It also gives URIs we can use to dig in even further. We’ll follow one of these URIs to see the job’s PE information.
PE information using the Streams REST API
Pick one of the jobs from the jobs JSON array and navigate to its pes URI.
API call to /streams/rest/instances/<instanceid>/pes?job.restid=<jobid>
domain: "https://streams-console-c6d1.ng.bl you want to gain a deeper understanding of your Streams apps running either on-premises or in the Streaming Analytics Bluemix service? Whereas the Streams wuemix.net/streams/rest/domains/standard1",
This gives details about the PEs in a particular job.
We have just scratched the surface of the Streams REST API. Dig into the other URIs inside the JSON to get even more details. It is also easy to access REST APIs programmatically, even from Streams itself. With programmatic access, you can proactively monitor your Streams instance, build your own custom dashboard, or store the instance state for later analysis.
- Programmatically monitoring the REST API allows you to quickly diagnose and resolve Streams state anomalies. It also provides reassurance when everything is working correctly.
- To easily access metrics not provided by the Streams web console, you can make a custom dashboard view from the Streams REST API metrics.
- Persisting snapshots of the Streams REST API over time provides historical insight that you can use to pinpoint unexpected Streams state changes.
- Using the REST API, you can now monitor your Streams instances both on-premise and in the cloud using the same REST interface.