tutorial

Monitoring Drools with Vigilmon

Drools is Red Hat's open source business rules engine (BRMS) — here's how to monitor KIE Server rule session health, rule execution throughput and latency, working memory size, DMN decision services, Business Central, KJAR deployments, and JVM health with Vigilmon.

Drools is Red Hat's open source Business Rules Management System (BRMS), implementing the PHREAK algorithm for fast declarative rule evaluation. When you self-host Drools, you're running the KIE Server (the lightweight REST runtime for rule sessions), optionally Business Central (the web authoring environment), and the JVM processes that host stateful or stateless rule sessions. Drools powers real-time decisions — insurance eligibility checks, fraud scoring, pricing rules, compliance validation — and a silent failure in the rule engine can mean decisions are silently skipped or defaulting to wrong values. Vigilmon gives you complete observability across the Drools operational stack.

What You'll Set Up

  • KIE Server health monitor with rule session success rate
  • Rule execution throughput monitor
  • Rule execution latency (p99) monitor
  • Working memory size monitor for stateful sessions
  • DMN decision service latency monitor
  • Business Central availability monitor
  • KJAR container deployment health check
  • CEP event stream processing lag monitor
  • JVM heap and GC health monitor
  • Rule conflict and error rate monitor

Prerequisites

  • Drools 7.x or Red Hat Decision Manager deployed with KIE Server
  • KIE Server accessible on its REST port (default 8080)
  • Business Central accessible (default 8080 on the same or separate host)
  • A free Vigilmon account

Step 1: Monitor KIE Server Health

KIE Server is the execution runtime for all Drools rule sessions. When KIE Server is down, every upstream application that calls it for rule evaluation receives an error — decisions either fail open or fail closed depending on your client error handling, neither of which is acceptable in production.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: http://your-kie-server:8080/kie-server/services/rest/server
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Keyword check, enter "status":"UP" to verify KIE Server reports itself operational.
  7. Click Save.

The /kie-server/services/rest/server info endpoint lists server version, capabilities (RULE, PROCESS, PLANNING), and overall status. A 500 means KIE Server failed to initialize its container context; a timeout means Tomcat is running but the KIE Server webapp is hung.

For rule-session-specific health, add a lightweight probe that exercises the actual rule evaluation path:

// Health probe: execute a trivial stateless rule session
@ReadOperation
public Health ruleSessionHealth() {
    try {
        KieServicesClient client = KieServicesFactory.newKieServicesClient(config);
        RuleServicesClient ruleClient = client.getServicesClient(RuleServicesClient.class);
        ServiceResponse<ExecutionResults> response = ruleClient.executeCommandsWithResults(
            containerId, new BatchExecutionCommandImpl(Collections.emptyList())
        );
        return response.getType() == KieServiceResponse.ResponseType.SUCCESS
            ? Health.up().build()
            : Health.down().withDetail("error", response.getMsg()).build();
    } catch (Exception e) {
        return Health.down().withException(e).build();
    }
}

Step 2: Monitor Rule Execution Throughput

Rule execution throughput — rules fired per second — is your primary signal of Drools engine health and capacity. A throughput drop can mean: client requests are failing before reaching KIE Server, a KJAR was redeployed and sessions are being rebuilt, or the KIE Server thread pool is saturated under load.

Expose throughput metrics via Micrometer:

// Instrument every KIE Server rule execution request
@Around("execution(* org.kie.server.api.marshalling.MarshallerFactory.*(..))")
public Object trackRuleExecution(ProceedingJoinPoint pjp) throws Throwable {
    long start = System.nanoTime();
    try {
        Object result = pjp.proceed();
        long rulesFireCount = extractRulesFired(result);
        
        meterRegistry.counter("drools.rules.fired.total",
            "container", currentContainerId).increment(rulesFireCount);
        meterRegistry.timer("drools.execution.duration").record(
            System.nanoTime() - start, TimeUnit.NANOSECONDS);
        
        return result;
    } catch (Exception e) {
        meterRegistry.counter("drools.execution.errors").increment();
        throw e;
    }
}

Expose a health endpoint that checks rolling throughput:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/droolsThroughput
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 2 minutes
  6. Click Save.

Step 3: Monitor Rule Execution Latency

Low rule execution latency is critical when Drools is in the hot path of a user-facing request — a pricing API, an eligibility check, a fraud scoring call. A p99 latency spike means 1% of your decisions are slow, which may be within acceptable limits for batch processing but catastrophic for real-time user flows.

