Runtime ClusterMonitor Configuration

Overview

This article provides a reference for writing a StreamBase Runtime ClusterMonitor configuration file, which is used as a component of cluster monitoring.

Required Header Lines

Each configuration file must contain the following header lines, typically found at the beginning of each file:

name

Specifies an arbitrary, case-sensitive string to name this configuration, which must be unique among other files with the same type, if any. Configuration files can refer to each other by this name. Select a name that reminds you of this configuration's type and purpose. For example:

name = "FullAppConfig"
version

Specifies an arbitrary version number that you can use to keep track of file versions for this configuration type in your development project. The maintenance of version numbers is under user control; StreamBase does not compare versions when loading configuration files during the fragment launch process. The version number is a string value, and can contain any combination of characters and numbers. For example:

version = "1.0.0"
type

This essential setting specifies the unique HOCON configuration type described on this page.

type = "com.tibco.ep.dtm.configuration.clustermonitor"

The three header lines taken together constitute a unique signature for each HOCON file in a project's configurations folder. Each project's configurations folder can contain only one file with the same signature.

The top-level configuration object defines the configuration envelope the same way for all HOCON file types.

configuration

On a line below the header element lines, enter the word configuration followed by an open brace. The configuration element is a sibling of the name, version, and type elements, and serves to define the configuration envelope around this type's objects as described on this page. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Elements Explained

This section provides detailed descriptions for all properties in each configuration object.

ClusterMonitor

If you want to manually restrict this object to be associated with specific engines, do so here. Each entry can be a specific engine name or a regular expression that can applies to more than one engine. This name-value pair is optional and has no default value. If not present, the configuration uses default engine association based on its location in a fragment or application archive, or in a node deploy configuration.

associatedWithEngines

If you want to restrict this object to be associated with specific engines, do so here. Each entry can be a specific engine name or a regular expression that can applies to more than one engine. This name-value pair is optional and has no default value. If not present, the configuration is associated with all engines.

For example:

[ "javaengine", "otherengine[0-9]" ]
administrationAuthentication

Optional credentials to use when executing the epadmin commands.

userName

String. The user name used by the authentication system to access to the node. Required.

For example:

userName = "administrator"
password

String. The password used by the authentication system to access the node. You can provide an enciphered string for the value; generate the enciphered string with the sbcipher command and prefix #! to the generated string. This name-value pair is required.

For example:

password = "mypassword"
eventFlowAuthentication

Optional credentials to use when connecting to StreamBase servers.

userName

The user name to use when connecting to the EventFlow or LiveView StreamBase listener.

For example:

userName = "sbAdministrator"
password

The password to use when connecting to the EventFlow or LiveView StreamBase listener. A value beginning with #! is enciphered with the sbcipher tool.

For example:

password = "mypassword"
commands

String. A list of epadmin commands to run against discovered node services for every collection interval, and then publish to LiveView server tables.

The epadmin is described on its reference page, and in depth at this link.

commandName

Optional list of epadmin commands to run.

targetName

Administration target name. Required.

For example:

targetName = "history"
parameters

String. Optional command parameters.

tableName

The name of the LiveView table for the command results. This name must be a legal LiveView table name, starting with a letter, followed by a combination of letters, digits, and underscores. Whitespace is not allowed. Optional. Defaults to t_commandName_targetName.

For example:

tableName = "NodeInfo"
collectionIntervalSeconds

Int. Optional. Number of seconds between command invocations. Default = 1.

For example:

collectionIntervalSeconds = 1
eventFlow

Optional EventFlow monitoring control using the any of the following name-value pairs.

systemInfo

Bool. Used to monitor EventFlow system statistics. Default = true.

streamInfo

Bool. Used to monitor EventFlow stream statistics. Default = true.

queueInfo

Bool. Used to monitor EventFlow queue statistics. Default = true.

rowAgeLimitSeconds

Optional. Age limit of data rows in the commands tables. Rows older than tableTrimSeconds will be periodically removed. Default = 60.

For example:

rowAgeLimitSeconds = 60
rowCheckIntervalSeconds

Optional. The interval at which tables are checked for removing old rows. Default = 30.

For example:

rowCheckIntervalSeconds = 30

Configuration Sample

Sample 1 is based on the servicediscoveryadapter portion of the default configuration file used in the Cluster Monitor application.

Sample 2 is the entire default configuration for the Cluster Monitor application, which combines the servicediscoveryadapter.conf and clustermonitor.conf files into one configuration.

