tutorial

Monitoring Kogito with Vigilmon

Kogito is Red Hat's cloud-native business automation platform on Quarkus — here's how to monitor Kogito service health, process REST endpoints, Data Index, Jobs Service, Kafka consumer lag, Management Console, and native memory with Vigilmon.

Kogito is Red Hat's cloud-native, Kubernetes-first business automation platform that brings BPMN workflow and Drools rules to the modern microservices era. Built on Quarkus (with optional Spring Boot support), Kogito generates REST endpoints directly from BPMN process definitions — each process becomes a microservice with its own API. The platform includes supporting infrastructure: Kogito Data Index (a GraphQL service for querying process state), Kogito Jobs Service (a persistent timer scheduler), Kogito Management Console and Task Console (React-based monitoring UIs), and Kafka for CloudEvents. A Kogito deployment failure can be isolated (one process microservice crashing) or systemic (Data Index losing sync with Kafka) — and both need different monitoring approaches. Vigilmon gives you per-service health checks across the entire Kogito fleet.

What You'll Set Up

  • Per-service Quarkus health endpoint monitors (/q/health)
  • Process-specific REST endpoint health checks
  • Active process instance count via Data Index GraphQL
  • Human task pending count monitor
  • Kogito Data Index health monitor
  • Kogito Jobs Service health monitor
  • Kafka consumer lag monitor for Data Index
  • Kogito Management Console availability monitor
  • GraalVM native startup time monitor
  • JVM or native memory health monitor

Prerequisites

  • Kogito services deployed (Quarkus JVM or native mode) on Kubernetes or Docker Compose
  • Kogito Data Index service running and connected to Kafka
  • Kogito Jobs Service running (if using BPMN timer events)
  • A free Vigilmon account

Step 1: Monitor Each Kogito Service Health

Every Kogito service is a Quarkus microservice with a built-in health endpoint. Because Kogito follows the microservices pattern (one service per bounded context or process group), you will have multiple services to monitor independently — an order management service, a customer onboarding service, a claims processing service.

For each Kogito service:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: http://your-kogito-service:8080/q/health
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Keyword check, enter "status":"UP" to verify Quarkus health reports all components healthy.
  7. Click Save.

The /q/health endpoint aggregates Quarkus health checks including database connectivity (if configured), Kafka connectivity (if using CloudEvents), and application-specific checks. A DOWN status on any component rolls up to the overall health response.

For finer-grained readiness vs. liveness separation:

  • Liveness (is the JVM alive?): /q/health/live
  • Readiness (is the service ready to handle requests?): /q/health/ready

Create separate Vigilmon monitors for liveness and readiness on critical services — a DOWN readiness with UP liveness means the service is alive but temporarily unable to handle requests (e.g., waiting for Kafka to become available).

Repeat this for every Kogito service in your deployment.

Step 2: Monitor Process REST Endpoint Health

Kogito generates REST endpoints for each BPMN process definition. For an order process, Kogito generates GET /order (list instances), POST /order (start instance), GET /order/{id} (get instance), etc. A failure on the process endpoint means clients cannot start or interact with that process, even if the Quarkus JVM is healthy.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kogito-service:8080/orders (replace orders with your process name)
  3. Method: GET
  4. Expected status: 200
  5. Keyword check: [] or [{ — an empty or non-empty JSON array, confirming the endpoint is responding.
  6. Check interval: 1 minute
  7. Click Save.

Add a monitor for each critical process endpoint — this catches cases where the process definition failed to compile or the process container is in an error state, which would not show up in the generic /q/health check.

Step 3: Monitor Active Process Instance Count via Data Index

Kogito Data Index is the central query service for process state across your entire Kogito fleet. It consumes CloudEvents from Kafka and exposes a GraphQL API for querying process instances, human tasks, and process variables. Use Data Index to monitor active process instance counts.

Create a GraphQL health probe endpoint in a sidecar or monitoring service:

// GraphQL query to count active process instances
const ACTIVE_INSTANCES_QUERY = `
  query {
    ProcessInstances(where: { state: { equal: ACTIVE } }) {
      id
    }
  }
`;

// Health endpoint that counts active instances
app.get('/health/activeInstances', async (req, res) => {
  const response = await fetch('http://data-index:8180/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: ACTIVE_INSTANCES_QUERY })
  });
  const data = await response.json();
  const count = data.data.ProcessInstances.length;
  
  res.json({
    activeInstances: count,
    status: count < 10000 ? 'ok' : 'warning'
  });
});
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-monitoring-sidecar:3000/health/activeInstances
  3. Expected status: 200
  4. Keyword check: "status":"ok"
  5. Check interval: 2 minutes
  6. Click Save.

Step 4: Monitor Human Task Pending Count

Kogito human tasks (BPMN User Tasks) are surfaced through the Task Console and the Data Index GraphQL API. A growing pending task queue means users are not completing assigned tasks, which stalls process instances at human task wait states.

Query pending tasks via Data Index GraphQL:

const PENDING_TASKS_QUERY = `
  query {
    UserTaskInstances(where: { state: { equal: "Ready" } }) {
      id
      name
      processInstanceId
    }
  }
`;

app.get('/health/pendingTasks', async (req, res) => {
  const response = await fetch('http://data-index:8180/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: PENDING_TASKS_QUERY })
  });
  const data = await response.json();
  const count = data.data.UserTaskInstances.length;
  
  res.json({
    pendingTasks: count,
    status: count < 500 ? 'ok' : 'degraded'
  });
});
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-monitoring-sidecar:3000/health/pendingTasks
  3. Expected status: 200
  4. Keyword check: "status":"ok"
  5. Check interval: 2 minutes
  6. Click Save.