Track latency percentiles in your application metrics:

// Timer with percentiles
Timer.builder("drools.rule.execution.time")
    .tag("container", containerId)
    .publishPercentiles(0.5, 0.95, 0.99)
    .publishPercentileHistogram()
    .register(meterRegistry);

Expose a latency health indicator:

@ReadOperation
public Health latencyHealth() {
    double p99ms = meterRegistry.get("drools.rule.execution.time")
        .percentile(0.99).value() / 1_000_000; // ns to ms
    
    if (p99ms > 500) { // 500ms SLA threshold
        return Health.down()
            .withDetail("p99LatencyMs", p99ms)
            .withDetail("slaThresholdMs", 500)
            .build();
    }
    return Health.up().withDetail("p99LatencyMs", p99ms).build();
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/droolsLatency
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Step 4: Monitor Working Memory Size

Stateful Drools rule sessions maintain a working memory — a collection of Java facts that the PHREAK network evaluates against rule conditions. When working memory grows unbounded (typically due to sessions not being disposed after use), memory pressure builds until the JVM runs out of heap and crashes.

Track working memory object counts:

// KieSession working memory monitoring
KieSession session = kieContainer.newKieSession();
// ... execute rules ...

int factCount = (int) session.getFactCount();
meterRegistry.gauge("drools.working.memory.facts", 
    Tags.of("session", sessionId), factCount);

// Alert if session is not disposed: fact count grows without bound
if (factCount > MAX_EXPECTED_FACTS) {
    log.warn("Working memory may not be disposed: {} facts in session {}", 
        factCount, sessionId);
}

// Always dispose stateful sessions
session.dispose();

Expose a working memory health check:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/workingMemory
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 2 minutes
  6. Click Save.

The leading indicator is a monotonically increasing fact count in a session ID that should have been disposed — this precedes the OOM crash by minutes or hours.

Step 5: Monitor DMN Decision Service Latency

If your Drools deployment uses DMN (Decision Model and Notation) for structured decision tables and decision requirements graphs, DMN decision service latency is a separate concern from DRL rule execution. DMN decisions can be complex, multi-step graphs; a regression in a DMN model can spike evaluation time without affecting DRL rule throughput.

Monitor a representative DMN endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kie-server:8080/kie-server/services/rest/server/containers/{containerId}/dmn
  3. Method: GET
  4. Expected status: 200
  5. Check interval: 2 minutes
  6. Click Save.

For latency-specific monitoring, use a probe that exercises the actual DMN decision path:

# Health probe: evaluate a known DMN decision with test input
curl -X POST \
  http://your-kie-server:8080/kie-server/services/rest/server/containers/{containerId}/dmn \
  -H "Content-Type: application/json" \
  -d '{"model-namespace":"...","model-name":"...","decision-name":"...","context":{"testInput":1}}'

Time the response and alert when it exceeds your DMN SLA threshold (typically 100ms for real-time decisions).

Step 6: Monitor Business Central

Business Central is the web workbench for Drools rule authoring — where your rules analysts create and modify DRL rules, decision tables, DMN models, and test scenarios. Its unavailability blocks rule updates and KJAR deployments.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-business-central:8080/business-central
  3. Expected status: 200
  4. Keyword check: Business Central
  5. Check interval: 2 minutes
  6. Enable Monitor SSL certificate if Business Central is HTTPS-exposed, with expiry alert at 21 days.
  7. Click Save.

Business Central is a resource-heavy Wildfly/EAP application. On constrained servers, it's often the first service to become unresponsive under JVM heap pressure — monitor it separately from KIE Server even if they run on the same host.

Step 7: Monitor KJAR Container Deployment Health

Drools rules are packaged as KJARs (KIE Java Archives) and deployed to KIE Server as containers. A failed KJAR deployment means rules are not updated — your KIE Server is executing an older version of the rules, or no rules at all if it's a first deployment.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kie-server:8080/kie-server/services/rest/server/containers
  3. Method: GET
  4. Expected status: 200
  5. Keyword check: "status":"STARTED" — all healthy rule containers report STARTED.
  6. Check interval: 2 minutes
  7. Click Save.

For a specific container (e.g., fraud-rules_2.1.0):

http://your-kie-server:8080/kie-server/services/rest/server/containers/fraud-rules_2.1.0

A FAILED container status means rules from that KJAR are unavailable. Add a separate monitor per production rule container to isolate deployment failures by rule domain.

Step 8: Monitor CEP Event Stream Processing Lag

If you use Drools Fusion for Complex Event Processing — temporal rule windows over event streams such as fraud pattern detection, anomaly detection, or IoT event correlation — CEP processing lag is a critical metric. When the CEP engine falls behind the real-time event stream, temporal windows drift and rule evaluations are made on stale data.

Expose CEP lag from your Drools CEP application:

// Track the lag between event ingestion time and CEP processing time
@EventListener
public void onEvent(MyDomainEvent event) {
    long eventTime = event.getTimestamp();
    long now = System.currentTimeMillis();
    long lagMs = now - eventTime;
    
    meterRegistry.gauge("drools.cep.processing.lag.ms", lagMs);
    
    if (lagMs > CEP_LAG_THRESHOLD_MS) {
        log.warn("CEP processing lag exceeds threshold: {}ms", lagMs);
    }
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/cepLag
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Step 9: Monitor JVM Heap and GC

Drools KIE Server's memory profile is dominated by working memory objects (facts), compiled PHREAK networks (the in-memory rule index), and active rule sessions. Large rule sets with many facts can consume hundreds of megabytes of heap. A JVM crash from OutOfMemoryError terminates all rule sessions instantly.

Add a heap health indicator:

@Component
public class HeapHealthIndicator implements HealthIndicator {
    
    @Override
    public Health health() {
        MemoryMXBean memBean = ManagementFactory.getMemoryMXBean();
        long used = memBean.getHeapMemoryUsage().getUsed();
        long max = memBean.getHeapMemoryUsage().getMax();
        double pct = (double) used / max * 100;
        
        // Also check GC pause time
        long totalGcTimeMs = ManagementFactory.getGarbageCollectorMXBeans()
            .stream().mapToLong(GarbageCollectorMXBean::getCollectionTime).sum();
        
        if (pct > 85) {
            return Health.down()
                .withDetail("heapUsedPct", String.format("%.1f%%", pct))
                .withDetail("totalGcTimeMs", totalGcTimeMs)
                .build();
        }
        return Health.up()
            .withDetail("heapUsedPct", String.format("%.1f%%", pct))
            .build();
    }
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/heapHealth
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Step 10: Monitor Rule Conflict and Error Rate

DRL rule evaluation errors — ClassCastException from mismatched fact types, NullPointerException in rule consequence blocks, constraint violations — produce exceptions that propagate to the calling application. A sustained rule error rate means your DRL logic has a bug or a fact type mismatch after a rule deployment.

Track rule errors separately from application errors:

// Drools AgendaEventListener for rule error tracking
public class RuleErrorListener extends DefaultAgendaEventListener {
    
    @Override
    public void afterRuleFired(AfterRuleFiredEvent event) {
        meterRegistry.counter("drools.rules.fired", 
            "rule", event.getRule().getName()).increment();
    }
    
    // Override rule exception handling in your session wrapper
    public void onRuleException(Exception e, String ruleName) {
        meterRegistry.counter("drools.rule.errors",
            "rule", ruleName,
            "exception", e.getClass().getSimpleName()).increment();
        log.error("Rule execution error in {}: {}", ruleName, e.getMessage());
    }
}

Expose a rule error rate health check:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/ruleErrors
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 2 minutes
  6. Click Save.

Alerting Configuration

Configure Vigilmon alert channels by operational impact:

KIE Server health — alert immediately on 1 failure. All rule execution stops.

KJAR container deployment — alert immediately on FAILED status. Rules are running stale or not at all.

Rule execution latency (p99) — alert when p99 exceeds your decision SLA; affects real-time user flows.

Working memory size — alert on sustained growth trend; indicates un-disposed sessions heading toward OOM.

JVM heap — alert above 85% heap; include restart runbook.

Rule error rate — alert after 2 consecutive minutes above threshold; typically indicates a rule logic bug post-deployment.

Business Central — alert after 2 consecutive failures; developers and rules analysts are blocked.

CEP processing lag — alert immediately if above threshold; temporal rule windows are evaluating stale events.

Conclusion

Drools KIE Server is often invisible to end users — they see the downstream application decision (approved, declined, priced), not the rule engine that produced it. That invisibility makes monitoring especially important: a silent Drools failure produces wrong decisions with no error surface until a user notices an incorrect outcome. With Vigilmon monitoring KIE Server health, rule execution throughput and latency, working memory growth, and KJAR deployment status, you surface rule engine failures before they affect business decisions.

Start with the free Vigilmon account and add your first KIE Server monitor in under five minutes.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles