Skip to main content

Prometheus (JMX Exporter) Integration

This guide explains how to integrate Prometheus with MAPS Messaging using the JMX Exporter.

1) Mapping file: prometheus.yml​

Create $MAPS_HOME/conf/prometheus.yml with:

startDelaySeconds: 0
ssl: false
lowercaseOutputName: true
lowercaseOutputLabelNames: true
rules:
  - pattern: io\.mapsmessaging<type=Broker,.*destinationName=([^,]+),\s*destinationType=([^,>]+).*><>(published|delivered|stored|retrieved|expired|delayed|noInterest|subscribed|subscribedClients|pendingTransaction|transacted)
    name: maps_destination_$3
    type: GAUGE
    labels:
      destination: $1
      destination_type: $2
  - pattern: io\.mapsmessaging<type=Broker,.*endPointManagerName=([^,>]+).*><>(Connected|Protocols|Packets
      Read|Packets Sent|Bytes Read|Bytes Sent)
    name: maps_endpoint_manager_$2
    type: GAUGE
    labels:
      manager: $1
  - pattern: io\.mapsmessaging<type=Broker,.*endPointManagerName=([^,]+),\s*endPointName=([^,>]+).*><>(Bytes
      Read|Bytes(?:\s+|_)Sent|Total Underflow|Total Overflow|Last Read|Last Write)
    name: maps_endpoint_$3
    type: GAUGE
    labels:
      manager: $1
      endpoint: $2
  - pattern: io\.mapsmessaging<type=Broker,.*name=([^,>]+).*><>(Maximum outstanding|Total
      Tasks Queued|Outstanding Tasks|Thread offload count)
    name: maps_taskqueue_$2
    type: GAUGE
    labels:
      queue: $1
  - pattern: io\.mapsmessaging<type=Broker,.*service=Health.*><>(currentStatus)
    name: maps_health_status
    type: GAUGE

2) Enable JMX in MessageDaemon.yaml​

Ensure JMX is enabled:

MessageDaemon:
  EnableJMX: true
  EnableJMXStatistics: true

3) Download the JMX Exporter agent JAR​

Download and place under $MAPS_HOME/lib:

mkdir -p "$MAPS_HOME/lib"
curl -L -o "$MAPS_HOME/lib/jmx_prometheus_javaagent.jar"   https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/1.0.1/jmx_prometheus_javaagent-1.0.1.jar

4) Wire the agent in start.sh​

Add before the while true; do loop:

# --- Prometheus JMX Exporter ---
export PROM_JMX_PORT="${PROM_JMX_PORT:-9404}"
export PROM_JMX_JAR="${PROM_JMX_JAR:-$MAPS_HOME/lib/jmx_prometheus_javaagent.jar}"
export PROM_JMX_CONFIG="${PROM_JMX_CONFIG:-$MAPS_HOME/conf/prometheus.yml}"

export JAVA_OPTS="$JAVA_OPTS -javaagent:${PROM_JMX_JAR}=${PROM_JMX_PORT}:${PROM_JMX_CONFIG}"

5) Verify without Prometheus​

Linux/macOS​

curl -sI http://localhost:9404/metrics | grep -i content-type
curl -s http://localhost:9404/metrics | grep -E '^maps_|^# (HELP|TYPE)' | head

Windows (PowerShell)​

Test-NetConnection localhost -Port 9404
(Invoke-WebRequest http://localhost:9404/metrics -Method Head).Headers['Content-Type']
(Invoke-WebRequest http://localhost:9404/metrics).Content | Select-String '^maps_' | Select-Object -First 20

6) Prometheus scrape example​

scrape_configs:
  - job_name: 'maps-messaging-jmx'
    scrape_interval: 15s
    static_configs:
      - targets: ['maps.example.com:9404']

Only expose port 9404 to trusted networks (or front with your existing proxy/TLS).

7) Troubleshooting​

  • Exporter starts but no maps_ metrics: Attribute names/spacing differ. Check via /jolokia/read and adjust patterns.
  • Regex error about ${3}: Use $3 (not ${3}) in name:.
  • High series count: Reduce rules; avoid per-client/topic dimensions.