Step 5: Monitor Kogito Data Index Health

Kogito Data Index is the query backbone of a multi-service Kogito deployment. When Data Index is down, you lose visibility into all process state — Management Console goes blank, GraphQL queries fail, and any application that queries process data via Data Index returns errors.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-data-index:8180/q/health
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Data Index's health check includes its Kafka consumer connectivity and its database (PostgreSQL or Infinispan) connection. A DOWN on Data Index health almost always means either Kafka is unreachable or the persistence layer failed.

Also add a readiness check:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-data-index:8180/q/health/ready
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Data Index readiness indicates it has successfully connected to Kafka and initialized its persistence schema.

Step 6: Monitor Kogito Jobs Service Health

The Kogito Jobs Service manages all BPMN timer events — intermediate catching timer events, boundary timers, and SLA deadline escalations. When Jobs Service fails, all timer-based process transitions stop: processes that should escalate after 24 hours wait indefinitely, and SLA timers never fire.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-jobs-service:8580/q/health
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Jobs Service uses PostgreSQL or Infinispan for job persistence. Its health check reflects the persistence layer connectivity. Add a heartbeat to verify Jobs Service is actively scheduling jobs (not just alive):

// A Quarkus scheduled job that runs every 5 minutes and pings Vigilmon
@ApplicationScoped
public class JobsServiceHeartbeat {
    
    @ConfigProperty(name = "vigilmon.heartbeat.url")
    String heartbeatUrl;
    
    @Scheduled(every = "5m")
    void ping() {
        // This job being scheduled by Kogito Jobs Service proves Jobs Service is alive
        client.getAbs(heartbeatUrl).send();
    }
}

In Vigilmon, add a heartbeat monitor expecting a ping every 10 minutes.

Step 7: Monitor Kafka Consumer Lag for Data Index

Kogito services publish CloudEvents to Kafka when process instances start, tasks are created, and processes complete. Data Index consumes these events to maintain its queryable state. When the Kafka consumer group for Data Index falls behind — measured by consumer lag — process state in Data Index becomes stale: Management Console shows outdated data and GraphQL queries return inconsistent results.

Expose consumer lag via a Kafka monitoring endpoint or Kafka Exporter:

