Add files via upload

Author: Helene

CHANGELOG.md

@@ -1,3 +1,72 @@
+# Version 5 (12/01/2019)
+
+Moved the source code & documentation to the IBM GITHUB
+
+Source code refactoring(bridge internal optimization)
+- metadata retrieval optimizations (time performance)
+
+
+
+# Version 4 (04/08/2019)
+
+Added aggregation support to query interval 
+- set the query interval automatically to the metric data polling interval if the downsampling is disabled explicitly
+- allow usage of AVG, MIN, MAX, SUM aggregators for the downsampled polling intervals
+
+Changed the logic for checking the metric sensor configuration data.
+- Reason: GPFSFSInodeCap and GPFSPoolCap are virtual sensors. The config settings for this sensors need to be derived from the sensor GPFSDiskCap.
+
+
+
+# Version 3 (08/06/2018)
+
+Added python3.6 support 
+
+Source code changes based on [openTSDB datasource](https://github.com/grafana/grafana/tree/master/public/app/plugins/datasource/opentsdb) plugin supported by Grafana
+- Query requests and results in [openTSDB API 2.3 supported format](http://opentsdb.net/docs/build/html/api_http/query/index.html)
+- Fixed [alias tag issue](https://github.com/grafana/grafana/issues/7560)
+
+Source code changes based on latest configuration updates to IBM Spectrum Scale performance monitoring tool (ZIMon):
+- changed '-s --server' option from required to optional. If not specified the server will be automatically set to 'localhost'.
+>> **NOTE**: Since Spectrum Scale version 5.0.0 the ZImon pmcollector allows query requests, per default, only from local host.
+- added vlaidity check for '-P --serverPort'
+- added configuration check for multithreaded serverPort. If configured, this will be automatically used for querying pmcollector.
+
+Source code refactoring(bridge internal optimization)
+- refactoring of GET, POST Handler result objects (bridge internal)
+- metadata retrieval optimizations (time performance)
+
+Improved logging, more options for troubleshooting
+- improved trace messages for logging connection issues
+- improved trace messages for logging wrong input parameters f.e. tag names, tag values
+
+
+
+# Version 2 (05/24/2017)
+
+Added HTTPS(SSL) connection support(via port 8443)
+- required [CherryPy version 4.0](download from: https://pypi.python.org/pypi/CherryPy/4.0.0) or higher 
+- required [SSL private key and certificate](http://cherrypy.readthedocs.io/en/latest/deploy.html#ssl-support) to be generated
+- start the bridge with '-k' option (followed by the SSLkey location path) and port 8443 (-p option)
+
+Source code changes based on [openTSDB datasource](https://github.com/grafana/grafana/tree/master/public/app/plugins/datasource/opentsdb) plugin supported by Grafana
+- allowing the multiple filters usage in the [lookup](http://opentsdb.net/docs/build/html/api_http/search/lookup.html?) queries
+- Query requests and results in [openTSDB API 2.3 query format](http://opentsdb.net/docs/build/html/api_http/query/index.html)
+
+Improved logging, more options for troubleshooting 
+- added python version, cherryPy version and the list of enabled sensors to the console message during the bridge start
+- added trace messages for logging received requests from Grafana and processed queries stored in zserver.log(INFO-level)
+- added trace messages for logging process details at different places (DEBUG-level)
+- added HTTPError codes to the error trace messages(if the error cause is known)
+- cherrypy_access.log enabled (automatically created with the bridge start)
+- cherrypy_error.log (automatically created with the bridge start)
+
+Source code refactoring(bridge internal optimization)
+- moved to the new QueryHandler(backend query engine)
+- metadata retrieval simplification (all methods quering metadata moved to the separate module)
+
+
+
 # Version 1 (06/16/2016)
 
 Initial version

README.md

@@ -1,6 +1,6 @@
 The ***IBM Spectrum Scale bridge for Grafana*** could be used for exploring IBM Spectrum Scale performance data on [Grafana dashboards](https://grafana.com/grafana/).
 
-Grafana Bridge is a standalone Python application. It translates the IBM Spectrum Scale metadata and performance data collected by the [IBM Spectrum Scale performance monitoring tool (ZiMon)](https://www.ibm.com/support/knowledgecenter/en/STXKQY_4.2.0/com.ibm.spectrum.scale.v4r2.adv.doc/bl1adv_PMToverview.htm) to the query requests acceptable by the [Grafana integrated openTSDB plugin](https://grafana.com/docs/features/datasources/opentsdb/).
+Grafana Bridge is a standalone Python application. It translates the IBM Spectrum Scale metadata and performance data collected by the [IBM Spectrum Scale performance monitoring tool (ZiMon)](https://www.ibm.com/support/knowledgecenter/en/STXKQY_4.2.3/com.ibm.spectrum.scale.v4r23.doc/bl1adv_PMToverview.htm) to the query requests acceptable by the [Grafana integrated openTSDB plugin](https://grafana.com/docs/features/datasources/opentsdb/).
 
 
 
@@ -9,16 +9,18 @@ Grafana Bridge is a standalone Python application. It translates the IBM Spectru
 ### Prerequisites
 
 Before installing the IBM Spectrum Scale bridge for Grafana you must install the software prerequisites. Those are:
-1. [Performance Monitoring tool](https://www.ibm.com/support/knowledgecenter/en/STXKQY_4.2.0/com.ibm.spectrum.scale.v4r2.adv.doc/bl1adv_PMToverview.htm) installed and configured on your IBM Spectrum Scale device
-2. On the [collector node](https://www.ibm.com/support/knowledgecenter/en/STXKQY_4.2.0/com.ibm.spectrum.scale.v4r2.adv.doc/bl1adv_PMToverview.htm) the following software need to be installed:
-- [Python2.7](https://www.python.org/downloads/release/python-2717/)
+1. [Performance Monitoring tool](https://www.ibm.com/support/knowledgecenter/en/STXKQY_4.2.3/com.ibm.spectrum.scale.v4r23.doc/bl1adv_PMToverview.htm) installed and configured on your IBM Spectrum Scale device
+2. On the [collector node](https://www.ibm.com/support/knowledgecenter/en/STXKQY_5.0.4/com.ibm.spectrum.scale.v5r04.doc/bl1adv_configurecollector.htm) the following software need to be installed:
+- [Python2.7](https://www.python.org/downloads/release/python-2717/)/ [Python3.6](https://www.python.org/downloads/release/python-369/)
 - [CerryPy](https://cherrypy.org/)
 
 
 ### Dependencies
 This package could be used for: 
-- IBM Spectrum Scale devices having mimimum release level 4.2.1 and above
-- Grafana 3.0.4 and above
+- IBM Spectrum Scale devices having mimimum release level 5.0.3 FP2 and above
+- Grafana 6.0.0 and above
+
+To use this tool on the older IBM Spectrum Scale devices please refer to the [SUPPORT_MATRIX](SUPPORT_MATRIX.md) file.
 
 
 
@@ -37,13 +39,13 @@ In a multi-collector environment, there is no need to run the bridge on each pmc
 #### Step 2. Verify Python and CherryPy
 
 Ensure that Python and CherryPy have been installed on the IBM Spectrum Scale system. 
-Check the [SUPPORT_MATRIX](SUPPORT_MATRIX.md) file for the recommended version.
+Check the SUPPORT_MATRIX file for the recommended version.
 
 
 
 #### Step 3. Set up IBM Spectrum Scale Performance Monitoring Bridge
 
-Download the zip package and unpack it in your favorite directory:
+Download the zip package and unpack it in your favorite directory on the collector node :
 
 ```shell
 # unzip zimonGrafanaIntf.zip
@@ -52,7 +54,7 @@ Download the zip package and unpack it in your favorite directory:
 Start the bridge application by issuing:
 
 ```shell
-# python zimonGrafanaIntf.py -s <pmcollector host>
+# python zimonGrafanaIntf.py 
 ```
 
 If the bridge did establish the connection to the specified pmcollector and the initialization of the metadata was performed successfully, you should get the message "server started" at the end of line. Otherwise check the zserver.log stored in the zimonGrafanaIntf  directory.  Additionally, check the pmcollector service running properly by issuing:
@@ -73,9 +75,9 @@ Download and install [Grafana](https://grafana.com/get) according to the given i
 
 Define a new data source (Data Sources -> Add New)
 
-![](Add_DataSource.png)
+![](Example_Add_DataSource.png)
 
-**NOTE**: The IBM Spectrum Scale bridge listens on port 4242
+**NOTE**: The IBM Spectrum Scale bridge listens on port 4242 for HTTP connections, and on port 8443 for HTTPS connections
 
 Grafana now can talk to Spectrum Scale Performance Monitoring tool via the bridge. Follow the grafana instructions to create dashboards.
 

SUPPORT_MATRIX.md

@@ -1,5 +1,29 @@
 The following matrix gives a quick overview of the supported software for the IBM Spectrum Scale bridge for Grafana packages by version number:
 
+# Version 5 (12/01/2019)
+- Python 2.7 or Python 3.6
+- CherryPy 8.0.0 and above (For HTTPS connection required CherryPy 8.0.0/Python 2.7 or CherryPy 18.0.0/Python3.6)
+- IBM Spectrum Scale system must run 5.0.3 FP2 and above
+- Grafana 6.0.0 and above
+
+# Version 4 (04/08/2019)
+- Python 2.7 or Python 3.6
+- CherryPy 8.0.0 and above (For HTTPS connection required CherryPy 8.0.0/Python 2.7 or CherryPy 18.0.0/Python3.6)
+- IBM Spectrum Scale system must run 4.2.3. FP14 and above
+- Grafana 6.0.0 and above
+
+# Version 3 (08/06/2018)
+- Python 2.7 or Python 3.6
+- CherryPy 4.0.0 and above (For HTTPS connection required CherryPy 4.0.0/Python 2.7 or CherryPy 14.0.1/Python3.6)
+- IBM Spectrum Scale system must run 4.2.3. FP8 and above
+- Grafana 5.0.0 and above
+
+# Version 2 (05/24/2017)
+- Python 2.7 or Python 3.4
+- CherryPy 3.6.0 (For HTTPS connection required CherryPy 4.0.0/Python 2.7 or CherryPy 8.2.0/Python3.4.3)
+- IBM Spectrum Scale system must run 4.2.1. or above (Note: For the optimal bridge performance we recommend to use the IBM Spectrum Scale release level 4.2.3 FP1)
+- Grafana 4.2.0
+
 # Version 1 (06/16/2016)
 - Python 2.7
 - CherryPy 3.6.0