In this article, we will explore how to set up Prometheus for data collection, configure Grafana for visualization, and establish alerting mechanisms to proactively monitor system health and performance of Universal Messaging.
In Universal Messaging Docker images version 10.15 and higher, monitoring using Prometheus is enabled by default
Applicable Versions: UM 10.15 and later
Overview
Monitoring is a critical aspect of managing enterprise messaging systems. IBM’s Universal Messaging (UM) server provides Java Management Extensions (JMX) beans that allow administrators to monitor and manage server resources. These JMX beans expose valuable metrics, but leveraging them effectively requires the right tools. The Universal Messaging server exposes a number of Java Management Extensions (JMX) beans for management and monitoring of server resources. The beans available for monitoring depend on the functionality that is enabled on the server.
For basic monitoring, you can also use JConsole, a Java-based tool that connects to the Universal Messaging JMX interface. However, when dealing with large-scale deployments, Prometheus provides a more scalable and automated approach to JMX monitoring.
Prometheus, an open-source monitoring system, offers a component called JMX Exporter that simplifies JMX data collection. Instead of manually configuring Remote Method Invocation (RMI) for monitoring, you can use the JMX Exporter Java agent to automatically extract relevant metrics from Universal Messaging.
The JMX Exporter is included in the Universal Messaging product delivery as the jar file jmx_prometheus_javaagent.jar. You can run the JMX Exporter as a Java аgent to export a set of Universal Messaging time series data that can be analyzed by Prometheus.
Installation and setup
To enable the JMX Exporter agent
1. Open the <installation_directory>\UniversalMessaging\server\instance_name\bin\Server_Common.conf file in a text editor and search for the line referring to the JMX Exporter agent. The line looks similar to this:
wrapper.java.additional.<n>=
-javaagent:<installation_directory>\UniversalMessaging\lib\jmx_prometheus_javaagent.jar=0.0.0.0:9200:
<installation_directory>\UniversalMessaging\server\instance_name\bin\jmx_sag_um_exporter.yaml
2. Uncomment the line.
3. Optionally, change the port number from the default 9200.
4. Restart the Universal Messaging realm instance.
Install and SetUp Prometheus locally
For Windows:
Go to the official Prometheus download page: https://prometheus.io/download/
Extract the ZIP file to a directory of your choice (e.g., C:\Prometheus\).
For Mac:
brew install prometheus
Locate the Extracted Folder:
If you installed Prometheus via Homebrew, the default location is:
/usr/local/etc/prometheus/prometheus.yml
If you downloaded Prometheus manually, the configuration file is in the extracted folder:
C:\path\to\prometheus\prometheus.yml
Edit the Configuration File and Save:
global:
scrape_interval: 15s
scrape_configs:
- job_name: "prometheus"
static_configs:
- targets: ["localhost:9200"]
[This is the same port on which UM Prometheus server is started. The Default port in UM is given as 9200.]
Run Prometheus:
For Windows:
cd C:\Prometheus
prometheus.exe --config.file=prometheus.yml
For Mac:
./prometheus --config.file=prometheus.yml
Open a browser and go to: http://localhost:9090/query.
You should see the Prometheus UI.
Under the Status tab, select Target Health. It will display the status of the target URL updated in the prometheus.yml.
If UM server is running, it should show green.
Install and Setup Grafana locally
Navigate to https://grafana.com/grafana/download and download the zip or Windows installer.
Start Grafana by executing grafana-server.exe, located in the bin directory.
For mac:
brew install grafana
brew services start Grafana
Open http://localhost:3000 in your browser.
Default login: Username: admin Password: admin (You’ll be prompted to change it).
Add Prometheus as Data Source
Go to "Connections" → "Data sources".
Click "Add new data source".
Select Prometheus.
In the URL field, enter: http://localhost:9090
Click "Save & Test"Add Create Grafana Dashboard -
Go to "Dashboards" → "New Dashboard".
Click Add Visualization
Select Data Source as Prometheus
Under Queries, Select UM metrics.
Usage Notes on Health Monitoring with Prometheus
The following sections contain usage notes on key metrics that you can use to monitor the health of a Universal Messaging server in Prometheus.
You can set the thresholds and percentage limits of these metrics. Note that the thresholds and limits are guidelines and the values might differ depending on your specific use case and requirements.
Server Metrics
sag_um_server_cpu_usage_ratio
sag_um_server_memory_heap_usage_bytes
sag_um_server_memory_heap_free_bytes
sag_um_server_memory_heap_max_bytes.
sag_um_server_memory_direct_usage_bytes
sag_um_server_memory_direct_max_bytes
sag_um_server_memory_direct_free_bytes
sag_um_server_memory_direct_max_bytes.
sag_um_server_disk_usage_bytes
sag_um_server_disk_total_bytes
sag_um_server_disk_free_bytes
sag_um_server_disk_total_bytes.
sag_um_server_currentconnections
sag_um_server_bytesin_bytes_total
sag_um_server_bytesout_bytes_total
Cluster Metrics
sag_um_cluster_processqueue
sag_um_cluster_clientqueue
sag_um_cluster_commsqueue
sag_um_cluster_currentstate
Thread Metrics
sag_um_threadpool_queued_tasks
sag_um_threadpool_stalled_tasks
Topic Metrics
sag_um_topic_noofevents
sag_um_topic_memory_usage_bytes
sag_um_topic_disk_usage_bytes
sag_um_topic_durable_outstanding
sag_um_topic_durable_pending
Queue Metrics
sag_um_queue_events
sag_um_queue_memory_usage_bytes
sag_um_queue_disk_usage_bytes
Example Grafana Dashboard
Enable HTTPS SSL Connection in JMX Exporter for UM
To secure the JMX Exporter with HTTPS/SSL, you need to configure the exporter to use a valid keystore. This ensures encrypted communication between clients and the Universal Messaging (UM) server.
To generate the java keystore files, please refer "Client SSL Configuration" in Universal Messaging Documentation.
This guide will walk you through the steps to enable SSL for JMX Exporter by modifying its configuration file.
Navigate to the JMX Exporter YAML configuration file, typically found in:
<Installation Directory>/UniversalMessaging/server/umserver/bin/jmx_sag_um_exporter.yaml
Open the jmx_sag_um_exporter.yaml file and add the following SSL settings:
httpServer:
ssl:
keyStore:
filename: <Installation Directory> /UniversalMessaging/server/umserver/bin/<certificate>.jks"
password: <keystore password>
certificate:
alias: <keystore alias>
After saving the above configuration in jmx_sag_um_exporter.yaml file, we need to update the scheme in prometheus.yaml file as well.
In the prometheus.yaml file update the scheme value as -
global:
scrape_interval: 15s
scrape_configs:
- job_name: "prometheus"
scheme: https
static_configs:
- targets: ["localhost:9200"]
If the target uses self-signed certificates, you may need to disable TLS verification by adding:
tls_config:
insecure_skip_verify: true
After updating the configuration, restart the Universal Messaging server and premetheus server to apply the changes.
Once the servers are running, verify that JMX Exporter is accessible over HTTPS: https://localhost:9200/metrics
Health Monitoring and Setting Alerts
Setting up alerts and email notifications ensures timely responses to critical issues, preventing downtime and improving system reliability.
Setting Up Alerts in Grafana
Alerts help you monitor key system metrics and get notified when thresholds are breached.
Define an Alert Rule:
Open your dashboard and click on the panel settings.
Select the Alert tab and click Create Alert.
Define alert conditions (e.g., CPU usage > 80%).
Set the evaluation frequency (e.g., every 1 minute).
Click Save.
Configure Notification Channels:
Go to Alerting → Notification Channels.
Click Add Channel.
Choose a notification method (Email, Slack, Teams, etc.).
Configure recipient details and alert message format.
Click Save Channel.
Setting Up Email Alerts
To receive alerts via email, you must configure an SMTP server in Grafana.
Update Grafana SMTP Settings:
Edit the grafana.ini file located in /etc/grafana/grafana.ini.
Add the following SMTP configuration:
[smtp]
enabled = true
host = smtp.example.com:587
user = your-email@example.com
password = your-password
from_address = grafana@example.com
Restart Grafana
Configure Alert Notifications:
Navigate to Alerting → Notification Channels.
Select Email as the notification type.
Add recipient email addresses.
Click Save.
Choosing the Right Scale/Unit for Grafana Charts: Best Practices
Choosing the right scale and unit for metrics in Grafana charts ensures accurate visualization and meaningful insights. Here’s how you can choose or update the scale and units effectively:
1. Choose the Right Scale Type
Linear Scale: Default for most cases; use it for evenly spaced values.
Logarithmic Scale: Suitable for large variations in values (e.g., network latency, error rates).
To enable:
Open Panel Settings → Axes & Grid → Set Scale type to Logarithmic.
2. Adjust Unit Format
Setting the correct unit helps Grafana auto-scale values (e.g., bytes, milliseconds, requests/sec).
Open Panel Settings → Field Tab.
Set the unit under the "Standard Options" section:
Bytes → Gigabytes (GB): Select bytes (IEC) or gigabytes (GB).
Bytes → Megabytes (MB): Select megabytes (MB).
In Unit, choose the most appropriate unit (e.g., "bytes", "requests per second", "CPU %").
Grafana automatically adjusts the values and scale accordingly.
For example:
sag_um_server_disk_total_bytes represents the total disk space in bytes. Converting it to gigabytes (GB) improves readability.
Similarly, sag_um_server_memory_direct_usage_bytes indicates the amount of direct memory used by the server in bytes. Displaying it in megabytes (MB) makes the data easier to interpret.
Summary
This article barely scratched the surface of monitoring Universal Messaging with Prometheus and Grafana. By integrating JMX Exporter with Prometheus and Grafana, Universal Messaging users can efficiently monitor server health, track performance trends, and set up proactive alerts. This approach eliminates the need for complex RMI configurations while leveraging modern cloud-native monitoring solutions.
Documentation References
https://docs.webmethods.io/on-premises/webmethods-universal-messaging/en/11.1.0/webhelp/index.html#page/num-webhelp%2Fco-ops_using_prometheus.html
#Spotlight#community-stories1
