tutorial

Monitoring WSO2 API Manager with Vigilmon

WSO2 API Manager is your self-hosted API gateway and lifecycle platform — but a crashed Gateway, Key Manager latency spike, or database failure can silently block all API traffic. Here's how to monitor WSO2 API Manager with Vigilmon.

WSO2 API Manager is a full-lifecycle, open source API management platform that handles everything from API design and publication to OAuth2 authentication, rate limiting, and analytics in a self-hosted deployment. It sits between your API consumers and backend services — if the Gateway crashes, every API call fails; if the Key Manager slows down, every authenticated request times out. Vigilmon gives you continuous health monitoring across every WSO2 component, so you catch Gateway outages, Key Manager degradation, and database failures before your API consumers do.

What You'll Set Up

  • API Gateway health and request throughput monitoring
  • API Publisher and Developer Portal availability checks
  • Key Manager OAuth2 token validation latency monitoring
  • Traffic Manager health and rate limit sync monitoring
  • API error rate tracking with endpoint-level alerts
  • Database connectivity health checks
  • Analytics pipeline health monitoring

Prerequisites

  • WSO2 API Manager 4.x installed and running
  • Access to the Gateway, Publisher, Developer Portal, and Key Manager endpoints
  • WSO2 admin credentials for API-level health checks
  • A free Vigilmon account

Step 1: Monitor the API Gateway Health

The WSO2 API Gateway is the runtime component that intercepts and proxies all API traffic. A Gateway crash blocks every API call across all deployed APIs. Monitor the Gateway's health endpoint directly:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the Gateway's health check URL: 
    https://your-wso2-host:9443/services/Version
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

Also monitor the Gateway's primary API traffic port:

  1. Click Add Monitor → TCP Port.
  2. Enter your Gateway host and port 8243 (HTTPS gateway port) or 8280 (HTTP gateway port).
  3. Set Check interval to 1 minute.
  4. Click Save.

For deployments using Choreo Connect (Envoy-based cloud-native gateway), monitor the Envoy admin endpoint instead:

http://your-choreo-connect-host:9000/ready

Step 2: Monitor the API Publisher Availability

API developers use the Publisher to design, document, and deploy APIs. If the Publisher is unavailable, no new APIs can be published and no existing APIs can be updated:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the Publisher URL: 
    https://your-wso2-host:9443/publisher
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200.
  5. Click Save.

The Publisher REST API (used by CI/CD pipelines for automated API deployment) is a separate check:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the Publisher REST API endpoint: 
    https://your-wso2-host:9443/api/am/publisher/v3/apis?limit=1
  3. Add a Basic Auth or Bearer token header with admin credentials.
  4. Set Expected HTTP status to 200.
  5. Click Save.

Step 3: Monitor the Developer Portal Availability

API consumers discover and subscribe to APIs through the Developer Portal (formerly the API Store). Portal downtime blocks new subscriptions and prevents consumers from obtaining API keys:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the Developer Portal URL: 
    https://your-wso2-host:9443/devportal
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200.
  5. Click Save.

Step 4: Monitor Key Manager Token Validation Latency

The Key Manager validates OAuth2 tokens and API subscriptions for every incoming API request. High Key Manager latency directly translates to slow API responses for all consumers — even if the backend APIs themselves are fast:

#!/bin/bash
# /opt/wso2/scripts/check-key-manager.sh
WSO2_HOST="your-wso2-host"
WSO2_PORT="9443"
LATENCY_THRESHOLD_MS=500
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_KM_HEARTBEAT_ID"

START=$(date +%s%N)
HTTP_CODE=$(curl -sf -o /dev/null -w "%{http_code}" --max-time 5 \
  "https://${WSO2_HOST}:${WSO2_PORT}/keymanager-operations/dcr/register" \
  -H "Content-Type: application/json" \
  --data-raw '{"callbackUrl":"https://example.com","clientName":"health-check","owner":"admin","grantType":"password refresh_token","saasApp":true}' \
  -k 2>/dev/null || echo "000")
END=$(date +%s%N)

ELAPSED_MS=$(( (END - START) / 1000000 ))

# Accept both 200 (success) and 400 (endpoint reached, bad request expected for minimal payload)
if { [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "400" ]; } && [ "$ELAPSED_MS" -lt "$LATENCY_THRESHOLD_MS" ]; then
  curl -sf "$HEARTBEAT_URL" > /dev/null
else
  echo "Key Manager response: HTTP ${HTTP_CODE}, latency ${ELAPSED_MS}ms (threshold: ${LATENCY_THRESHOLD_MS}ms)" >&2
fi

Schedule this check every 2 minutes and create a Cron Heartbeat monitor with a 5-minute expected interval.

Step 5: Monitor API Request Throughput and Error Rate

Track API invocation health through the WSO2 Analytics REST API or by querying the Gateway's own metrics:

#!/bin/bash
# /opt/wso2/scripts/check-api-error-rate.sh
WSO2_HOST="your-wso2-host"
WSO2_ANALYTICS_HOST="your-analytics-host"
ADMIN_USER="admin"
ADMIN_PASS="admin"
ERROR_RATE_THRESHOLD=5  # percent
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_ERRORRATE_HEARTBEAT_ID"

# Query API Analytics for error rate in the last 5 minutes
# This uses WSO2 API Manager's built-in analytics REST API
RESULT=$(curl -sf -u "${ADMIN_USER}:${ADMIN_PASS}" -k \
  "https://${WSO2_HOST}:9443/api/am/analytics/v2/stats/api-usage?startTime=$(date -d '5 minutes ago' +%s)000&endTime=$(date +%s)000" \
  2>/dev/null)

