Configuring the Status Dashboard

The following sections cover the configurations that need to be done in order to view statistics relating to the performance of your WSO2 SP deployment in the status dashboard.

Assigning unique carbon IDs to nodes

Carbon metrics use the carbon ID as the source ID for metrics. Therefore, all the worker nodes are required to have a unique carbon ID defined in the wso2.carbon: section of the <SP_HOME>/conf/worker/deployment.yaml file as shown in the extract below.

wso2.carbon:
    # value to uniquely identify a server
  id: wso2-sp
    # server name
  name: WSO2 Stream Processor
    # ports used by this server

Setting up the database

To monitor statistics in the Status Dashboard, you need a shared metrics database that stores the metrics of all the nodes. 

Set up a database of the required type by following the steps below. In this section, a MySQL database is created as an example.

1. Download and install the required database type. For this example, let's download and install MySQL Server.

2. Download the required database driver. For this example, download the MySQL JDBC driver.

3. Unzip the database driver you downloaded, copy its JAR file (mysql-connector-java-x.x.xx-bin.jar in this example), and place it in the <SP_HOME>/lib directory.

4. Enter the following command in a terminal/command window, where username is the username you want to use to access the databases.
   mysql -u username -p 
5. When prompted, specify the password you are using to access the databases with the username you specified.

6. Create two databases named WSO2_METRICS_DB (to store metrics data) and WSO2_STATUS_DASHBOARD_DB (to store statistics) with tables. To create MySQL databases and tables for this example, run the following commands.

   mysql> create database WSO2_METRICS_DB;
   mysql> use WSO2_METRICS_DB;
   mysql> source <SP_HOME>/wso2/editor/dbscripts/metrics/mysql.sql;
   mysql> grant all on WSO2_METRICS_DB.* TO username@localhost identified by "password";

   mysql> create database WSO2_STATUS_DASHBOARD_DB;
   mysql> use WSO2_STATUS_DASHBOARD_DB;
   mysql> source <SP_HOME>/wso2/editor/dbscripts/metrics/mysql.sql;
   mysql> grant all on WSO2_STATUS_DASHBOARD_DB.* TO username@localhost identified by "password";

7. Create two data sources named  WSO2_METRICS_DB and WSO2_STATUS_DASHBOARD_DB by adding the following data source configurations under the wso2.datasources: section of the <SP_HOME>/conf/worker/deployment.yaml file.

   The names of the data sources must be the same as the names of the database tables you created for metrics and statistics.
   You need to change the values for the username and password parameters to the username and password that you are using to access the MySQL database.

   For detailed information about data sources, see carbon-datasources.

   
   

   • WSO2_METRICS_DB

        - name: WSO2_METRICS_DB
           description: The datasource used for dashboard feature
           jndiConfig:
             name: jdbc/WSO2MetricsDB
           definition:
             type: RDBMS
             configuration:
               jdbcUrl: 'jdbc:mysql://localhost/WSO2_METRICS_DB?useSSL=false'
               username: root
               password: root
               driverClassName: com.mysql.jdbc.Driver
               maxPoolSize: 50
               idleTimeout: 60000
               connectionTestQuery: SELECT 1
               validationTimeout: 30000
               isAutoCommit: false

   • WSO2_STATUS_DASHBOARD_DB


         - name: WSO2_STATUS_DASHBOARD_DB
           description: The datasource used for dashboard feature
           jndiConfig:
             name: jdbc/wso2_status_dashboard
             useJndiReference: true
           definition:
             type: RDBMS
             configuration:
               jdbcUrl: 'jdbc:mysql://localhost/WSO2_STATUS_DASHBOARD_DB?useSSL=false'
               username: root
               password: root
               driverClassName: com.mysql.jdbc.Driver
               maxPoolSize: 50
               idleTimeout: 60000
               connectionTestQuery: SELECT 1
               validationTimeout: 30000
               isAutoCommit: false

     


     The following are sample configurations for database tables when you use other database types supported.
     

      Click here to view the sample datasource configurations

     Database Type	Metrics Datasource	Dashboard Datasource
     MSSQL	name: WSO2_METRICS_DB description: The datasource used for dashboard feature jndiConfig: name: jdbc/WSO2MetricsDB definition: type: RDBMS configuration: jdbcUrl: 'jdbc:sqlserver://localhost;databaseName=wso2_metrics' username: root password: root driverClassName: com.microsoft.sqlserver.jdbc.SQLServerDriver maxPoolSize: 50 idleTimeout: 60000 connectionTestQuery: SELECT 1 validationTimeout: 30000 isAutoCommit: false	name: WSO2_STATUS_DASHBOARD_DB description: The datasource used for dashboard feature jndiConfig: name: jdbc/wso2_status_dashboard useJndiReference: true definition: type: RDBMS configuration: jdbcUrl: 'jdbc:sqlserver://localhost;databaseName=monitoring' username: root password: root driverClassName: com.microsoft.sqlserver.jdbc.SQLServerDriver maxPoolSize: 50 idleTimeout: 60000 connectionTestQuery: SELECT 1 validationTimeout: 30000 isAutoCommit: false
     Oracle	name: WSO2_METRICS_DB description: The datasource used for dashboard feature jndiConfig: name: jdbc/WSO2MetricsDB definition: type: RDBMS configuration: jdbcUrl: 'jdbc:oracle:thin:@localhost:1521/xe' username: root password: root driverClassName: oracle.jdbc.driver.OracleDriver maxPoolSize: 50 idleTimeout: 60000 connectionTestQuery: SELECT 1 validationTimeout: 30000 isAutoCommit: false	name: WSO2_STATUS_DASHBOARD_DB description: The datasource used for dashboard feature jndiConfig: name: jdbc/wso2_status_dashboard useJndiReference: true definition: type: RDBMS configuration: jdbcUrl: 'jdbc:oracle:thin:@localhost:1521/xe' username: root password: root driverClassName: oracle.jdbc.driver.OracleDriver maxPoolSize: 50 idleTimeout: 60000 connectionTestQuery: SELECT 1 validationTimeout: 30000 isAutoCommit: false

