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.

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.

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

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

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

   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

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.

The following are the metrics measured for a Siddhi application.

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.

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.