tutorial

How to Monitor Gravitee API Gateway with Vigilmon (HTTP, TCP, and Alerts)

Gravitee is an open-source API management platform that provides an API gateway, developer portal, API designer, and access management in a single suite. Ent...

Gravitee is an open-source API management platform that provides an API gateway, developer portal, API designer, and access management in a single suite. Enterprises use Gravitee to secure, throttle, transform, and publish APIs across REST, WebSocket, gRPC, and GraphQL protocols. When Gravitee's gateway goes down, every API that routes through it becomes unreachable — consumers get 502s, internal services lose their communication paths, and developers can't access the portal to diagnose the problem.

In this tutorial you'll set up end-to-end monitoring for a self-hosted Gravitee deployment using Vigilmon — free tier, no credit card required.

Why Gravitee needs external monitoring

Gravitee's architecture is composed of several independent services, each of which can fail independently:

  • API Gateway (APIM Gateway) — the data plane that proxies all incoming API traffic, typically on port 8082; if this goes down, all APIs are unreachable
  • Management API (APIM Management API) — the control plane REST API used by the console and CI pipelines to manage APIs, plans, and subscriptions, on port 8083
  • Management Console — the Angular web UI on port 4200 (or served by nginx)
  • Developer Portal — the consumer-facing API catalog and subscription portal
  • MongoDB — stores API definitions, policies, subscription data, and gateway configuration
  • Elasticsearch — stores analytics and API logs; loss of Elasticsearch means analytics stop but traffic continues (degraded, not down)

Gravitee failure modes that are easy to miss:

  • Gateway process crash — a buggy policy plugin causes an uncaught exception that kills the gateway; nginx returns 502 for all API calls; the Docker container restarts but the brief outage window goes undetected
  • MongoDB replica set election — a MongoDB primary election takes 10-30 seconds; during this window the Management API cannot write; API deployments queue or fail
  • Policy sync delay — the gateway polls MongoDB for API configuration updates; if MongoDB is degraded, newly deployed APIs or policy changes are not picked up
  • Elasticsearch write failures — analytics events queue in memory; after the queue fills, the gateway starts dropping analytics records silently
  • SSL certificate expiry — the gateway's outbound TLS certificate for a backend API expires; requests to that specific API return 502 while all other APIs continue working

An external monitor catches all gateway-layer failures from the consumer's perspective — exactly what your API consumers experience.

What you'll need

  • A running Gravitee APIM deployment (Docker Compose or Kubernetes)
  • A free Vigilmon account — takes 30 seconds to create

Step 1: Identify Gravitee health endpoints

Gravitee ships with Spring Boot Actuator health endpoints on all server components. These are enabled by default on the technical port (separate from the gateway proxy port).

Gateway health check (port 18082 by default):

curl http://<your-host>:18082/_node/health

Healthy response:

{
  "db-repositories": { "healthy": true },
  "process-cpu-threshold": { "healthy": true },
  "memory-threshold": { "healthy": true },
  "management-repository": { "healthy": true }
}

Management API health check (port 18083 by default):

curl http://<your-host>:18083/_node/health

Gateway readiness probe (Kubernetes):

curl http://<your-host>:18082/_node/health?probes=security-policy-manager,sync

To expose these health endpoints to Vigilmon, proxy them through nginx:

server {
    listen 443 ssl;
    server_name gateway-health.yourcompany.com;

    ssl_certificate     /etc/letsencrypt/live/gateway-health.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gateway-health.yourcompany.com/privkey.pem;

    location /_node/health {
        proxy_pass http://127.0.0.1:18082/_node/health;
        proxy_set_header Host $host;
        # Restrict to Vigilmon monitoring IPs
        allow 185.25.104.0/24;
        deny all;
    }

    location /mgmt-health {
        proxy_pass http://127.0.0.1:18083/_node/health;
        proxy_set_header Host $host;
        allow 185.25.104.0/24;
        deny all;
    }
}

Step 2: Set up HTTP monitoring for the gateway

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS as the type
  3. Set the URL to https://gateway-health.yourcompany.com/_node/health
  4. Set the check interval to 1 minute
  5. Under Expected response, configure:
    • Status code: 200
    • Response body contains: "management-repository":{"healthy":true}
  6. Save the monitor

Add a second monitor for the Management API:

  1. Create a monitor for https://gateway-health.yourcompany.com/mgmt-health
  2. Expected status: 200
  3. Response body: "healthy":true

The two monitors together tell you whether a failure is in the data plane (gateway) or control plane (management API).

Step 3: Monitor the gateway proxy port directly

Beyond health endpoints, Vigilmon should probe the actual proxy port to verify the gateway is accepting and routing API requests:

Create an echo API in Gravitee for monitoring:

  1. In the Gravitee console, create a new API called healthcheck
  2. Set the entrypoint to /healthz
  3. Set the backend (endpoint) to a simple HTTP mock endpoint: return {"status":"ok"} with a 200 status
  4. Deploy the API with an API key plan or a keyless plan restricted to the Vigilmon monitoring IP range
  5. Publish the API

