com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_link3' is unknown.

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.

  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 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 TypeMetrics DatasourceDashboard 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 wso2 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


    ParameterDefault ValueDescription
    dataSource&JDBC01
    dataSource > dataSourceNamejava:comp/env/jdbc/WSO2MetricsDBThe name of the datasource used to store metric data.
    dataSource > scheduledCleanup > enabledfalseIf this is set to true, metrics data stored in the database is cleared at a specific time interval as scheduled.
    dataSource > scheduledCleanup > daysToKeep3If 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 > scheduledCleanupPeriod86400This 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...


    • Class loading

      PropertyDefault LevelDescription
      jvm.class-loading.loaded.currentINFOThe gauge showing the number of classes currently loaded for the JVM.
      jvm.class-loading.loaded.current
      jvm.class-loading.unloaded.total


    • Garbage collector

      PropertyDefault LevelDescription
      jvm.gc.PS-MarkSweep.countDEBUGThe 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

      PropertyDefault LevelDescription
      metric.level.jvm.gcINFOThe gauge for showing the used and committed memory in WSO2 SP.
      jvm.memory.heap.committedINFOThe 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.committedINFOThe 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.committedINFOThe 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.poolsOFF
      jvm.memory.poolsOFF
    • Operating system load

      PropertyDefault LevelDescription

      jvm.os


      INFOThe gauge for showing the current load imposed by the JVM on the operating system.
      jvm.os.cpu.load.processINFO
      jvm.os.cpu.load.process
      jvm.os.system.load.average
    • Threads

      PropertyDefault LevelDescription
      jvm.threads.countDebugThe gauge for showing the number of active and idle threads currently available in the JVM thread pool.
      jvm.threads.daemon.countDebugThe gauge for showing the number of active daemon threads currently available in the JVM thread pool.
      jvm.threads.blocked.countOFFThe gauge for showing the number of threads that are currently blocked in the JVM thread pool.
      jvm.threads.deadlock.countOFFThe gauge for showing the number of threads that are currently deadlocked in the JVM thread pool.
      jvm.threads.new.countOFFThe gauge for showing the number of new threads generated in the JVM thread pool.
      jvm.threads.runnable.countOFFThe gauge for showing the number of runnable threads currently available in the JVM thread pool.
      jvm.threads.terminated.countOFFThe 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.countOFFThe gauge for showing the number of threads in the Timed_Waiting state.
      jvm.threads.waiting.countOFFThe 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

      PropertyDefault LevelDescription
      file.descriptor.max.countINFOThe gauge for showing the number of open file descriptors and max file descriptors.
      file.descriptor.open.count
    • Swap space

      PropertyDefault LevelDescription
      swap.space.free.sizeINFOThe 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.

MetricComponents 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 )
MemoryQueries (per query)
Buffered Events Count
Number of events at disruptorStreams (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.

  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.

Permission LevelGranted permissions
SysAdmin
  • Enabling/disabling metrics
  • Adding workers
  • Deleting workers
  • Viewing workers
Developers
  • Adding workers
  • Deleting workers
  • Viewing workers
ViewersViewing 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.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.