Configuring metrics

This section explains how to configure metrics for your status dashboard.

Configuring worker metrics

To enable metrics and to configure metric-related properties, do the following configurations in the < SP_HOME>/conf/worker/deployment.yaml  file for the required nodes.

1. To enable Carbon metrics, set the enabled property to true under wso2.metrics as shown below.

   wso2.metrics:
     enabled: true

2. To enable JDBC reporting, set the Enable JDBC parameter to true in the wso2.metrics.jdbc: => reporting: subsection as shown below. If JDBC reporting is not enabled, only real-time metrics are displayed in the first page of the Status dashboard, and information relating to metrics history is not displayed in the other pages of the dashboard. To render the first entry of the graph, you need to wait for the time duration specified as the pollingPeriod.

   # Enable JDBC Reporter
    name: JDBC
    enabled: true
    pollingPeriod: 60
   

3. Under  wso2.metrics.jdbc , configure the following properties to clean up the database entries.
   

   wso2.metrics.jdbc:
     # Data Source Configurations for JDBC Reporters
     dataSource:
       # Default Data Source Configuration
       - &JDBC01
         # JNDI name of the data source to be used by the JDBC Reporter.
         # This data source should be defined in a *-datasources.xml file in conf/datasources directory.
         dataSourceName: java:comp/env/jdbc/WSO2MetricsDB
         # Schedule regular deletion of metrics data older than a set number of days.
         # It is recommended that you enable this job to ensure your metrics tables do not get extremely large.
         # Deleting data older than seven days should be sufficient.
         scheduledCleanup:
           # Enable scheduled cleanup to delete Metrics data in the database.
           enabled: false
   
           # The scheduled job will cleanup all data older than the specified days
           daysToKeep: 7
   
           # This is the period for each cleanup operation in seconds.
           scheduledCleanupPeriod: 86400

   
   

   Parameter	Default Value	Description
   dataSource	&JDBC01
   dataSource > dataSourceName	java:comp/env/jdbc/WSO2MetricsDB	The name of the data source used to store metric data.
   dataSource > scheduledCleanup > enabled	false	If this is set to true, metrics data stored in the database is cleared at a specific time interval as scheduled.
   dataSource > scheduledCleanup > daysToKeep	3	If scheduled clean-up of metric data is enabled, all metric data in the database that are older than the number of days specified in this parameter are deleted.
   dataSource > scheduledCleanup > scheduledCleanupPeriod	86400	This parameter specifies the time interval in seconds at which all metric data stored in the database must be cleared.

    