// Monitor Kafka consumer lag for the Data Index consumer group
@ReadOperation
public Health kafkaLagHealth() {
    Map<TopicPartition, Long> lags = adminClient.listConsumerGroupOffsets("kogito-data-index")
        .partitionsToOffsetAndMetadata()
        .get()
        .entrySet()
        .stream()
        .collect(Collectors.toMap(
            Map.Entry::getKey,
            e -> getEndOffset(e.getKey()) - e.getValue().offset()
        ));
    
    long totalLag = lags.values().stream().mapToLong(Long::longValue).sum();
    
    if (totalLag > 10000) {
        return Health.down()
            .withDetail("totalConsumerLag", totalLag)
            .withDetail("threshold", 10000)
            .build();
    }
    return Health.up().withDetail("totalConsumerLag", totalLag).build();
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kafka-monitor:8080/health/dataIndexLag
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

A consumer lag above threshold means Data Index is processing events slower than Kogito services are producing them — typically caused by Data Index being down and restarting, or a sudden burst of process activity overwhelming the indexer.

Step 8: Monitor Kogito Management Console

Kogito Management Console is the React-based web UI for monitoring process instances. While the console is not in the critical path of process execution (processes run fine without it), its availability is important for operators who need to intervene in stuck or failed process instances.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-management-console:8280
  3. Expected status: 200
  4. Keyword check: Kogito (appears in the React app's page title)
  5. Check interval: 2 minutes
  6. Enable Monitor SSL certificate if HTTPS-exposed, with expiry alert at 21 days.
  7. Click Save.

Management Console depends on Data Index for its data. Even if the console itself is healthy, operators will see empty dashboards if Data Index is down. Monitor both independently.

Step 9: Monitor GraalVM Native Startup Time

If you compile Kogito services to GraalVM native executables, startup time is a key operational metric. A native binary that takes more than 5 seconds to start indicates either a misconfiguration in the native image profile (too many dynamic class initializations), excessive startup-time database migrations, or a very large application. Slow native startups become critical during a Kubernetes rolling update or crash-loop recovery.

Monitor startup time via a Quarkus metric:

// Quarkus exposes startup time via MicroProfile Metrics
@Inject
@Metric(name = "jvm.uptime")
Gauge<Long> uptime;

// Or use the Quarkus startup event
void onStart(@Observes StartupEvent ev) {
    long startupMs = System.currentTimeMillis() - startTime;
    log.info("Kogito service started in {}ms", startupMs);
    
    if (startupMs > 5000) {
        log.warn("Startup time {}ms exceeds 5s threshold for native binary", startupMs);
    }
}

For Kubernetes deployments, track startup time via the container readiness probe delay:

readinessProbe:
  httpGet:
    path: /q/health/ready
    port: 8080
  initialDelaySeconds: 2  # native binaries should be ready in <2s
  periodSeconds: 1
  failureThreshold: 10

Add a Vigilmon HTTP monitor on /q/health/ready with a check interval of 30 seconds to catch containers stuck in startup (not ready after restart).

Step 10: Monitor JVM or Native Memory Health

Kogito services running on JVM have standard heap constraints; native executables have their own RSS memory footprint. Both can grow under sustained load from large numbers of active process instances, unclosed stateful rule sessions (if using Drools alongside jBPM in Kogito), or event accumulation in Data Index.

For JVM mode:

@Component
public class MemoryHealthIndicator implements HealthIndicator {
    
    @Override
    public Health health() {
        MemoryMXBean mem = ManagementFactory.getMemoryMXBean();
        long used = mem.getHeapMemoryUsage().getUsed();
        long max = mem.getHeapMemoryUsage().getMax();
        double pct = (double) used / max * 100;
        
        return pct > 85
            ? Health.down().withDetail("heapUsedPct", String.format("%.1f%%", pct)).build()
            : Health.up().withDetail("heapUsedPct", String.format("%.1f%%", pct)).build();
    }
}

For native mode, monitor RSS via a sidecar:

# Native binary RSS monitoring sidecar
#!/bin/sh
while true; do
  RSS_KB=$(cat /proc/1/status | grep VmRSS | awk '{print $2}')
  if [ "$RSS_KB" -gt 2097152 ]; then  # 2GB threshold
    echo '{"status":"DOWN","rssKb":'$RSS_KB'}' > /tmp/memory_health.json
  else
    echo '{"status":"UP","rssKb":'$RSS_KB'}' > /tmp/memory_health.json
  fi
  sleep 30
done
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kogito-service:8080/q/health (includes memory health via custom health check)
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Alerting Configuration

Kogito's microservices architecture means alert routing matters — not every failure is equally critical:

Process service health — alert immediately on 1 failure; that process domain is completely unavailable.

Data Index health — alert immediately on 1 failure; all process state visibility is lost.

Jobs Service health — alert immediately on 1 failure; all timer events are suspended.

Kafka consumer lag — alert when lag exceeds threshold; Data Index state is becoming stale.

Task Console / Management Console — alert after 2 consecutive failures; operations visibility is impaired but processes still run.

Active process instance count spike — alert after 2 consecutive threshold breaches; route to process operations team.

Pending task queue — alert after 2 consecutive threshold breaches; notify both operations and engineering.

JVM/native memory — alert above 85% heap or RSS threshold; include a rollout restart runbook for Kubernetes.

GraalVM native readiness — alert if /q/health/ready remains DOWN more than 30 seconds after container start.

Conclusion

Kogito's cloud-native design distributes process execution across independent microservices — which is excellent for scalability but means monitoring must be distributed too. A single Vigilmon dashboard cannot show you "Kogito is down"; it shows you "the claims service is down" or "Data Index is behind Kafka by 15,000 events." With per-service health monitors on /q/health, endpoint monitors on process REST APIs, and infrastructure monitors on Data Index and Jobs Service, you get the precise failure isolation that a microservices architecture demands. Add the Kafka consumer lag monitor to catch the subtle Data Index drift that appears before full failures, and you have end-to-end observability across your entire Kogito deployment.

Start with the free Vigilmon account and add your first Kogito service 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