Integrate Apache Tomcat 11 with Prometheus and Grafana monitoring for comprehensive performance tracking

Install required packages

Update your system and install Java 11 or higher, which is required for Tomcat 11.

sudo apt update
sudo apt install -y openjdk-11-jdk wget curl

sudo dnf update -y
sudo dnf install -y java-11-openjdk-devel wget curl

Download and install Apache Tomcat 11

Create a dedicated tomcat user and download the latest Tomcat 11 release.

sudo useradd -r -m -U -d /opt/tomcat -s /bin/false tomcat
cd /tmp
wget https://archive.apache.org/dist/tomcat/tomcat-11/v11.0.0/bin/apache-tomcat-11.0.0.tar.gz
sudo tar xf apache-tomcat-11.0.0.tar.gz -C /opt/tomcat --strip-components=1
sudo chown -R tomcat:tomcat /opt/tomcat
sudo chmod +x /opt/tomcat/bin/*.sh

Download JMX Prometheus Java agent

The JMX Prometheus Java agent exports JVM metrics in Prometheus format via HTTP endpoint.

cd /opt/tomcat/lib
sudo wget https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/0.20.0/jmx_prometheus_javaagent-0.20.0.jar
sudo chown tomcat:tomcat jmx_prometheus_javaagent-0.20.0.jar

Create JMX exporter configuration

Configure which JMX metrics to export and how to transform them for Prometheus.

rules:
  # JVM Memory metrics
  - pattern: 'java.lang<>HeapMemoryUsage'
    name: jvm_memory_heap_bytes
    type: GAUGE
    labels:
      area: "heap"
    help: "Heap memory usage in bytes"
    
  - pattern: 'java.lang<>NonHeapMemoryUsage'
    name: jvm_memory_nonheap_bytes
    type: GAUGE
    labels:
      area: "nonheap"
    help: "Non-heap memory usage in bytes"
    
  # Thread metrics
  - pattern: 'java.lang<>ThreadCount'
    name: jvm_threads_current
    type: GAUGE
    help: "Current thread count"
    
  - pattern: 'java.lang<>PeakThreadCount'
    name: jvm_threads_peak
    type: GAUGE
    help: "Peak thread count"
    
  # Tomcat connector metrics
  - pattern: 'Catalina<>currentThreadCount'
    name: tomcat_threads_current
    type: GAUGE
    labels:
      connector: "$1"
    help: "Current thread count for connector"
    
  - pattern: 'Catalina<>currentThreadsBusy'
    name: tomcat_threads_busy
    type: GAUGE
    labels:
      connector: "$1"
    help: "Current busy thread count for connector"
    
  - pattern: 'Catalina<>maxThreads'
    name: tomcat_threads_max
    type: GAUGE
    labels:
      connector: "$1"
    help: "Maximum thread count for connector"
    
  # Request metrics
  - pattern: 'Catalina<>requestCount'
    name: tomcat_requests_total
    type: COUNTER
    labels:
      connector: "$1"
    help: "Total request count"
    
  - pattern: 'Catalina<>processingTime'
    name: tomcat_processing_time_milliseconds_total
    type: COUNTER
    labels:
      connector: "$1"
    help: "Total processing time in milliseconds"
    
  - pattern: 'Catalina<>bytesReceived'
    name: tomcat_bytes_received_total
    type: COUNTER
    labels:
      connector: "$1"
    help: "Total bytes received"
    
  - pattern: 'Catalina<>bytesSent'
    name: tomcat_bytes_sent_total
    type: COUNTER
    labels:
      connector: "$1"
    help: "Total bytes sent"
    
  # Session metrics
  - pattern: 'Catalina<>activeSessions'
    name: tomcat_sessions_active
    type: GAUGE
    labels:
      host: "$1"
      context: "$2"
    help: "Active session count"
    
  - pattern: 'Catalina<>sessionCounter'
    name: tomcat_sessions_created_total
    type: COUNTER
    labels:
      host: "$1"
      context: "$2"
    help: "Total sessions created"
    
  # Garbage Collection metrics
  - pattern: 'java.lang<>CollectionCount'
    name: jvm_gc_collections_total
    type: COUNTER
    labels:
      gc: "$1"
    help: "Total garbage collections"
    
  - pattern: 'java.lang<>CollectionTime'
    name: jvm_gc_collection_time_milliseconds_total
    type: COUNTER
    labels:
      gc: "$1"
    help: "Total garbage collection time in milliseconds"

sudo chown tomcat:tomcat /opt/tomcat/conf/jmx-exporter-config.yml

Configure Tomcat to use JMX exporter

Add the JMX Prometheus agent to Tomcat's JVM startup options.

#!/bin/bash
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/tomcat/lib/jmx_prometheus_javaagent-0.20.0.jar=8088:/opt/tomcat/conf/jmx-exporter-config.yml"
JAVA_OPTS="$JAVA_OPTS -Xmx2048m -Xms1024m -XX:+UseG1GC"

sudo chown tomcat:tomcat /opt/tomcat/bin/setenv.sh
sudo chmod +x /opt/tomcat/bin/setenv.sh

Create systemd service for Tomcat

Configure Tomcat to start automatically and run as the tomcat user.

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking
User=tomcat
Group=tomcat
Environment=JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"
Environment="JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom"
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

Start Tomcat and verify JMX exporter

Enable and start the Tomcat service, then verify the metrics endpoint is working.

sudo systemctl daemon-reload
sudo systemctl enable --now tomcat
sudo systemctl status tomcat
curl http://localhost:8088/metrics | head -20

Install Prometheus

Download and install Prometheus to scrape metrics from Tomcat.

sudo useradd -r -M -s /bin/false prometheus
sudo mkdir -p /etc/prometheus /var/lib/prometheus
cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v2.48.0/prometheus-2.48.0.linux-amd64.tar.gz
tar xf prometheus-2.48.0.linux-amd64.tar.gz
sudo cp prometheus-2.48.0.linux-amd64/prometheus /usr/local/bin/
sudo cp prometheus-2.48.0.linux-amd64/promtool /usr/local/bin/
sudo chown prometheus:prometheus /usr/local/bin/prometheus /usr/local/bin/promtool
sudo chown -R prometheus:prometheus /etc/prometheus /var/lib/prometheus

Configure Prometheus to scrape Tomcat metrics

Set up Prometheus configuration to collect metrics from the Tomcat JMX exporter.

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - "tomcat_alerts.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets: []

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
  
  - job_name: 'tomcat'
    static_configs:
      - targets: ['localhost:8088']
    scrape_interval: 5s
    metrics_path: '/metrics'
    scrape_timeout: 5s

sudo chown prometheus:prometheus /etc/prometheus/prometheus.yml

Create Prometheus alerting rules

Define alert conditions for Tomcat performance and health monitoring.

groups:
  - name: tomcat_alerts
    rules:
      - alert: TomcatDown
        expr: up{job="tomcat"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Tomcat instance is down"
          description: "Tomcat metrics endpoint has been unreachable for more than 1 minute."
          
      - alert: TomcatHighMemoryUsage
        expr: (jvm_memory_heap_bytes{area="heap"} / jvm_memory_heap_max_bytes{area="heap"}) * 100 > 85
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Tomcat high heap memory usage"
          description: "Tomcat heap memory usage is above 85% for more than 5 minutes. Current usage: {{ $value }}%"
          
      - alert: TomcatHighThreadUsage
        expr: (tomcat_threads_busy / tomcat_threads_max) * 100 > 80
        for: 3m
        labels:
          severity: warning
        annotations:
          summary: "Tomcat high thread pool usage"
          description: "Tomcat thread pool usage is above 80% for connector {{ $labels.connector }}. Current usage: {{ $value }}%"
          
      - alert: TomcatHighResponseTime
        expr: rate(tomcat_processing_time_milliseconds_total[5m]) / rate(tomcat_requests_total[5m]) > 5000
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Tomcat high response time"
          description: "Average response time for connector {{ $labels.connector }} is above 5 seconds: {{ $value }}ms"
          
      - alert: TomcatHighGCTime
        expr: rate(jvm_gc_collection_time_milliseconds_total[5m]) > 100
        for: 3m
        labels:
          severity: warning
        annotations:
          summary: "Tomcat high garbage collection time"
          description: "Garbage collection time rate is high for collector {{ $labels.gc }}: {{ $value }}ms/sec"
          
      - alert: TomcatNoActiveThreads
        expr: tomcat_threads_current - tomcat_threads_busy < 5
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Tomcat low available threads"
          description: "Less than 5 threads available for connector {{ $labels.connector }}"
          
      - alert: TomcatHighErrorRate
        expr: rate(tomcat_servlet_errors_total[5m]) / rate(tomcat_requests_total[5m]) * 100 > 5
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Tomcat high error rate"
          description: "Error rate is above 5% for the last 5 minutes: {{ $value }}%"

sudo chown prometheus:prometheus /etc/prometheus/tomcat_alerts.yml

Create Prometheus systemd service

Configure Prometheus to start automatically on system boot.

[Unit]
Description=Prometheus
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
  --config.file /etc/prometheus/prometheus.yml \
  --storage.tsdb.path /var/lib/prometheus/ \
  --web.console.templates=/etc/prometheus/consoles \
  --web.console.libraries=/etc/prometheus/console_libraries \
  --web.listen-address=0.0.0.0:9090 \
  --web.enable-lifecycle
Restart=always

[Install]
WantedBy=multi-user.target

Start Prometheus service

Enable and start Prometheus, then verify it's collecting Tomcat metrics.

sudo systemctl daemon-reload
sudo systemctl enable --now prometheus
sudo systemctl status prometheus

Install Grafana

Add Grafana repository and install the latest version for dashboard visualization.

sudo apt install -y software-properties-common
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install -y grafana

sudo tee /etc/yum.repos.d/grafana.repo <