Welcome to our docs site. Docs on this site are for ACP version 9.
See these links for previous versions: Version 8, Version 7

Configure JMX Monitoring

The Platform supports Static JMX Connection strings for monitoring your Java Applications. By leveraging a proxy and monitoring service, all instances of a Java Web Application components can be monitored by using a single Static JMX Connection string, username and password. This document describes the basic Platform and application configuration needed to implement Static JMX Connections. 

About Static JMX Connections

Due to the nature of the Platform, application components have the potential to be hosted on any applicable server at any time. A highly scaling application, for example, will have workloads added and removed from the Platform constantly. By default, the Platform is configured to generate a JMX Connection string for each workload of a JMX enabled application component deployed on the Platform. This default JMX Connection string is specific to the workload it is connected to, meaning that if the workload moves on the Platform, the connection information will change to reflect the new location. Static JMX Connections, however, allow your monitoring client to retrieve the monitoring information from all application component workloads independent of the workload’s movement on the Platform. The proxy and monitoring extension service work together to manage workload locations and retrieve JMX Monitoring Subscriptions properties at the configured rates. It should be noted that the default JMX Connections strings will still be available for monitoring a specific workload instance of an application component when Static JMX Connections are enabled.

Platform Configurations for a JMX Proxy

Some Platform configurations need to be made by the Platform Operator to accommodate the addition of Static JMX Connections. The following two Platform Registry Settings should be added by your Platform Operator.

Name Explanation Values
Apprenda.Security.SocApiAuthorizationToken Token to be used by JMX Proxy to gain access to the SOC and gather information about application workloads string
Deployment.MonitoringExtService Location of an application the Platform should use as a Monitoring Extension Service monitoringAppAlias/MonitoringExtensionService

The Apprenda.Security.SocApiAuthorizationToken is a token that will be used by the JMX Proxy to connect to the SOC and gather information about application workloads. For increased security, this setting must be encrypted upon creation. Additionally, once Apprenda.Security.SocApiAuthorizationToken is set it will only be visible in the Platform Registry database and will not appear in the list of Platform Registry Settings in the SOC. If you need to reset the token value, overwrite the current value by adding the Platform Registry Setting again.

Deployment.MonitoringExtService informs the Platform of the application that should be used as a Monitoring Extension Service. The value for this setting must be a string consisting of the monitoringAppAlias/MonitoringExtensionService where monitoringAppAlias is the alias of the application of the Monitoring Extension Service.

Configuring the JMX Proxy

To have Static JMX Connections, you will need to configure a proxy to manage the Platform locations of the application workloads being monitored. An example JMX Proxy application can be found on the Downloads page.

Configuring the application.conf File

The following are configuration options that can be set in the application.conf file of the JMX Proxy.

Configuration Settings

Platform Settings
platformUrl URL of the Platform
useHttps Determined if the proxy should use HTTPS for connections, true/false
socAuthToken Authentication token used to access application workload. Should match value set as the Apprenda.Security.SocApiAuthorizationToken
requestTimeoutSeconds The timeout (in seconds) for requests to the Platform
maxRedirectCount The max number of HTTP redirects to follow
Proxy Settings
exposedFqdn FQDN that will be used in the Static JMX Connection string. If not set, the proxy will programmatically detect the FQDN. In a HA solution, this must be set to the load balancer of the proxy
minPort Minimum port number to be used by the proxy
maxPort Maximum port number to be used by the proxy
updateFrequency The amount of time (in minutes) the proxy checks for configuration updates
updateTimeout The amount for time (in seconds) the proxy waits for an update check before a timeout
Database Settings
connString Connection string to be used by the proxy to access the database
user Username of the database
password Password of the database

Example application.conf file

#
# JMX Proxy Configuration
#
#
#NOTE:  Triple double quotes (""") are used to wrap strings to ensure that the they are
#       handled as raw strings.  Without them, certain characters (like '\') may cause problems
#       when the configuration file is parsed.

#Platform settings
apprenda {
  platformUrl = """apps.apprenda.harp"""
  useHttps = true                        
  socAuthToken = """token"""              
  requestTimeoutSeconds = 20             
  maxRedirectCount=5                      
}

#Proxy settings
proxy {
  # exposedFqdn = FQDN                    
  # Optional. FQDN that will be used in the JMX connection string.
  # If not set, the proxy will programmatically detect the FQDN.
  # This setting is required if you need a HA solution. It should be set to the FQDN of the proxy load balancer

  # Port range allocated to the proxy.  Range size is dependent on the number of
  # distinct components to be monitored.  Where n components are to be monitored,
  # at least n + 1 ports are required.
  minPort = 17600
  maxPort = 17700

  updateFrequency = 1m                    
  updateTimeout = 30s                     

#DB Connection settings
db {
  connString = """jdbc:sqlserver://serverName; databaseName=databaseName"""             
  user = """databaseUsername"""          
  password = """databasePassword"""      
}
 

 

Deploying the Monitoring Service and JMX Proxy

Note: All example applications can be found on the Downloads page.

You can deploy the Monitoring Service Extension and JMX Proxy as a single application on the Platform. The JMX Proxy and Monitoring Service Extension Apprenda Archive from the Downloads page is a useable example of how the the JMX Proxy Linux Service and Monitoring Service Extension can be packed into a single Apprenda Archive. Once the JMX Proxy has been configured as noted in the previous section, the archive can be uploaded to the Platform by a Developer.

HA off Platform Solution

If you need a HA solution for Static JMX Connections, the Monitoring Service Extension and JMX Proxy should be deployed separately. The Monitoring Service Extension should be deployed as a WCF Service application on the Platform (Monitoring Extension Service Apprenda Archive example) and the JMX Proxy configured and started on all off Platform Linux machines you wish to use (Stand-alone Proxy example). For this solution you will need to set the exposedFqdn to the FQDN of the proxy and set the port range in the application.conf file for each JMX Proxy.

In both the on and off-Platform solutions, the JMX Proxy and Monitoring Service Extension use a MS SQL Server database. Additionally the portion of the solution hosted on the Platform will need to be in the Published state of the Application Lifecycle in order to establish Static JMX Connections and begin fulfilling Monitoring Subscriptions. The applications being monitored, however, can be in either the Sandbox or Published state.

To ensure the best monitoring performance regardless of the solution employed, it is recommended that the JMX Proxy be placed on a high performing server and that only necessary properties be set in Monitoring Subscriptions at reasonable refresh rates.