tutorial

Monitoring Zeebe with Vigilmon: Gateway Health, gRPC Port, Camunda Operate, and Cluster Topology

How to monitor Zeebe workflow engine with Vigilmon — gateway gRPC health, Camunda Operate uptime, REST API availability, and cluster topology checks for distributed BPMN orchestration.

Zeebe is the cloud-native workflow engine at the core of Camunda Platform 8 — the distributed, horizontally scalable BPMN orchestration engine designed for high-throughput microservice coordination. When the Zeebe gateway goes down, every SDK client (Java, Go, Node.js, Python) loses the ability to deploy process definitions, create workflow instances, or publish messages. When a partition loses its leader, workflow instances assigned to that partition stall indefinitely. When Camunda Operate is unavailable, engineers lose all visibility into running processes, incidents, and failed jobs. Vigilmon gives you external observability into Zeebe's key surfaces: gateway availability, gRPC port connectivity, Operate uptime, and the REST API that exposes cluster health.

What You'll Build

  • A monitor on the Zeebe gateway REST API for cluster topology health
  • A TCP monitor on the gRPC port to catch SDK connectivity failures
  • Camunda Operate uptime monitoring for process visibility
  • SSL certificate monitoring for TLS-secured Zeebe deployments
  • An alerting configuration that distinguishes gateway failures from partition-level issues

Prerequisites

  • A running Zeebe cluster (self-hosted or Camunda Platform 8 SaaS) with a reachable domain
  • Zeebe gateway REST API or gRPC port accessible
  • Camunda Operate deployed and accessible over HTTPS (optional but recommended)
  • A free account at vigilmon.online

Step 1: Understand Zeebe's External Interfaces

Zeebe exposes the following externally reachable endpoints:

| Port | Protocol | Role | |---|---|---| | 26500 | gRPC | Zeebe gateway — all SDK client connections | | 8080 | HTTP/REST | Zeebe REST API (Camunda 8.4+) for topology, process deployment, instances | | 9600 | HTTP | Zeebe monitoring and metrics (/actuator/health, /metrics) | | 8080 (Operate) | HTTP | Camunda Operate web UI (may be on a separate host) |

Camunda Platform 8 Cloud: On Camunda SaaS, the gateway is at <cluster-id>.zeebe.camunda.io:443 (TLS). The REST API is at https://<region>.zeebe.camunda.io.

External monitoring focuses on the gRPC port (SDK connectivity), the REST API (cluster health), and Camunda Operate (process visibility).

Step 2: Monitor the Zeebe Gateway Health Endpoint

Zeebe exposes a management actuator on port 9600 by default. The /actuator/health endpoint returns cluster health including gateway status and partition leadership:

curl http://zeebe.example.com:9600/actuator/health
# Returns JSON: {"status":"UP","components":{...}}
  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: http://zeebe.example.com:9600/actuator/health.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: "status":"UP".
  7. Label: Zeebe gateway health.
  8. Click Save.

This monitor catches gateway process crashes, partition leadership failures that degrade to a DOWN status, and Raft consensus issues that mark the gateway unhealthy.

Alert sensitivity: Set to trigger after 1 consecutive failure — a down gateway means all SDK clients are disconnected and no workflow instances can be created.

Step 3: Monitor the gRPC Port via TCP Check

The Zeebe gateway accepts all SDK client connections on gRPC port 26500. A TCP check confirms the port is accepting connections independently of the health endpoint:

# Test gRPC port connectivity
nc -zv zeebe.example.com 26500
# Connected: gRPC port is open
  1. Add Monitor → TCP.
  2. Host: zeebe.example.com.
  3. Port: 26500.
  4. Check interval: 60 seconds.
  5. Label: Zeebe gRPC gateway port.
  6. Click Save.

Why TCP in addition to the health endpoint? The health endpoint is served by the management server — a separate HTTP server from the gRPC gateway itself. In edge cases, the gRPC port may be blocked by a firewall rule or load balancer while the management port remains reachable. The TCP check catches port-level failures that the health endpoint misses.

TLS/mTLS: If your Zeebe gateway uses TLS (as Camunda Platform 8 Cloud does), the gRPC port is still 443 (or the configured TLS port). TCP checks work the same way — the TCP handshake succeeds regardless of TLS.

Step 4: Monitor the Zeebe REST API (Camunda 8.4+)

Camunda Platform 8.4+ includes a native REST API alongside the gRPC gateway. If available, the REST API provides an HTTP-native health signal for cluster topology:

# Get cluster topology
curl https://zeebe.example.com:8080/v2/topology
# Returns JSON with broker count, partition count, and replication factor
  1. Add Monitor → HTTP.
  2. URL: https://zeebe.example.com:8080/v2/topology.
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: "brokers".
  7. Label: Zeebe REST API topology.
  8. Click Save.

This confirms the REST API gateway is up and the cluster topology is reachable — a prerequisite for all REST-based process deployments and instance management.

If using Camunda 8 SaaS, the REST API endpoint is https://<region>.zeebe.camunda.io/v2/topology with OAuth2 authentication. For external monitoring without credentials, rely on the gRPC TCP check and Operate HTTP monitor instead.

Step 5: Monitor Camunda Operate

Camunda Operate is the web UI for process monitoring — it shows running instances, completed processes, incidents, and job worker activity. When Operate is down, engineers have no visibility into the BPMN engine's runtime state:

curl https://operate.example.com
# Returns HTML: "Camunda Operate"
  1. Add Monitor → HTTP.
  2. URL: https://operate.example.com.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: Camunda (appears in the Operate page title and content).
  7. Label: Camunda Operate UI.
  8. Click Save.

Operate's Elasticsearch dependency: Camunda Operate is backed by Elasticsearch. If Elasticsearch is unavailable, Operate will fail to load process data even if the web server responds with a 200. Consider adding an Elasticsearch health monitor (http://elasticsearch:9200/_cluster/health) as a companion check.

Step 6: Monitor Camunda Tasklist (If Deployed)

If you're using Camunda Tasklist for human task management, add a similar HTTP monitor:

  1. Add Monitor → HTTP.
  2. URL: https://tasklist.example.com.
  3. Check interval: 60 seconds.
  4. Expected status: 200.
  5. Keyword: Camunda.
  6. Label: Camunda Tasklist UI.
  7. Click Save.

Step 7: Monitor SSL Certificates

Zeebe's gRPC gateway and Operate both use TLS in production. Certificate expiry causes all SDK clients and browser users to fail:

openssl s_client -connect zeebe.example.com:443 2>/dev/null | openssl x509 -noout -dates
  1. Add Monitor → SSL Certificate.
  2. Domain: zeebe.example.com.
  3. Alert when expiry is within: 30 days.
  4. Alert again: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

Repeat for operate.example.com and tasklist.example.com.

mTLS for Zeebe SDK clients: If your Zeebe deployment uses mutual TLS (client certificates required for SDK authentication), client certificate expiry is a separate failure mode — the gateway port will be reachable but clients with expired certificates will be rejected. Monitor client certificate expiry separately via your PKI toolchain.

Step 8: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Incident meaning | Action | |---|---|---|---| | Zeebe health endpoint | Non-200 or "UP" missing | Gateway degraded or partition losing leadership | Check gateway pod logs; verify Raft quorum; inspect partition leader status | | gRPC TCP (26500) | Connection refused | Gateway port down; all SDK clients disconnected | Check firewall rules; verify gateway pod is running; inspect K8s service | | REST API topology | Non-200 or "brokers" missing | REST gateway degraded; API clients failing | Check REST API gateway; verify TLS; inspect pod logs | | Camunda Operate | Non-200 or Camunda missing | Operate unavailable; no process visibility | Check Operate pod; verify Elasticsearch connectivity; inspect ingress | | Camunda Tasklist | Non-200 or Camunda missing | Tasklist unavailable; human tasks blocked | Check Tasklist pod; verify Elasticsearch; inspect ingress | | SSL Certificate | < 30 days to expiry | Certificate expiring | Renew certificate; test SDK and browser connectivity after renewal |

Alert after: 1 consecutive failure for the gRPC TCP and health endpoint monitors. 2 consecutive failures for Operate and Tasklist monitors.

Common Zeebe Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Gateway pod OOM killed (K8s) | gRPC TCP and health monitors fire; SDK clients disconnect immediately | | Partition leader election in progress | Health monitor may briefly show degraded; resolves when new leader elected | | Elasticsearch unavailable (Operate backend) | Operate monitor fires; gRPC gateway may stay healthy | | Raft quorum lost (majority of brokers down) | Health monitor shows DOWN; partition processing stalls | | gRPC port blocked by NetworkPolicy | TCP monitor fires; health endpoint on 9600 may still respond | | Zeebe upgrade rolling restart | Brief health monitor trigger during pod restarts; clears on completion | | SSL certificate expires | SSL monitor alerts at 30-day threshold; SDK clients fail with TLS errors | | DNS misconfiguration | All monitors fire simultaneously | | Zeebe exporter (Elasticsearch) lag | Not directly catchable externally — use internal Prometheus metrics | | Job worker connectivity lost | Not directly catchable externally — incidents appear in Operate |

Partition and Job Worker Health

Vigilmon monitors Zeebe's external surfaces. Partition leadership, job worker connectivity, and incident rates require internal metric collection:

  • Zeebe Prometheus metrics: The /metrics endpoint on port 9600 exposes zeebe_partition_role (leader/follower), zeebe_job_activated_total, zeebe_incident_created_total, and zeebe_exporter_exported_total.
  • Partition leader alerts: Alert when any partition has zeebe_partition_role{role="leader"} == 0 — that partition has no leader and workflow instances assigned to it are stalled.
  • Incident rate alerts: Alert when rate(zeebe_incident_created_total[5m]) > 0 for more than 5 minutes — indicates systematic workflow processing failures.
  • Camunda Operate incidents view: The Operate UI's Incidents section shows all active incidents with process context and the failed job type.

Vigilmon catches infrastructure-level failures (gateway down, port unreachable, Operate unavailable, certificate expired). Partition health and job worker connectivity require Prometheus-based internal monitoring.

Zeebe is the workflow coordination layer for your entire microservice mesh — when the gateway goes down, every service task stops executing, running process instances stall mid-flight, and new business processes can't start. Vigilmon gives you the external health signal that confirms the gateway is alive and SDK clients can connect before your services start logging gRPC connection errors: gateway health, gRPC port TCP connectivity, Operate availability, and SSL certificate expiry, so you can restore orchestration before business processes time out.

Start monitoring Zeebe in under 5 minutes — register free at vigilmon.online.

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