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 uses 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.

You need to ensure that the carbon ID of each node is unique because it is required for the Status dashboard to identify the worker nodes and display their statistics accordingly.

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.

The Status Dashboard is only supported with H2, MySQL, MSSQL and Oracle database types. It is configured with the H2 database type by default. If you want to continue to use H2, skip this step.

Download and install the required database type. For this example, let's download and install MySQL Server.
Download the required database driver. For this example, download the MySQL JDBC driver.
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.
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
When prompted, specify the password you are using to access the databases with the username you specified.

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";

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

The names of the datasources must be thesame 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 datasources, 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.

To enable wso2 metrics, set the enabled property to true under wso2.metrics as shown below.
```
wso2.metrics:
  enabled: true
```
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
```

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 datasource 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.

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...

Class loading

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('true')
define stream TestStream (message string);

The following are the metrics measured for a Siddhi application.

The default level after enabling metrics is INFO for all the meytrics listed in the following table.

Metric	Components to which the metric is applied
Latency	Windows (per window.find and window.add) Mappers (per sink mapper, source mapper) Queries (per query) Tables (per table insert, find, update, updateOrInsert, delete, contains)
Throughput	Windows (per window.find and window.add) Mappers (per sink mapper, source mapper) Queries (per query) Tables (per table insert, find, update, updateOrInsert, delete, contains )
Memory	Queries (per query)
Buffered Events Count
Number of events at disruptor	Streams (per stream)
Number of events produced/received after restart	Sources (per source) Sinks (per sink)

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.

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'
```
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.

Permission Level	Granted permissions
`SysAdmin`	Enabling/disabling metrics Adding workers Deleting workers Viewing workers
`Developers`	Adding workers Deleting workers Viewing workers
`Viewers`	Viewing workers

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

The display name of the roles given in the configuration must be present in the user store. To configure user store check, User Management.

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`	INFO

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`