# Publishing JMX metrics

Here are some examples of how to configure a DataSource application so that users can monitor its state through a [JMX](https://www.oracle.com/java/technologies/javase/javamanagement.html) monitoring client, such as the [Caplin Management Console](../cmc/index.md). Monitoring configuration applies 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).

Want some background to all this first? See [Features and concepts of DataSource monitoring and management](datasource-datasource-monitoring-and-management.md). And for detailed information about all the monitoring configuration items, refer to the Reference documentation: [DataSource monitoring configuration](datasource-datasource-monitoring-configuration-part-1.md).

**📌 NOTE**\
One other thing you need to know before looking at the examples: in DataSource applications built with the current (version 6.1) releases of the DataSource APIs ([Caplin Integration Suite](../cis/index.md), C DataSource API), all monitoring users can read all MBean attributes, though they can’t write to them. So there’s no configuration that controls access to attributes.

## Example 1: Basic monitoring configuration

Here’s an example of some basic monitoring configuration for an Integration Adapter.

You’d add the configuration to the Adapter blade’s configuration file _<Deployment-framework-root>/kits/<blade_name>/DataSource/etc/datasource.conf_

```
monitor-module jmx
monitor-moddir %r/DataSource/lib
process-usage-period 20
log-monitor-level NOTIFY
```

* `monitor-module jmx` specifies that the JMX monitoring module is to be loaded into the Integration Adapter. Without this line, JMX monitoring is disabled.
* `monitor-moddir` defines the directory where the DataSource application’s JMX monitoring module is located. The %r marker causes the Deployment Framework to prefix the directory with the root directory of the Adapter installation; for example forming the directory _/MyAdapterBlade/DataSource/lib_
* `process-usage-period` defines the time interval in seconds at which the Adapter’s CPU time counters `user-cputime-total` and `system-cputime-total` are updated. These counters can be viewed through JMX monitoring. Here the time interval’s been doubled to 20 seconds (the default is 10 seconds) to reduce the amount of data transmitted to the monitoring client.
* `log-monitor-level` specifies the threshold at which log messages about the Adapter’s events and errors are published to the monitoring subsystem, to be viewed by a monitoring client. Here we’ve set the level to `NOTIFY`, which is a lower threshold than the default setting of `INFO` and so reduces the amount of data transmitted to the monitoring client.

## Example 2: Adding monitoring users and roles

Taking the configuration of [Example 1](#example-1-basic-monitoring-configuration), we need to the add some user credentials that will allow designated users to monitor the Adapter through a monitoring client. Here we add two users:

* User `admin`, with a secure (encrypted) password, `adminpass`, can read the attributes of the Adapter’s MBeans and invoke any operation on any MBean.
* User `guest`, with a non-secure password, `guestpass`, can only read the attributes of the Adapter’s MBeans, and can’t invoke any operations.

The additional configuration looks like this:

```
...
add-monuser
   user        admin
   secure-pass $apr1$twr9ykne$grsfePTtmxi76iD3iUF651
   roles       adminrole
end-monuser

add-monuser
   user  guest
   pass  guestpass
   roles guestrole
end-monuser

mon-operation-default adminrole
```

* The first `add-monuser` configuration item defines the `admin` user’s user name (`user admin`), the [APR1](https://httpd.apache.org/docs/current/misc/password_encryptions.html) encrypted password (`secure-pass $apr1$twr...`), and a role for the user (`roles adminrole`) that determines the `admin` user’s access permissions to the Adapter’s MBeans.
* The second `add-monuser` item defines the same set of things for the `guest` user, but this time the password definition isn’t encrypted (`pass guestpass`), and the user has a different role (`roles guestrole`), because they are to be given different permissions.
* The default permission setting for MBean operations is that a user role is barred from invoking an operation unless it’s explicitly given permission. The `mon-operation-default` configuration item overrides this default for users with the role `adminrole`, so the `admin` user, who has this role, can invoke any operations on any of the Adapter’s MBeans. The `guest` user doesn’t have the `adminrole`, so (by default) can’t invoke any operations on any MBeans; `guest` can only read the MBean attributes.

## Example 3: Granting extra access permissions

Now we expand [Example 2](#example-2-adding-monitoring-users-and-roles) to allow the `guest` user to invoke any operations on a specific MBean.

Assume the Adapter has an MBean with Object Name `myadapter.server.peerstats:identifier=0` and this bean has the operations `reset-counters` and `set-monitoring-interval`. To enable the `guest` user to invoke any of these operations on just this particular bean, add an `**add-mon-roles**` configuration item that includes the `operation-default` option.

```
...
mon-operation-default adminrole

add-mon-roles
   beanname  myadapter.server.peerstats:identifier=0
   operation-default adminrole,guestrole
end-mon-roles
```

* Within the `add-mon-roles` item, the `beanname` option specifies the MBean that we want to give the extra permissions to.
* The option `operation-default` specifies the role `guestrole`, so this role (and hence the `guest` user) can invoke all the operations on this MBean.
* Why does `adminrole` appear in the `operation-default` option as well?

  This is because the permissions granted in the various configuration items are not additive, and in this case, the `operation-default` option overrides the `mon-operation-default` item. So although the `mon-operation-default` setting grants `adminrole` the ability to invoke any operation on any MBean, if we just used `operation-default guestrole`, the absence of `adminrole` in this option would by default prevent `adminrole` from invoking operations on the specified MBean. Adding `adminrole` to the ``operation-default`’s role list preserves that role’s access permissions for the MBean operations.

  If you subsequently added another role to `mon-operation-default`, you’d also have to add it to the `operation-default` option in the `add-mon-roles` item so that the new role could invoke all operations on the MBean.

  For more information on the precedence rules for `mon-operation-default`, `operation-default`, and `operation`, see the documentation for [`mon-operation-default`](datasource-datasource-monitoring-configuration-part-1.md#mon-operation-default).

**📌 NOTE**\
Do not include spaces in the comma-separated list of roles. Write `adminrole,guestrole` _not_ `adminrole, guestrole`.

## Example 4: Reducing access permissions

Starting from [Example 3](#example-3-granting-extra-access-permissions), we’ll restrict ``guestrole`’s access to the operations on the MBean with Object Name `myadapter.server.peerstats:identifier=0`

Now we only want `guestrole` to be able to invoke this MBean’s `reset-counters` operation, and we want to deny it access to the `set-monitoring-interval` operation.

The configuration you need looks like this:

```
...
mon-operation-default adminrole

add-mon-roles
   beanname  myadapter.server.peerstats:identifier=0
   operation reset-counters adminrole,guestrole
end-mon-roles
```

* The new `operation` option explicitly grants `guestrole` permission to invoke the MBeans’s `reset-counters` operation.
* We’ve removed the `operation-default` option, so `guestrole` can’t invoke any other operations on the MBean.
* Why does `adminrole` appear in the `operation` option too?

  For the same reason we put it in the `operation-default` option in [Example 3](#example-3-granting-extra-access-permissions) - the `operation` option overrides the `mon-operation` option and therefore we have to explicitly include `adminrole` in the `operation` option so it can continue to invoke `reset-counters` on the MBean as well as `guestrole`.

## Example 5: Restricting developers' access to MBean operations

In this example, we have a Liberator, Transformer and two Integration Adapters (A and B). The Liberator has some MBeans in the domain `rttpd.server.peers:` that allow users monitoring the Liberator to invoke operations affecting the connections to the Transformer and the Integration Adapters.

The MBeans in the domain `rttpd.server.peers:` are

* `rttpd.server.peers:peer-number=0` (MBean relating to connections to the Transformer)
* `rttpd.server.peers:peer-number=1` (MBean relating to connections to IntegrationAdapter A)
* `rttpd.server.peers:peer-number=2` (MBean relating to connections to IntegrationAdapter B)

There are three roles:

* `adminRole` can invoke any operations on the Liberator MBeans.
* `peerManagerRole` can invoke operations only on the MBeans in the domain `rttpd.server.peers:`
* `devRole` is for developers who are working on IntegrationAdapterA; they can invoke only certain operations on the MBeans relating to the connection to IntegrationAdapterA.

**📌 NOTE**\
For more information on the term 'peer', see [DataSource Overview](index.md).

**Here’s the Liberator’s monitoring configuration for `adminRole` and `peerManagerRole`:**

You’d normally add the configuration to the **jmx.conf** file in the Deployment Framework’s overrides file for the Liberator: _<Deployment-framework-root>/global_config/overrides/servers\Liberator/etc/jmx.conf_

We allow the `adminRole` to invoke operations on all the Liberator’s MBeans, and the `peerManager` role to invoke operations only on the MBeans that are in the domain `rttpd.server.peers`:

```
mon-operation-default adminRole

add-mon-roles
   beanname rttpd.server.peers:
   operation-default adminRole,peerManagerRole
end-mon-roles
```

As in the previous examples, we’ve had to add `adminRole` to the role list in the `operation-default` option so that this role can continue to invoke operations on the MBeans in the domain `rttpd.server.peers:` (`operation-default` overrides `mon-operation-default` for these MBeans).

**Adding permissions for developers**

So far, users with role `devRole` only have read access to the `rttpd.server.peers:` MBeans. Now say IntegrationAdapterA is under development, whereas IntegrationAdapterB and the Liberator and Transformer aren’t. We want developer users to be able to invoke the MBean operations called `set-up` and `set-down` relating to IntegrationAdapter A, for testing purposes. The `set-down` operation makes the Liberator disconnect from the Integration Adapter, and `set-up` makes it reconnect. We don’t want developer users to be able to invoke these operations on the connections to the other Adapter or the Transformer.

We add the following configuration to the Liberator:

```
add-mon-roles
   # MBean relating to the DataSource peer IntegrationAdapterA
   beanname rttpd.server.peers:peer-number=1
   operation set-up adminRole,peerManagerRole,devRole
   operation set-down adminRole,peerManagerRole,devRole
end-mon-roles
```

* We’ve explicitly identified the Liberator MBean relating to IntegrationAdapterA

  (`beanname rttpd.server.peers:peer-number=1`)
* The `operation` options allow `devRole` to invoke the MBean’s `set-up` and `set-down` operations, but `devRole` can’t invoke any other operations on this MBean or on any other MBeans.
* As in the previous examples, we’ve added `adminRole` and `peerManagerRole` to the role lists in the `operation` options, so they can continue to invoke the `set-up` and `set-down` operations on the MBean.

---

**See also:**

* [Monitoring and Management in the Caplin Platform](../platform-architecture/monitoring-and-management.md)
* [Features and concepts of DataSource monitoring and management](datasource-datasource-monitoring-and-management.md)
* **Reference:** [DataSource monitoring configuration](datasource-datasource-monitoring-configuration-part-1.md)
* [DataSource Configuration Syntax Reference](datasource-configuration-syntax.md) (PDF)
* [ITRS Geneos: Monitoring Caplin](https://www.itrsgroup.com/products/geneos/integrations-and-plugins/monitoring-caplin)