Now add a Vigilmon HTTP monitor for this endpoint:

  1. Create a monitor for https://api.yourcompany.com/healthz
  2. If using an API key plan, add the API key header: X-Gravitee-Api-Key: your-monitoring-api-key
  3. Expected status: 200
  4. Response body: "status":"ok"

This monitor verifies the full gateway path: DNS → TLS → nginx → Gravitee gateway → policy engine → mock backend. If any layer fails, this check catches it.

For TCP monitoring of the gateway port:

  1. Go to Monitors → New Monitor → TCP Port
  2. Host: api.yourcompany.com, Port: 443 (or 8082 for direct access)
  3. Save the monitor

Step 4: Monitor MongoDB and Elasticsearch

MongoDB TCP monitor:

  1. Go to Monitors → New Monitor → TCP Port
  2. Host: mongodb.yourcompany.com, Port: 27017
  3. Save the monitor

If MongoDB is in a replica set, add TCP monitors for each member:

mongodb-0.yourcompany.com:27017
mongodb-1.yourcompany.com:27017
mongodb-2.yourcompany.com:27017

Elasticsearch HTTP monitor:

Elasticsearch exposes a cluster health API:

curl https://elastic.yourcompany.com/_cluster/health

Response:

{
  "cluster_name": "gravitee",
  "status": "green",
  "number_of_nodes": 3,
  "active_shards": 24
}

Add a Vigilmon HTTP monitor:

  1. URL: https://elastic.yourcompany.com/_cluster/health
  2. Expected status: 200
  3. Response body contains: "status":"green"

Note: if Elasticsearch is yellow (replica shards unassigned), analytics still work. Only alert on "status":"red" which means primary shards are missing.

Step 5: Configure alerts and a status page

Webhook alert for gateway down:

  1. Go to Alert Channels → Add Channel → Webhook
  2. Enter your Slack or PagerDuty webhook URL
  3. Assign it to: gateway health, gateway proxy TCP, and the echo API monitor

Example Slack alert payload:

{
  "monitor_name": "Gravitee Gateway /_node/health",
  "status": "down",
  "url": "https://gateway-health.yourcompany.com/_node/health",
  "started_at": "2024-05-08T11:45:00Z",
  "duration_seconds": 180
}

Status page for API consumers:

If you have external API consumers, a public status page gives them visibility into gateway status without needing to contact your support team:

  1. Go to Status Pages → New Status Page
  2. Name it "API Platform Status"
  3. Add monitors: Gateway health, Management API health, Echo API (proxy check)
  4. Publish the page

Share this URL in your developer portal and API documentation. Consumers can subscribe to status page updates via email.

Gravitee Docker Compose with health monitoring

version: "3.9"

services:
  gateway:
    image: graviteeio/apim-gateway:4
    ports:
      - "8082:8082"
      - "18082:18082"  # Technical/health port
    environment:
      - gravitee_management_mongodb_uri=mongodb://mongodb:27017/gravitee
      - gravitee_reporters_elasticsearch_endpoints_0=http://elasticsearch:9200
    depends_on:
      mongodb:
        condition: service_healthy
      elasticsearch:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18082/_node/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    restart: unless-stopped

  management-api:
    image: graviteeio/apim-management-api:4
    ports:
      - "8083:8083"
      - "18083:18083"  # Technical/health port
    environment:
      - gravitee_management_mongodb_uri=mongodb://mongodb:27017/gravitee
      - gravitee_analytics_elasticsearch_endpoints_0=http://elasticsearch:9200
    depends_on:
      mongodb:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18083/_node/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    restart: unless-stopped

  management-console:
    image: graviteeio/apim-management-ui:4
    ports:
      - "4200:8080"
    environment:
      - MGMT_API_URL=http://management-api:8083/management/
    depends_on:
      - management-api
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

  mongodb:
    image: mongo:6.0
    volumes:
      - mongo_data:/data/db
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  elasticsearch:
    image: elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    volumes:
      - elastic_data:/usr/share/elasticsearch/data
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:9200/_cluster/health | grep -v '\"status\":\"red\"'"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    restart: unless-stopped

volumes:
  mongo_data:
  elastic_data:

Monitoring checklist

| What to monitor | Type | Endpoint | Alert on | |---|---|---|---| | Gateway health | HTTP | /_node/health (port 18082) | Non-200 or unhealthy component | | Management API health | HTTP | /_node/health (port 18083) | Non-200 | | Echo API (proxy check) | HTTP | /healthz via gateway | Non-200 | | Gateway proxy port | TCP | api-host:8082 or 443 | Connection refused | | MongoDB | TCP | mongodb-host:27017 | Connection refused | | Elasticsearch | HTTP | /_cluster/health | "status":"red" |

Summary

Gravitee is the entry point for all your APIs — downtime at the gateway layer means every consumer, integration, and internal service loses connectivity simultaneously. A layered monitoring strategy covering the gateway health endpoint, the actual proxy port, MongoDB, Elasticsearch, and a live echo API gives you precise failure attribution and immediate alerting. With Vigilmon's free tier, you can set up all six monitors with 1-minute check intervals, Slack or PagerDuty alerts, and a public status page for your API consumers in under fifteen minutes.

Start monitoring your API gateway for 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