# DataSource monitoring configuration These DataSource configuration items determine who can monitor and manage a [DataSource application](index.md) through JMX, and what objects can be monitored and managed. They apply to all DataSource applications, such as [Liberator](../liberator/index.md), [Transformer](../transformer/index.md) and [Integration Adapters](../platform-architecture/putting-data-into-the-platform.md). You would typically monitor and manage the DataSource application from a monitoring client, such as the [Caplin Management Console](../cmc/index.md) (CMC). The permissions grant or deny a monitoring user, such as someone logged in to the CMC, permission to invoke specific operations on the application’s MBeans. ## add-monuser `add-monuser` specifies the credentials that allow a monitoring client application to log into a DataSource application. **Use in:** C, Java **Syntax**: There are three ways to specify the credentials. **Password** ``` add-monuser user username pass password roles rolename1,rolename2, ... end-monuser ``` **Secure (encrypted) password** ``` add-monuser user username secure-pass encryptedpassword roles rolename1,rolename2, ... end-monuser ``` **Signature key (Liberator and Transformer only)** ``` add-monuser user username key-id akeyidentifier roles rolename1,rolename2, ... end-monuser ``` **Options** * **user** **Type:** string | **Default:** _null_ A username that the monitoring client application can use to log in to the DataSource application via JMX. If the `user` and `pass` options, or `user` and `secure-pass` options, or `user` and `key-id` options, are not specified, the DataSource application will accept monitoring login requests from _any_ user. * **pass** **Type:** string | **Default:** An unencrypted password that the monitoring client application’s user specified in `user` must supply when logging in to the DataSource application via JMX. The DataSource application uses this option to verify the user’s password. You must specify a `pass` option, or a `secure-pass` option, or (for Liberator and Transformer only) a `key-id` option. * **secure-pass** **Type:** string | **Default:** A secure encryption of the password that the user of the monitoring client application (as specified in the `user` option) supplies when logging in to the DataSource application via JMX. The password the user enters must be encrypted before being passed to the DataSource application. The DataSource application uses this option to verify the user’s encrypted password. The cryptographic formats supported are [APR1](https://httpd.apache.org/docs/current/misc/password_encryptions.html) (an MD5-based encoding) and Unix Crypt. You must specify a `secure-pass` option, or a `pass` option, or (for Liberator and Transformer only) a `key-id` option. The `secure-pass` option overrides the `pass` option. Also see [Using the secure-pass option](#using-the-secure-pass-option-in-add-monuser) below. * **key-id** **Type:** string | **Default:** The identifier of a signature key, as specified in the `key-id` option of an `add-sigkey` configuration entry. This option can only be used in [Liberator](../liberator/index.md) and [Transformer](../transformer/index.md) configuration, and should be used instead of the `pass` option or `secure-pass` option when the monitoring client application is to log in using a [KeyMaster](../keymaster/index.md) user credentials token. The Liberator or Transformer uses this option to verify the user’s user credentials token - see [Using the key-id option](#using-the-key-id-option-in-add-monuser) below***__.__*** **📌 NOTE**\ This option is not available in Java-based DataSource applications. * **roles** **Type:** string | **Default:** `*` A comma separated list of roles that the user can have (no space separators allowed). A role defines the JMX MBean oprations in the DataSource application that the user can invoke. Roles are associated with MBeans through `add-mon-roles` configuration items. The wildcard role `*` grants the user permission to invoke any of the operations available on any MBeans; this is the default if no roles are specified. If a user attempts to invoke an operation without having permission, a `SecurityException` is thrown back to the monitoring client (in the [CMC](../cmc/index.md) the Exception is flagged in a pop-up), and, provided the DataSource application’s [log-monitor-level](datasource-datasource-monitoring-configuration-part-1.md#log-monitor-level) configuration item is set to at least `INFO`, details of the user and operation are logged in the DataSource application’s monitoring log file. In Liberator, the basic configuration file in the install kit contains the following monitoring client login credentials: ``` add-monuser user admin pass admin end-monuser ``` ### Using the secure-pass option in add-monuser Some examples: * Here’s the configuration for a monitoring user called 'admin', with password 'admin' that’s encrypted using the APR1 algorithm: ``` add-monuser user admin secure-pass $apr1$z71X7C20$3B6zCqZLN.WrBWpObcPaj. end-monuser ``` * This configuration is for monitoring user 'admin2', with password 'admin' that’s encrypted using the Crypt algorithm: ``` add-monuser user admin2 secure-pass hPF1s9piPZULA end-monuser ``` ### Using the key-id option in add-monuser This option can only be used in [Liberator](../liberator/index.md) and [Transformer](../transformer/index.md) configuration, A monitoring client application can be designed so that it logs in to the Liberator or Transformer through [KeyMaster](../keymaster/index.md), supplying a digitally signed user credentials token instead of a password (for example, the Caplin Management Console can do this). To allow Liberator/Transformer to handle monitoring login requests that have user credentials tokens, specify its add-monuser configuration with the options `user` and `key-id`, rather than `user` and `pass`. The value of the `key-id` option must match the [key-id](datasource-keymaster-configuration.md#key-id) value in an [add-sigkey](datasource-keymaster-configuration.md#add-sigkey) configuration item: ``` add-sigkey key-id akeyidentifier timeout 600 keyfile %r/etc/PublicKey.der hashing-algorithm md5 end-sigkey ... add-monuser user username key-id akeyidentifier end-monuser ``` The `add-sigkey` item specifies a signature checking key. When the JMX enabled monitoring client application logs in, Liberator/Transformer looks for an `add-monuser` entry with a matching username and then finds the [add-sigkey](datasource-keymaster-configuration.md#add-sigkey) item that has a [key-id](datasource-keymaster-configuration.md#key-id) value matching the `key-id` in `add-monuser`. It uses the `keyfile` option of the `add-sigkey` item to locate the file containing the user’s public encryption key. The Liberator’s or Transformer’s auth module can then use this public key to validate the digital signature in the user credentials token. ## add-mon-roles Each `add-mon-roles` configuration item refers to an MBean or set of MBeans, and specifies which roles grant permission to invoke specific operations on the MBean(s). **Use in:** C, Java **Syntax**: An `add-mon-roles` configuration item must contain a `beanname` option and at least one instance of `operation` or `operation-default`. ``` add-mon-roles xref:beanname[beanname] FXAdapter.example:name=bean1 xref:operation[operation] invokeMe adminrole xref:operation-default[operation-default] adminrole,superadminrole end-mon-roles ``` **Options** * **beanname** **Type:** string | **Default:** _null_ ``` beanname :[property=value][,...] ``` The name of an MBean object in the DataSource application, which can be monitored and/or managed. This option can also be a partial name that selects a set of MBeans. For an explanation of the formats allowed, see [Beanname format](#beanname-format) and [The four beanname specification types](#the-four-beanname-specification-types) below. * **operation** **Type:** array of strings | **Default:** _null_ ``` operation [,...] ``` The name of an operation on the MBean or MBeans selected by `beanname`, followed by a comma separated list of roles (see the role option of [add-monuser](#add-monuser)). This list specifies roles (and hence users) that can potentially invoke the operation for the MBeans specified by `beanname`, subject to the precedence rules for matching ``beanname``s defined in [The four beanname specification types](#the-four-beanname-specification-types) below. Example: `operation invokeMe adminrole,superadminrole` An `operation` option overrides, for that particular operation, any `operation-default` settings in the same `add-mon-roles` block. In particular, if a role is listed in `operation-default`, but not in `operation`, that role cannot invoke the operation. For more information on the rules of precedence, see [mon-operation-default](#mon-operation-default). * **operation-default** **Type:** string | **Default:** _null_ ``` operation-default [,...] ``` A comma separated list of roles (see the `role` option of [add-monuser](#add-monuser)). These roles are by default allowed to invoke all the operations on the MBeans specified by `beanname`, subject to the precedence rules for matching ``beanname``s defined in [The four beanname specification types](#the-four-beanname-specification-types) below. Example: `operation-default adminrole,superadminrole` The settings of `operation-default` are overridden by any operation settings in the same `add-mon-roles` block; see the description of the `operation` option. You can specify the `beanname` option of the `add-mon-roles` configuration item in one of four ways that define the precedence when matching MBeans to determine users' access to them. * [Beanname format](#beanname-format) * [The four beanname specification types](#the-four-beanname-specification-types) * [Applying the precedence rules](#applying-beanname-precedence-rules) ### Beanname format The general format for the beanname option follows the syntax for MBean object names: ``` : ``` where `` has the form: ``` property1=value,property2=value,... ``` In the examples on the rest of this page, we’ve assumed that our MBeans have just one property called `name`, which is the name of the MBean: `name=` An example of a `beanname` that includes the `name` property is: `FXAdapter.example:name=bean1` Because it has a fully specified domain and a ``, this `beanname` specifies the Object Name of an MBean - the MBean called `bean1` in the domain `FXAdapter.example` You can also define ``beanname``s with only partial domains and/or no ``. Such `beannames` have lower precedence when determining the access permissions that roles have to MBean operations. For more about this, see [The four beanname specification types](#the-four-beanname-specification-types) below. **📌 NOTE**\ The naming convention used at Caplin is for an MBean’s domain to start with the name of the Integration Adapter, as in `FXAdapter.example` For more about the syntax of MBean Object Names, and the conventions for them, see the Java documentation page [Java Management Extensions (JMX) - Best Practices](https://www.oracle.com/java/technologies/javase/management-extensions-best-practices.html). ### The four beanname specification types The four ways to specify bean names, listed in descending order of precedence, from highest precedence (4) to lowest precedence (1). | # | Domain | Properties | Example | | --- | --- | --- | --- | | 4 | Full | Present | FXAdapter.example:name=bean1 | | 3 | Partial | Present | .example:name=bean1 | | 2 | Full | Absent | FXAdapter.example: | | 1 | Partial | Absent | .example: | #### Precedence level 4 (highest precedence) A fully-specified domain with <key-property-list>. ``` add-mon-roles beanname FXAdapter.example:name=bean1 operation invokeMe adminrole end-mon-roles ``` In this example, the MBean called `bean1` in the domain `FXAdapter.example` exactly matches the `beanname`, so for this Integration Adapter, the role `adminrole` would be allowed to invoke ``bean1`’s `invokeMe` operation. But if this configuration were applied to a Transformer with an MBean called `bean1` but the MBean’s domain is `Transformer.example`, there would be no match and `adminrole` would be denied access to that MBean’s `invokeMe` operation. #### Precedence level 3 Partially specified domain with <key-property-list>. ``` add-mon-roles beanname .example:name=bean1 operation invokeMe adminrole end-mon-roles ``` In this example, any MBean called `bean1` whose domain ends in `.example` matches the `beanname`. So `adminrole` would be allowed to invoke the `invokeMe` operation of `FXAdapter.example:name=bean1` and `Transformer.example:name=bean1`, but would be denied access to this operation in `Transformer.example:name=bean2`. #### Precedence level 2 Fully specified domain but no <key-property-list>. ``` add-mon-roles beanname FXAdapter.example: operation invokeMe adminrole end-mon-roles ``` In this example, any MBean in the domain `FXAdapter.example` matches the `beanname`. So `adminrole` would be allowed to invoke the `invokeMe` operation on any MBean (that has this operation defined for it) in the `FXAdapter.example` domain. But if this configuration were applied to a Transformer where the domain is `Transformer.example`, there would be no match and `adminrole` would be denied access to the `invokeMe` operation on any of the MBeans having that operation. #### Precedence level 1 (lowest precedence) Partially specified domain and no <key-property-list>. ``` add-mon-roles beanname .example: operation invokeMe adminrole end-mon-roles ``` In this example, any MBean whose domain ends in `.example` matches the `beanname`. So `adminrole` would be allowed to invoke the `invokeMe` operation of _any_ MBean (that has this operation defined for it) in the domains `FXAdapter.example` and `Transformer.example` ### Applying beanname precedence rules If your configuration contains multiple instances of `add-mon-roles` with `beannames` of different precedences the permissions are applied to roles in the order of precedence as described above. These permissions are not additive; the permissions for a `beanname` with higher precedence always overwrite those for a `beanname` with lower precedence. For example, consider this configuration: ``` add-monuser user admin secure-pass hPF1s9piPZULA #"admin" roles adminrole end-monuser add-monuser user user1 pass Apetj.oXzcOrA #"password" roles userrole end-monuser add-mon-roles # Precedence level 1 beanname .server.peerstats: operation invokeMe adminrole end-mon-roles ``` Here the `add-mon-roles` configuration entry allows the role `adminrole` (and hence the user called 'admin') to invoke the `invokeMe` operation on any MBean that has this operation defined for it and that has a domain ending in `.server.peerstats` Now consider what happens when we add another `add-mon-roles` entry with a higher precedence for the `beanname` match: ``` add-mon-roles # Precedence level 1 beanname .server.peerstats: operation invokeMe adminrole end-mon-roles add-mon-roles # Precedence level 4 beanname FXAdapter.server.peerstats:name=bean1 operation invokeMe userrole end-mon-roles ``` The second `add-mon-roles` entry has a `beanname` with both a fully specified domain and a bean object name, so it has the highest precedence (level 4) and overrides the first `add-mon-roles` entry (which has the lowest possible precedence level of 1). This new entry allows the role `userrole` (and hence the user called 'user1') to invoke the `invokeMe` operation, on the MBean called `bean1` in the `FXAdapter.server.peerstats` domain. Because the permissions in the `add-mon-roles` entries are not additive, by default this new entry denies role `adminrole` (and any other roles) access to any of ``bean1`’s operations. So to ensure that role `adminrole` can access `bean1` in domain `FXAdapter.server.peerstats`, we need to add this role to the second `add-mon-roles` entry: ``` ... add-mon-roles # Precedence level 1 beanname .server.peerstats: operation invokeMe adminrole end-mon-roles add-mon-roles # Precedence level 4 beanname FXAdapter.server.peerstats:name=bean1 operation invokeMe adminrole,userrole end-mon-roles ``` We add `adminrole` to the role list in the `operation` option, so that this role can access `invokeMe`. ## jmxcache-hash-size `jmxcache-hash-size` specifies the size of the hash table needed by this DataSource application’s JMX module. The value should be about twice the total number of mbeans that the application will create***__.__*** **Use in:** C **Syntax:** `jmxcache-hash-size ` **Type:** integer **Default value:** `100000` ## log-monitor-level `log-monitor-level` specifies the threshold at which log messages about a DataSource application’s events and errors are published to the [monitoring subsystem,](datasource-datasource-monitoring-and-management.md) to be viewed by a monitoring client such as the [Caplin Management Console](../cmc/index.md). You can override this setting _for the Event log only_ by specifying the [monitor-level](datasource-logging-configuration.md#monitor-level) option of the [add-log](datasource-logging-configuration.md#add-log) configuration item. **Use in:** C **Syntax:** `log-monitor-level ` **Type:** string **Default value:** `INFO` **Values accepted:** | LEVEL | DESCRIPTION | | --- | --- | | `FINEST` | Reports highly detailed tracing messages. | | `FINER` | Reports fairly detailed tracing messages. | | `DEBUG` | Sends all errors and events. | | `INFO` | Sends events and information regarding normal operation and all errors included in the `WARN`, `NOTIFY`, `ERROR` and `CRIT` debug levels. | | `WARN` | Sends minor errors and all errors included in the `NOTIFY`, `ERROR` and `CRIT` debug levels. | | `NOTIFY` | Sends errors regarding data corruptions and all errors included in the `ERROR` and `CRIT` debug levels. | | `ERROR` | Sends serious errors regarding network connections and all errors included in the `CRIT` debug level. | | `CRIT` | Sends critical errors that prevent the DataSource application from running. | ## mon-operation-default The `mon-operation-default` configuration item sets the default roles (see the `role` option of [add-monuser](#add-monuser)) that can invoke all the operations on all of the DataSource application’s MBeans. Define the roles as a comma separated list with no spaces between the items. **Use in:** C, Java **Syntax:** `mon-operation-default [,...]` **Type:** string **Default value:** +[none]+ **Example:** `mon-operation-default adminrole,superadminrole,superuserrole` ### Precedence rules The value of `mon-operation-default` is overridden for particular MBeans by the [add-mon-roles](#add-mon-roles) option `operation-default`, which is itself overridden by the [add-mon-roles](#add-mon-roles) option `operation`. The order of precedence (highest to lowest) is as follows: ``` add-mon-roles/operation > add-mon-roles/operation-default > mon-operation-default ``` The override is absolute, not additive. The value of the configuration item of highest precedence applies; the values of overridden items are ignored. **Precedence example** ``` mon-operation-default superuserrole,adminrole,userrole ① add-mon-roles beanname .server.peerstats:name=bean1 operation-default superuserrole ② end-mon-roles add-mon-roles beanname FXAdapter.server.open:name=open operation-default superuserrole ③ operation invokeMe superuserrole,sysadminrole ④ end-mon-roles ``` 1. For any bean in any domain, the default roles permitted to execute operations are superuserrole, adminrole, and userrole. 2. For beans named **bean1** in domains ending in **server.peerstats**, the default role permitted to execute operations is **superuserrole**. This overrides `mon-operation-default`. 3. For the bean named **open** in the domain **FXAdapter.server.open**, the default role permitted to execute operations is **superuserrole**. This overrides `mon-operation-default`. 4. For the bean named **open** in the domain **FXAdapter.server.open**, the roles permitted to execute the **invokeMe** operation are **superuserrole** and **sysadminrole**. This overrides `operation-default` (3), which overrides `mon-operation-default` (1). ## monitor-moddir `monitor-moddir` defines the directory where the DataSource application’s JMX monitoring module is located. You only need to configure this if you’re writing your own DataSource application (such as an Integration Adapter). For Liberator and Transformer, this configuration is predefined in the JMX Config blade that comes with these components. **Use in:** C **Syntax:** `monitor-moddir DIRECTORY` If the first two characters of DIRECTORY are `%r`, the directory is prefixed with the root directory ([application-root](datasource-run-time-environment-configuration.md#application-root)) of the DataSource application installation; for example `/liberator/lib` or `/myadapter/lib` **Type:** string **Default value:** `%r/lib` ## monitor-module `monitor-module` defines the monitoring module that is to be loaded into the DataSource application. You only need to use this configuration item if you’re writing your own DataSource application (such as a C-based Integration Adapter). For Liberator and Transformer, this configuration is predefined in the JMX Config blade that comes with these components. **Use in:** C **Syntax:** `monitor-module jmx` ## object-latency-stat-period `object-latency-stat-period` defines the period, in seconds, over which latency statistics are calculated for viewing via an object’s `latency-chain` MBean attribute. At the end of this period, the data is reset and the calculation (averaging) starts again. For more about the `latency-chain` MBean and how to view it, see How can I... [Monitor latency statistics using the CMC](../cmc/cmc-monitor-latency-using-the-cmc.md). **Use in:** C **Syntax:** `object-latency-stat-period ` **Type:** integer **Default value:** `300` seconds (`5` minutes) ## object-monitoring-interval `object-monitoring-interval` defines the time interval in seconds at which Liberator monitors the state of its objects. To disable object monitoring, set this item to `-1.0` (the default). **Use in:** C (Liberator only) **Syntax:** `object-monitoring-interval ` **Type:** float **Default value:** `-1.0` ## peer-monitor-interval `peer-monitor-interval` specifies the interval in seconds at which statistics about this DataSource application’s connection to its DataSource peers are read and transferred to the application’s [JMX monitoring module](datasource-datasource-monitoring-and-management.md). You can override this item for a specific peer by adding a [monitor-interval](datasource-datasource-peers-configuration-part-1.md#monitor-interval) option to this DataSource application’s [add-peer](datasource-datasource-peers-configuration-part-1.md#add-peer) configuration item for the peer. **Use in**: C **Syntax:** `peer-monitor-interval ` **Type:** float **Default value:** `30.0` seconds ## process-usage-period `process-usage-period` defines the time interval in seconds at which the DataSource application’s CPU time counters `user-cputime-total` and `system-cputime-total` are updated. These counters can be viewed through JMX monitoring. If you’re using the [Caplin Management Console](../cmc/index.md), you can see them in the Explorer tab under `rttpd.server.system` **Use in:** C **Syntax:** `process-usage-period ` **Type:** float **Default value:** `10` seconds. ## prometheus-endpoint The URI of the Prometheus metrics endpoint. Defaults to `/metrics`. Prometheus metrics are disabled by default. To enable the Prometheus metrics endpoint, set [prometheus-port](#prometheus-port). **Use in:** Java **Since:** DataSource for Java 7.1.13 **Syntax:** `prometheus-endpoint ` **Type:** string **Default value:** `/metrics` ## prometheus-port Sets the port number of the Prometheus metrics endpoint. By default this is unset, which disables the Prometheus endpoint. To enable the Prometheus metrics endpoint, set `prometheus-port` to an integer. The default endpoint URI is `/metrics`. This can be customised for Java DataSources; see [prometheus-endpoint](#prometheus-endpoint). For descriptions of the metrics published by DataSources, see the following pages: * [DataSource Prometheus metrics](datasource-prometheus-metrics.md) * [Liberator Prometheus metrics](../liberator/liberator-prometheus-metrics.md) * [Transformer Prometheus metrics](../transformer/transformer-prometheus-metrics.md) **Use in:** C, Java **Since:** DataSource for C 7.1.16 (Liberator 7.1.15, Transformer 7.1.10, TREP Adapter 7.1.3) **Syntax:** `prometheus-port ` **Type**: integer **Default value:** +[none]+ **Example:** `prometheus-port 48557` ## prometheus-tags Sets a list of common tags to apply to all Prometheus metrics published by a Java DataSource. **Use in:** Java **Since:** DataSource for Java 7.1.13 **Syntax:** `prometheus-tags "" ...` **Type**: array of strings **Default value:** +[none]+ **Example:** `prometheus-tags "adapter"` ## rmi-client-port `rmi-client-port` defines the port in this DataSource application that a JMX-enabled monitoring client, such as the [Caplin Management Console](../cmc/index.md), connects to. Alternatively, you can define this port in the DataSource application’s [jvm-options](datasource-java-jvm-configuration.md#jvm-options) configuration, as follows: ``` jvm-options -Drmi.client.port ``` Only define the port once, using _either_ `rmi-client-port` _or_ `jvm-options`. **💡 TIP**\ You should normally set the `rmi-client-port` value one higher than the value of [rmi-registry-port](#rmi-registry-port). In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), [configuration variables](datasource-configuration-syntax.md#configuration-variables) are used to specify `rmi-client-port` for Liberator and Transformer; for example, `LIBERATOR${THIS_LEG}_JMX_RMI_CLIENT_PORT`. See [Deployment Framework configuration variables](../deployment-framework/cdf-configuration-macros-and-items.md). **Use in:** C, Java **Syntax:** `rmi-client-port ` **Type:** integer **Default value:** `-1` (no port defined) ## rmi-registry-port `rmi-registry-port` defines a port in this DataSource application that a JMX-enabled monitoring client, such as the [Caplin Management Console](../cmc/index.md), uses to obtain monitored data. (It’s the port that’s used after the initial monitoring connection has been established to the port defined by [rmi-client-port](#rmi-client-port)). The registry port must be unique across all the DataSource applications executing on the same physical machine. So, when you implement an Integration Adapter, make sure its `rmi-registry-port` value is different to the settings used by Liberator and Transformer. Alternatively, you can define this port in the DataSource application’s [jvm-options](datasource-java-jvm-configuration.md#jvm-options) configuration, as follows: ``` jvm-options -Drmi.registry.port ``` Only define the port once, using _either_ `rmi-registry-port` _or_ `jvm-options`. In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), [configuration variables](datasource-configuration-syntax.md#configuration-variables) are used to specify `rmi-registry-port` for Liberator and Transformer; for example, `LIBERATOR${THIS_LEG}_JMX_RMI_REGISTRY_PORT`. See [Deployment Framework configuration variables](../deployment-framework/cdf-configuration-macros-and-items.md). **Use in:** C, Java **Syntax:** `rmi-registry-port ` **Type:** integer **Default value:** `-1` (no port defined) ## session-monitoring-interval `session-monitoring-interval` defines the time interval in seconds at which Liberator monitors the state of its sessions. To disable session monitoring, set this item to `-1.0` (the default). **Use in:** C (Liberator only) **Syntax:** `session-monitoring-interval ` **Type:** float **Default value:** `-1.0` --- **See also:** * How Can I... [Configure DataSource monitoring](datasource-configure-datasource-monitoring.md) * [Features and concepts of DataSource monitoring and management](datasource-datasource-monitoring-and-management.md) * [Monitoring and Management in the Caplin Platform](../platform-architecture/monitoring-and-management.md) * [DataSource Configuration Syntax Reference](datasource-configuration-syntax.md) (PDF)