name = "clustermonitor"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.clustermonitor"
configuration =
{
  ClusterMonitor =
    {
       associatedWithEngines = [ "cluster-monitor" ]
     
       //
       // A list of administration commands to run against discovered
       // node services, every collection interval, and then publish
       // to LiveView server tables.
       //
          commands =
          [
            {
       //
       // Administration command name. Required.
       //
          commandName = "display"
       //
       // Administration target name. Required.
       //
          targetName = "history"
       //
       // A list of command parameters. Optional.
       //
          parameters =
            {
              "seconds" = "1"
            }
       //
       // The name of the LiveView table for the command results.
       // This name must be a legal LiveView table name, starting
       // with a letter, followed by a combination of letters, digits,
       // and underscores.  Whitespace is not allowed.
       //
       // Optional. Will default to "t_commandName_targetName"
       //
          tableName = "NodeInfo"
       //
       // Number of seconds between command invocations.
       // Optional. Defaults to 1.
       //
          collectionIntervalSeconds = 1
          },
     
       // Additional commands may be added here.
          ]
       //
       // Age limit for data rows in the monitor tables.
       // Optional.  Defaults to 60.
       //
       // rowAgeLimitSeconds = 60
       //
       // The interval at which tables are checked for removing old rows.
       // Optional.  Defaults to 30.
       //
       // rowCheckIntervalSeconds = 30
       //
       // Optional credentials for running the administration commands.
       //
       // administrationAuthentication =
       // {
       //    //
       //    // The user name to use when connecting to the node.
       //    //
       //    userName = "administrator"
       //    //
       //    // The password to use when connecting to the node.
       //    //
       //    password = "This is a plain text password"
       // }
       //
       // Optional credentials for collecting StreamBase statistics.
       //
       // eventFlowAuthentication =
       // {
       //    //
       //    // The user name to use when connecting to the
       //    // EventFlow or LiveView StreamBase listener.
       //    //
       //    userName = "sbAministrator"
       //    //
       //    // The password to use when connecting to the
       //    // EventFlow or LiveView StreamBase listener.
       //    // A value beginning with '#!' is enciphered
       //    // with the sbcipher tool.
       //    //
       //    password = "#!xyzzy"
       // }
    }
}

It is possible to configure separate servicediscoveryadapter.conf and clustermonitor.conf files, which when used together support cluster monitoring. In most cases, it is easier to configure a combined file, as shown in this default Cluster Monitor configuration.