4. JVM metrics of which the log level is set to OFF are not measured by default. If you need to monitor one or more of them, add the relevant metric name(s) under the wso2.metrics: => levels subsection as shown in the extract below. As shown below, you also need to mention log4j mode in which the metrics need to be monitored (i.e., OFF, INFO, DEBUG, TRACE or ALL).
   

   wso2.metrics:
    # Enable Metrics
      enabled: true
      jmx:
         # Register MBean when initializing Metrics
       registerMBean: true
         # MBean Name
       name: org.wso2.carbon:type=Metrics
       # Metrics Levels are organized from most specific to least:
       # OFF (most specific, no metrics)
       # INFO
       # DEBUG
       # TRACE (least specific, a lot of data)
       # ALL (least specific, all data)
    levels:
         # The root level configured for Metrics
       rootLevel: INFO
         # Metric Levels
       levels:
            jvm.buffers: 'OFF'
            jvm.class-loading: INFO
            jvm.gc: DEBUG
            jvm.memory: INFO

    Click here to view the default metric levels supported...

   
   

   • Classloading

     Property	Default Level	Description
     jvm.class-loading.loaded.current	INFO	The gauge showing the number of classes currently loaded for the JVM.
     jvm.class-loading.loaded.current
     jvm.class-loading.unloaded.total

     
     

   • Garbage collector

     Property	Default Level	Description
     jvm.gc.PS-MarkSweep.count	DEBUG	The gauge for showing the garbage collection and memory usage. Monitoring this allows you to identify memory leaks and memory trash that have a negative impact on performance.
     jvm.gc.PS-MarkSweep.time
     jvm.gc.PS-MarkSweep.time
     jvm.gc.PS-Scavenge.time

   • Memory

     Property	Default Level	Description
     metric.level.jvm.gc	INFO	The gauge for showing the used and committed memory in WSO2 SP.
     jvm.memory.heap.committed	INFO	The gauge for showing the used and committed heap in WSO2 SP.
     jvm.memory.heap.init
     jvm.memory.heap.max
     jvm.memory.heap.usage
     jvm.memory.non-heap.committed	INFO	The gauge for showing the used code cache and used CMS Perm Gen in WSO2 SP.
     jvm.memory.non-heap.init
     jvm.memory.non-heap.max
     jvm.memory.non-heap.usage
     jvm.memory.non-heap.used
     jvm.memory.total.committed	INFO	The gauge for showing the total memory currently available for the JVM.
     jvm.memory.total.init
     jvm.memory.total.max
     jvm.memory.total.used
     jvm.memory.pools	OFF
     jvm.memory.pools	OFF

   • Operating system load

     Property	Default Level	Description
     jvm.os	INFO	The gauge for showing the current load imposed by the JVM on the operating system.
     jvm.os.cpu.load.process	INFO
     jvm.os.cpu.load.process
     jvm.os.system.load.average

   • Threads

     Property	Default Level	Description
     jvm.threads.count	Debug	The gauge for showing the number of active and idle threads currently available in the JVM thread pool.
     jvm.threads.daemon.count	Debug	The gauge for showing the number of active daemon threads currently available in the JVM thread pool.
     jvm.threads.blocked.count	OFF	The gauge for showing the number of threads that are currently blocked in the JVM thread pool.
     jvm.threads.deadlock.count	OFF	The gauge for showing the number of threads that are currently deadlocked in the JVM thread pool.
     jvm.threads.new.count	OFF	The gauge for showing the number of new threads generated in the JVM thread pool.
     jvm.threads.runnable.count	OFF	The gauge for showing the number of runnable threads currently available in the JVM thread pool.
     jvm.threads.terminated.count	OFF	The gauge for showing the number of threads terminated from the JVM thread pool since user started running the WSO2 API Manager instance.
     jvm.threads.timed_waiting.count	OFF	The gauge for showing the number of threads in the Timed_Waiting state.
     jvm.threads.waiting.count	OFF	The gauge for showing the number of threads in the Waiting state in the JVM thread pool. One or more other threads are required to perform certain actions before these threads can proceed with their actions.

   • File descriptor details

     Property	Default Level	Description
     file.descriptor.max.count	INFO	The gauge for showing the number of open file descriptors and max file descriptors.
     file.descriptor.open.count

   • Swap space

     Property	Default Level	Description
     swap.space.free.size	INFO	The gauge for showing the amount of free and total swap space in bytes.
     swap.space.total.size

Configuring Siddhi application metrics

To enable Siddhi application-level metrics for a Siddhi application, you need to add the @app:statistics annotation bellow the Siddhi application name in the Siddhi file as shown in the example below.

@App:name('TestMetrics')
@app:statistics(reporter = 'jdbc')
define stream TestStream (message string);

The following are the metrics measured for a Siddhi application.

Configuring cluster credentials

In order to access the nodes in a cluster and derive statistics, you need to maintain and share a user name and a password for each node in a SP cluster. This user name and password must be specified in the <SP_HOME>/conf/dashboard/deployment.yaml file. If you want to secure sensitive information such as the user name and the password, you can encrypt them via WSO2 Secure Vault.

1. To specify the user name and the password to access a node, define them under the wso2.status.dashboard section as shown in the following example.

   wso2.status.dashboard:  
   	workerAccessCredentials:
       	username: 'admin'
       	password: 'admin'

2. To encrypt the user name and the password you defined, define aliases for them as described in Protecting Sensitive Data via the Secure Vault.

   This functionality is currently supported only for single-tenant environments.

Configuring permissions

The following are the three levels of permissions that can be granted for the users of WSO2 Stream Processor Status Dashboard.

The admin user in the userstore is assigned the SysAdmin permission level by default.

To assign different permission levels to different roles, you can list the required roles under the relevant permission level in the wso2.status.dashboard section of the SP_HOME>/conf/dashboard/deployment.yaml file as shown in the extract below.

wso2.status.dashboard:
  sysAdminRoles:
	- role_1
  developerRoles:
	- role_2
  viewerRoles:
	- role_3