# If analytics isn't available, fall back to checking the Gateway is processing requests
# by verifying the Gateway management API responds
GW_HEALTH=$(curl -sf -o /dev/null -w "%{http_code}" -k \
  "https://${WSO2_HOST}:9443/api/am/admin/v3/api-categories" \
  -u "${ADMIN_USER}:${ADMIN_PASS}" 2>/dev/null)

if [ "$GW_HEALTH" = "200" ]; then
  curl -sf "$HEARTBEAT_URL" > /dev/null
else
  echo "WSO2 Admin API health check failed: HTTP ${GW_HEALTH}" >&2
fi

For real-time throughput monitoring, if you have WSO2 API Analytics with a Streaming Integrator, configure the Analytics dashboard URL as an additional HTTP monitor to ensure the analytics pipeline itself is operational.

Step 6: Monitor Traffic Manager Health

The Traffic Manager enforces rate limiting and throttling policies. If Traffic Manager sync fails, rate limits stop being enforced — either allowing traffic that should be throttled, or blocking traffic due to stale policy state:

#!/bin/bash
# /opt/wso2/scripts/check-traffic-manager.sh
WSO2_HOST="your-wso2-host"
WSO2_PORT="9443"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_TM_HEARTBEAT_ID"

# Check Traffic Manager JMX/management port
TM_HEALTH=$(curl -sf -o /dev/null -w "%{http_code}" -k \
  "https://${WSO2_HOST}:${WSO2_PORT}/throttle/data/v1/config" \
  --max-time 5 2>/dev/null || echo "000")

# Accept 200 or 401 (endpoint reachable, auth required — confirms TM is up)
if [ "$TM_HEALTH" = "200" ] || [ "$TM_HEALTH" = "401" ]; then
  curl -sf "$HEARTBEAT_URL" > /dev/null
else
  echo "Traffic Manager health check failed: HTTP ${TM_HEALTH}" >&2
fi

Step 7: Monitor Database Connectivity

WSO2 API Manager stores API metadata, subscription records, and configuration in MySQL or PostgreSQL. A database failure stops API publishing and subscription validation:

#!/bin/bash
# /opt/wso2/scripts/check-database.sh
DB_HOST="localhost"
DB_PORT="3306"  # MySQL; use 5432 for PostgreSQL
DB_NAME="apimgtdb"
DB_USER="wso2user"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_DB_HEARTBEAT_ID"

# MySQL check
if mysql -h "$DB_HOST" -P "$DB_PORT" -u "$DB_USER" \
   -p"$WSO2_DB_PASSWORD" "$DB_NAME" -e "SELECT 1" > /dev/null 2>&1; then
  curl -sf "$HEARTBEAT_URL" > /dev/null
else
  echo "WSO2 API Manager database connectivity check failed" >&2
fi

For PostgreSQL, replace the MySQL command with:

PGPASSWORD="$WSO2_DB_PASSWORD" psql -h "$DB_HOST" -p "$DB_PORT" \
  -U "$DB_USER" -d "$DB_NAME" -c "SELECT 1" > /dev/null 2>&1

Also add a direct TCP port monitor for port 3306 (MySQL) or 5432 (PostgreSQL):

  1. Click Add Monitor → TCP Port.
  2. Enter your database host and port.
  3. Set Check interval to 1 minute.
  4. Click Save.

Step 8: Monitor Analytics Pipeline Health

WSO2 API Analytics collects API usage data for billing, SLA monitoring, and business insights. Analytics data loss can affect billing accuracy and hide SLA violations:

#!/bin/bash
# /opt/wso2/scripts/check-analytics.sh
ANALYTICS_HOST="your-analytics-host"
ANALYTICS_PORT="9643"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_ANALYTICS_HEARTBEAT_ID"

# Check the Analytics Worker/Streaming Integrator management console
ANALYTICS_HEALTH=$(curl -sf -o /dev/null -w "%{http_code}" -k \
  "https://${ANALYTICS_HOST}:${ANALYTICS_PORT}/carbon/admin/login.jsp" \
  --max-time 10 2>/dev/null || echo "000")

if [ "$ANALYTICS_HEALTH" = "200" ]; then
  curl -sf "$HEARTBEAT_URL" > /dev/null
else
  echo "WSO2 Analytics health check failed: HTTP ${ANALYTICS_HEALTH}" >&2
fi

Step 9: Configure Alerting

With all monitors in place, configure alert routing for the right teams:

  1. In Vigilmon, click Alert Contacts → Add Contact.
  2. Add platform team email, Slack #api-platform channel webhook, or PagerDuty integration.
  3. Assign contacts to each monitor based on severity.

Recommended configuration:

| Monitor | Alert Sensitivity | Team | |---|---|---| | API Gateway TCP port | 1 failure | Platform on-call | | API Gateway health URL | 1 failure | Platform on-call | | Key Manager latency heartbeat | 2 missed pings | Platform on-call | | Developer Portal | 2 failures | Platform team | | API Publisher | 2 failures | Platform team | | Database TCP port | 1 failure | Platform on-call | | Traffic Manager heartbeat | 3 missed pings | Platform team | | Analytics heartbeat | 3 missed pings | Analytics team |

Conclusion

WSO2 API Manager is the gateway through which all your API traffic flows — every API consumer, every OAuth2 token validation, every rate limit decision passes through it. With Vigilmon monitoring the Gateway runtime, Key Manager token validation latency, Developer Portal and Publisher availability, database connectivity, and analytics pipeline health, you have end-to-end observability across your API management platform.

Start with the Gateway TCP port and health URL monitors (Step 1), add Key Manager latency tracking (Step 4), then layer in database and Traffic Manager health monitoring (Steps 6–7). Your API platform will have the same uptime visibility as the APIs it serves.

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