// Default configuration for the StreamBase Cluster Monitor.
//
// To change this configuration, make a copy of this entire file
// and use the nodedeploy option to epadmin install node.
//
// HOCON substitution variables used in this configuration:
//
// NODE_NAME       Required. The name of the node that the monitor application is
//                      installed to (the nodename parameter to epadmin install node).
//
// LIVEVIEW_PORT   Defaults to 10080
//
// These variables may be overridden via the substitutions or substitutionfile
// parameters to epadmin install node.
//
name = "ClusterMonitor"
version = "1.0"
type = "com.tibco.ep.dtm.configuration.node"
  configuration = {
    NodeDeploy = {
      nodes  =  {
        "${NODE_NAME}" =
             {
               description = "Node for running the ClusterMonitor"
               engines =
             {
               "cluster-monitor" =
             {
               fragmentIdentifier = "com.tibco.ep.cluster.eventflow"
                 configuration =
                   [
                     """
                       name = "cluster-monitor-service-discovery"
                       version = "1.0.0"
                       type = "com.tibco.ep.streambase.configuration.servicediscoveryadapter"
                       configuration =
                         {
                           ServiceDiscovery =
                             {
                               associatedWithEngines = [ "cluster-monitor" ]
                                 //
                                 // The port to use for discovery requests.
                                 // Optional. Defaults to the port being used by the node where
                                 // this configuration is loaded.
                                 //
                                 // discoveryPort = 54321
     
                                 //
                                 // A list of host names that specify which network interfaces
                                 // to use when sending discovery requests.
                                 // Optional. Defaults to the system's host name.
                                    discoveryHosts = [ ]
                                 //
                                 // Service names that will be discovered by the cluster monitor.
                                 // Optional. Defaults to all service names found.
                                 // Uncomment to restrict.
                                 //
                                 // serviceNames = [ "cluster1", "cluster2", "nodeA.cluster3" ]
                                 //
                                 // Service types that will be discovered by cluster monitor.
                                 // Optional. Empty defaults to all service types, but the cluster
                                 // monitor only knows how to monitor node, eventflow and
                                 // liveview services.
                                 //
                                    serviceTypes = [ "node", "eventflow", "liveview" ]
                                 //
                                 // The number of seconds between discovery requests.
                                 // Optional. Defaults to 1.
                                 //
                                 // discoveryBrowseIntervalSeconds = 1
                                 //
                                 // This causes the cluster-monitor event flow application
                                 // to wait for the LiveView server to become ready before
                                 // starting.  Do not change.
                                 //
                                    autostart = false
                                 //
                                 // Whether or not services running within the monitor's node
                                 // are discovered and monitored.
                                 // Defaults to false.
                                 //
                                    includeLocalServices = ${INCLUDE_LOCAL_SERVICES:-false}
                                  }
                              }
                                """,
     
                                """
                                name = "clustermonitor"
                                version = "1.0.0"
                                type = "com.tibco.ep.streambase.configuration.clustermonitor"
                                configuration =
                                {
                                    ClusterMonitor =
                                    {
                                        associatedWithEngines = [ "cluster-monitor" ]
     
                                        //
                                        // A list of administration commands to run against discovered
                                        // node services, every collection interval, and then publish
                                        // to LiveView server tables.
                                        //
                                        commands =
                                        [
                                            {
                                                //
                                                // Administration command name. Required.
                                                //
                                                commandName = "display"
     
                                                //
                                                // Administration target name. Required.
                                                //
                                                targetName = "history"
     
                                                //
                                                // A list of command parameters. Optional.
                                                //
                                                parameters =
                                                {
                                                   "seconds" = "1"
                                                }
     
                                                //
                                                // The name of the LiveView table for the command results.
                                                // This name must be a legal LiveView table name, starting
                                                // with a letter, followed by a combination of letters, digitis,
                                                // and underscores.  Whitespace is not allowed.
                                                //
                                                // Optional. Will default to "t_commandName_targetName"
                                                //
                                                tableName = "NodeInfo"
     
                                                //
                                                // Number of seconds between command invocations.
                                                // Optional. Defaults to 1.
                                                //
                                                collectionIntervalSeconds = 1
                                            },
     
                                            // Additional commands may be added here.
                                        ]
     
                                        //
                                        // Age limit for data rows in the monitor tables.
                                        // Optional.  Defaults to 60.
                                        //
                                        // rowAgeLimitSeconds = 60
     
                                        //
                                        // The interval at which tables are checked for removing old rows.
                                        // Optional.  Defaults to 30.
                                        //
                                        // rowCheckIntervalSeconds = 30
     
                                        //
                                        // Optional credentials for running the administration commands.
                                        //
                                        // administrationAuthentication =
                                        // {
                                        //    //
                                        //    // The user name to use when connecting to the node.
                                        //    //
                                        //    userName = "administrator"
                                        //    //
                                        //    // The password to use when connecting to the node.
                                        //    //
                                        //    password = "This is a plain text password"
                                        // }
     
                                        //
                                        // Optional credentials for collecting StreamBase statistics.
                                        //
                                        // eventFlowAuthentication =
                                        // {
                                        //    //
                                        //    // The user name to use when connecting to the
                                        //    // EventFlow or LiveView StreamBase listener.
                                        //    //
                                        //    userName = "sbAministrator"
                                        //    //
                                        //    // The password to use when connecting to the
                                        //    // EventFlow or LiveView StreamBase listener.
                                        //    // A value beginning with '#!' is enciphered
                                        //    // with the sbcipher tool.
                                        //    //
                                        //    password = "#!xyzzy"
                                        // }
                                    }
                                }
                                """,
     
                                """
                                name = "cluster-monitor-operator-parameters"
                                version = "1.0.0"
                                type = "com.tibco.ep.streambase.configuration.sbengine"
                                configuration =
                                {
                                    StreamBaseEngine =
                                    {
                                        streamBase =
                                        {
                                            operatorParameters =
                                            {
                                                   LIVEVIEW_PORT = ""${LIVEVIEW_PORT:-10080}
                                            }
                                        }
                                    }
                                }
                                """
                            ]
                        }
     
                        "liveview-server" =
                        {
                            fragmentIdentifier = "com.tibco.ep.cluster.liveview-server"
     
                            configuration =
                            [
                                """
                                name = "liveview-server-listener"
                                type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"
                                version = "1.0.0"
     
                                configuration =
                                {
                                    ClientAPIListener =
                                    {
                                        associatedWithEngines = [ "liveview-server" ]
                                        portNumber = ${LIVEVIEW_PORT:-10080}
                                    }
                                }
                                """,
     
                                """
                                name = "liveview-sb-listener"
                                type = "com.tibco.ep.streambase.configuration.sbclientapilistener"
                                version = "1.0.0"
                                configuration =
                                {
                                    ClientAPIListener =
                                    {
                                        associatedWithEngines = [ "liveview-server" ]
                                        apiListenerAddress =
                                        {
                                          portNumber = 0
                                        }
                                    }
                                }
                                """,
     
                                """
                                name = "liveview-server-engine"
                                version = "1.0.0"
                                type = "com.tibco.ep.ldm.configuration.ldmengine"
     
                                configuration = {
                                  LDMEngine = {
                                      //
                                      // Recommended JVM 1.8 flags for LiveVew
                                      //
                                      jvmArgs =
                                      [
                                          "-Xmx4g"
                                          "-Xms1g"
                                          "-XX:+UseG1GC"
                                          "-XX:MaxGCPauseMillis=500"
                                          "-XX:ConcGCThreads=1"
                                          "-XX:+UseCompressedOops"
                                      ]
                                      systemProperties = {
                                        "liveview.web.pstore.type" = "h2"
                                      }
                                      ldm = {
                                      }
                                  }
                              }
                              """
                          ]
                      }
                  }
              }
          }
      }
  }