Live Datamart Engine Configuration

Overview

This article provides a reference for writing a Live Datamart Engine configuration file where the HOCON type is com.tibco.ep.ldm.configuration.ldmengine.

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 = "myldmengine"
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.ldm.configuration.ldmengine"

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 lines, enter the word configuration followed by an open brace. The configuration object is a sibling of the name, version, and type identifiers, 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 Properties Explained

Below shows the configuration's HOCON properties, usage, and syntax example, where applicable.

LDMEngine

Root object for the Live Datamart engine configuration. The Live Datamart engine configuration inherits from the EventFlow engine configuration, which in turn inherits from the base Java engine. See Runtime JavaEngine Configuration for a list of available Java engine options.

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

For example:

associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
externalClassPath

Sample Java engine settings, using a subset of the full Java engine model to demonstrate inheritance.

externalClassPath = [
  "/absolute/path/d.jar"
  "/absolute/path/g.jar"
  "/absolute/path/root" // class file hierarchy
]
jvm

Used to specify properties to pass to the Java virtual machine (JVM) that runs Live Datamart Server.

minimumDispatchThreads

Minimum number of dispatch threads. This property is optional and its default value is 10.

For example:

minimumDispatchThreads = 10
maximumDispatchThreads

Long. Specifies the maximum number of dispatch threads. This property is optional and its default value is 2000. For example:

maximumDispatchThreads = 2000
shutdownTimerSeconds

Long. Specifies the maximum number of seconds to wait for a JVM to shut down before aborting it. This property is optional and its default value is 60. For example:

shutdownTimerSeconds = 60
timerParallelism

Long. Specifies the number of timers that can be executing concurrently. This property is optional and its default value is 1. For example:

timerParallelism = 1
timerResolutionMilliseconds

Long. Specifies the maximum timer resolution. This is the interval at which timers are examined. Higher resolution timers have more impact on system performance. This property is optional and its default value is 1000. For example:

timerResolutionMilliseconds = 1000
schedulerPolicy

The scheduling policy for the JVM process. The valid values for the policy are SCHED_FIFO, SCHED_RR, and SCHED_OTHER. This property is optional. For example:

schedulerPolicy = "SCHED_FIFO"
schedulerPriority

Long. Specifies the scheduling priority for the JVM process. The valid range for priority depends on the policy; for Linux the valid values for SCHED_FIFO and SCHED_RR are 1 to 99. This property is optional and its default value is operating system-specific. For example:

schedulerPriority = 1
systemProperties

A list of Java system properties that will be set in each engine that uses this configuration. This object is optional and has no default value.

Note this is where you would put any LiveView system properties that are not explicitly modeled in this configuration.

For example:

systemProperties = {
  prop1 = "val1"           
  prop2 = "val2"
  "prop.3" = "val3" // note dot, path separator so must be inside quoted string
}
jvmArgs

An array of JVM arguments used in each engine instance on this operating system type. These values can be overridden by individual application fragments. This array is optional and has no default value.

For example:

jvmArgs = [
  "-Xmx3g"
  "-Xms512m"
  "-XX:+UseG1GC"
  "-XX:MaxGCPauseMillis=500"
  "-XX:ConcGCThreads=1"
]
streamBase

This object controls the behavior of the EventFlow engine that is running this LiveView fragment. Some sample EventFlow engine settings are below, to demonstrate inheritance. See StreamBase Engine Configuration for more information about the streamBase object.

operatorStateChangeTimeoutMilliseconds

Int. Each Java operator changes state along with the engine process as a whole. The engine waits for each operator to change state before it completes its state change. The value of this property is the amount of time the engine will wait before timing out the operator. If an operator is timed out on a state change, the engine shuts down the operator and proceeds with the state change. This property is optional and its default value is 10000.

For example:

operatorStateChangeTimeoutMilliseconds = 10002
engineMonitor

Configures the engine's monitoring subsystem. This object is optional.

enabled

Boolean. If false, prevents the StreamBase profile service from starting. If true, the profile service starts. This property is optional and its default value is true. Do not change this property to false except under the guidance of TIBCO Support.

statsFrequencyMilliseconds

Int. Configures how frequently monitoring stats are produced. This property is optional and its default value is 1000.

For example:

statsFrequencyMilliseconds = 2000
ldm

Live Datamart-specific part of the configuration.

alert

Alert service configuration. This object is optional and has values as specified below.

enabled

Bool. If false, prevent the alert service from starting. If true, the alert service starts. This property is optional and its default value is true.

For example:

enabled = false
disableChanges

Bool. If true, prevent non-local LiveView clients from changing alert rules. If false, any client can change alert rules. This property is optional and its default value is false.

For example:

disableChanges = true
registerStartup

Bool. If false, prevents configured alerts from being registered at startup. If true, alerts are registered. This property is optional and its default value is true.

For example:

registerStartup = false
metadataStore

Identifies the type of LiveView metadata store to use.

storeType

Identifies the type of LiveView metadata store {H2|TRANSACTIONAL_MEMORY|JDBC} to use. This property is optional and its default value is H2.

For example:

storeType = "JDBC"
jdbcDataSource

Sets the JDBC data source used to identify the back-end JDBC database that will be used to store the LiveView metadata. The property is required when the storeType is JDBC and must be a configuration filename of HOCON type jdbcdatasource. It does not have a default value.

For example:

jdbcDataSource = "NAME_FOR_THE_DATA_SOURCE_HOCON_CONFIGURATION" 
jdbcMetadataTableNamePrefix

A prefix for the names of tables that store LiveView metadata. This property is relevant only when the storeType is JDBC. The property is optional and its default value is an empty string.

For example:

jdbcMetadataTableNamePrefix = "LV_CLUSTER1_"

HOCON Configuration File Sample

The following shows an example of the com.tibco.ep.ldm.configuration.ldmengine type, to illustrate how you can configure the Java and EventFlow parts of the LiveView engine.

name = "myldmengine"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmengine"
configuration = {
  LDMEngine = {
    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
    externalClassPath = [
      "/absolute/path/d.jar"
      "/absolute/path/g.jar"
      "/absolute/path/root" 
    ]
    jvm = {
      minimumDispatchThreads = 10
    }
    systemProperties = { 
      "liveview.server.allowedOrigins" = "*" }
    jvmArgs = [
      "-Xmx3g"
      "-Xms512m"
      "-XX:+UseG1GC"
      "-XX:MaxGCPauseMillis=500"
      "-XX:ConcGCThreads=1"
    ]
    streamBase = {
      operatorStateChangeTimeoutMilliseconds = 10002
      engineMonitor = {
        enabled = false
        statsFrequencyMilliseconds = 2000
      }
    }
    ldm = {
      alert = {
        enabled = false
        disableChanges = true
        registerStartup = false
      }
      metadataStore = {
        storeType = "JDBC" 
        jdbcDataSource = "NAME_FOR_THE_DATA_SOURCE_HOCON_CONFIGURATION"        
        jdbcMetadataTableNamePrefix = "LV_CLUSTER1_"       
      }
    }
  }
}