THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Introduction
There are many manageability points of contact in the Trafodion eco-system e.g., DTMCI, SQLCI, the "sqstatus", "sqps" & "ckillall" scripts, to name just a few. Moreover, there's no single connection point that a manageability client can contact to retrieve the information provided from components. This presents a unique challenge for manageability command & control clients. The Trafodion DCS component currently has a REST server that may be used as the Trafodion "core" REST server. A single days effort was needed to strip out the main DcsMaster and DcsServer code leaving a compact set of source code that was inserted into the GIT Trafodion "core" project as a new "rest" directory. This code is built with Maven.
Purpose
The server will provide a "one stop shop" for all things Trafodion. While the client uses well known REST with well defined operations the back end of the REST server can issue SQL queries to retrieve information from RMS. Workload and repository information may also be retrieved using either JDBC Type2 or Type 4 connector. DTM transaction visibility will be available as the server can "talk" to DTMCI. DCS server and client connection status may be collected using T2 or T4 connectors. Zookeeper information is available through a Zookeeper client connector. The data returned may be in JSON, plain text or XML and is dependent on what the HTTP client requests.
Usage Scenarios
Any on/off platform client that has the capability to perform REST operations can interoperate with the server. Users may write custom manageability applications supported by industry standard, open source REST mechanism.
For a comprehensive introduction to REST please see the following tutorial: REST Tutorial
External Functionality
This section covers the REST API.
New Syntax
Client will use RESTful commands to retrieve information from REST server. Please see the examples below.
Considerations
Like DCS the REST server will be installed/configured by the Trafodion installer into the "local_hadoop" directory. The start-rest.sh and stop-rest.sh scripts found in the /bin directory may be invoked to start/stop the server.
Security will be SSL.
Examples
The following examples using the "curl" tool illustrate a typical Trafodion REST server client request:
Core “sqcheck”:
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/dtm curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/rms curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/dcs
DCS Connections info from Zookeeper:
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/connections
Core “sqnodestatus”:
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/nodes
Core “cancel query <query id>”:
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/workload/cancel/<query id>
Core “sqpstack [program]”:
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/pstack curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/servers/pstack/program/<program>
DTMCI status tm
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/transactions/tm
DTMCI stats
curl -v -X GET -H "Accept: application/json" http://<Rest server IP address>:4200/v1/transactions/stats
Default Settings
Like HBase & DCS the rest server uses the Apache Hadoop configuration mechanism. Basically, a set of user properties is defined in rest-default.xml which is included in the rest-x.x.x-tar.gz file. The user may override any property by adding it to the conf/rest-site.xml file and changing the <value> tag. The configuration mechanism merges this set of files so the server can retrieve any overridden properties.
Configuration File Changes
The server is standalone with its own configuration therefore it has no impact on Trafodion core configuration.
New Error Messages
Like DCS and HBase error messages generated by the server are logged using standard log4j to the files configured in conf/log4j.properties
Architecture
The following is a block diagram of the capabilities inherited from the DCS server.
Internal Design
The server is a multi-threaded 100% Java implementation. In a nutshell, Http clients connect to the embedded Jetty server which is listening on port 4200. Depending on the REST request the server may invoke one or more connectors to retrieve the needed information from SQL engine, DTM, or Zookeeper.
Using the Java Scripting Engine, (JSR 223), see tutorial here: Scripting for the Java platform, it can invoke Python scripts that execute bash commands e.g., to retrieve/massage the output from e.g., an "sqstatus" command. The same Python scripts have the full capabilities of Java available to them as well.
The server is returned the output of the Python script and returns it back to the client in JSON format.
All Python scripts are compiled by the Java Scripting engine. Moreover the server can detect when the script changes and will re-compile the script.
Performance
REST server executes existing Trafodion scripts on platform. It should not affect performance of core Trafodion engine.
Usability
REST is well known and provides an excellent API for internal/external clients.
Availability
There is only a single instance of the server. It must be restarted if it fails. It's possible init.d could be used to detect failure and restart the server automatically.
Manageability
The server doesn't provide a manageability interface.
Scalability
The embedded Jetty server is multi-threaded. Min/Max threads is configurable via conf/rest-site.xml properties.
Dependencies
The REST server is dependent on the existing scripts and tools available in Trafodion.
Testing
Tests will be provided in the source tree. These can be invoked by running Maven after Trafodion is started.