Publishing JMX metrics

Here are some examples of how to configure a DataSource application so that users can monitor its state through a JMX monitoring client, such as the Caplin Management Console. Monitoring configuration applies to all DataSource applications, such as Liberator, Transformer and Integration Adapters.

Want some background to all this first? See Features and concepts of DataSource monitoring and management. And for detailed information about all the monitoring configuration items, refer to the Reference documentation: DataSource monitoring configuration.

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

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

For more information on the term 'peer', see DataSource Overview.

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: