tutorial

Monitoring Port with Vigilmon: Developer Portal API Health, Agent Connectivity, and Self-Service Action Checks

How to monitor Port with Vigilmon — API health, developer portal availability, self-hosted agent connectivity, webhook action endpoints, and SSL certificate alerts.

Port is an internal developer portal platform for platform engineers and DevOps teams building software catalogs, developer self-service workflows, and scorecards. Engineering teams rely on Port's API server, the web app, and the self-hosted agent to keep their software catalog synchronized with real infrastructure state — tracking services, deployments, environments, dependencies, and compliance posture. When the Port API is unreachable, developers can't trigger self-service actions, run scaffolders, or query entity relationships. When the agent loses connectivity, catalog data drifts and becomes stale. Vigilmon gives you external, agent-free visibility into every Port availability surface before your developers feel the impact.

What You'll Build

  • An HTTP monitor on the Port API health endpoint to detect control plane failures
  • A web app availability check to confirm the developer portal UI is accessible
  • A self-hosted Port agent connectivity monitor
  • Webhook action endpoint checks for self-service workflows
  • SSL certificate monitoring for your Port installation

Prerequisites

  • A Port account with at least one entity catalog configured
  • A self-hosted Port agent (if using private infrastructure connectivity)
  • HTTPS configured for any self-hosted Port components (e.g., https://port-agent.example.com)
  • A free account at vigilmon.online

Step 1: Understand Port's API Endpoints

Port's REST API is the backbone of catalog reads, self-service action triggers, and scorecard evaluations. The primary API base is:

curl -s https://api.getport.io/v1/health
# Returns: {"ok":true}

For entity catalog checks that confirm the API is both up and able to serve data:

curl -s https://api.getport.io/v1/blueprints \
  -H "Authorization: Bearer $PORT_CLIENT_SECRET"
# Returns JSON array of blueprints

A healthy Port API returns HTTP 200. When the API is degraded, self-service actions queue without executing, scorecards stop refreshing, and ingestion pipelines report delivery failures.

Step 2: Create a Vigilmon HTTP Monitor for the Port API

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://api.getport.io/v1/health.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: ok (present in the health response body).
  7. Click Save.

This monitor catches:

  • Port API service outages or planned maintenance windows
  • Routing failures that prevent API traffic from reaching Port servers
  • Authentication gateway failures that block all API calls
  • Rate-limit or quota breaches that cause 429/503 responses
  • Regional availability issues affecting your engineers' geography

Alert sensitivity: Trigger after 1 consecutive failure. When the Port API is down, no self-service actions can execute and all CI/CD integrations that push catalog data lose their delivery target.

Step 3: Monitor the Port Developer Portal Web App

The Port web app is the primary interface for developers browsing the software catalog, inspecting scorecard results, and triggering self-service actions. Portal unavailability blocks the entire developer self-service experience:

curl -s https://app.getport.io | grep -i "Port"
# Returns HTML containing "Port"
  1. Add Monitor → HTTP.
  2. URL: https://app.getport.io.
  3. Check interval: 2 minutes.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: Port (present in the portal HTML).
  7. Label: Port Developer Portal.
  8. Click Save.

When the portal monitor fires but the API health monitor stays green, the issue is a frontend delivery failure — CDN misconfiguration, asset bundle failure, or a React hydration problem — not an API outage.

Step 4: Monitor the Self-Hosted Port Agent

The Port agent runs inside your private infrastructure and streams data from internal services (GitHub Enterprise, Kubernetes clusters, internal databases) into the Port catalog. If the agent goes down, catalog entities derived from private sources stop updating:

# Check agent health endpoint (exposed on the agent container's port)
curl http://port-agent.example.com:8000/health
# Returns: {"status":"ok","version":"0.x.y"}
  1. Add Monitor → HTTP.
  2. URL: https://port-agent.example.com/health (replace with your agent's exposed health URL).
  3. Check interval: 2 minutes.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: ok.
  7. Label: Port Agent Health.
  8. Click Save.

If you run multiple agents (one per environment or datacenter), create a separate monitor for each.

Step 5: Monitor Self-Service Action Webhook Endpoints

Port self-service actions trigger webhooks to your backend — Backstage scaffolders, GitHub Actions, internal provisioning APIs, or Crossplane compositions. If these webhook receivers are down, self-service action buttons appear in the UI but silently fail:

curl -s https://actions.example.com/healthz
# Returns: {"status":"healthy"}
  1. Add Monitor → HTTP.
  2. URL: https://actions.example.com/healthz (your webhook receiver's health endpoint).
  3. Check interval: 3 minutes.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: healthy.
  7. Label: Port Action Receiver.
  8. Click Save.

Step 6: Monitor SSL Certificates

Port's self-hosted agent and any webhook receivers use TLS. An expired certificate causes the Port backend to reject webhook payloads and the agent to fail its handshake with Port's API:

openssl s_client -connect port-agent.example.com:443 2>/dev/null | openssl x509 -noout -dates
  1. Add Monitor → SSL Certificate.
  2. Domain: port-agent.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 any additional webhook receiver domains.

Port agents often run in Kubernetes clusters managed by cert-manager with short-lived certificates (90 days or less). A 30-day alert window gives enough lead time for automated renewals to retry after cert-manager misconfiguration.

Step 7: Monitor the Port Webhooks Ingestion Endpoint

Port accepts inbound webhook events from external tools (GitHub, PagerDuty, Datadog) to update catalog entities in real time. If your ingestion webhooks stop being accepted, entity properties (deployment status, incident count, alert severity) drift from reality:

curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://ingest.getport.io/v1/integration/$PORT_INTEGRATION_ID/webhook \
  -H "Authorization: Bearer $PORT_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"test":true}'
# Returns: 200
  1. Add Monitor → HTTP.
  2. URL: https://api.getport.io/v1/health (use the general health endpoint as a proxy signal for ingestion availability).
  3. Monitor via your existing API health monitor or add a separate integration status check.
  4. Label: Port Ingestion Gateway.

Step 8: Configure Alerting

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

| Monitor | Trigger | Action | |---|---|---| | Port API /v1/health | Non-200 or keyword missing | Check Port status page; self-service actions are blocked | | Port web app | Non-200 or keyword missing | CDN/frontend failure; developers cannot access catalog | | Port agent health | Non-200 or keyword missing | Agent pod crash; private catalog sources stop syncing | | Webhook action receiver | Non-200 or keyword missing | Self-service actions silently fail; check receiver logs | | SSL certificate | < 30 days to expiry | Renew certificate; agent TLS handshake will fail at expiry |

Alert after: 1 consecutive failure for the API and agent monitors. 2 consecutive failures for web app and webhook receivers.

Common Port Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Port API service outage | API health monitor fires within 60 s; no actions can execute | | Port agent pod OOM killed | Agent health monitor fires; private catalog sources go stale | | Webhook receiver deployment failure | Action receiver monitor fires; self-service silently fails | | SSL cert expires on agent | SSL monitor alerts 30 days ahead; agent stops syncing at expiry | | GitHub webhook misconfiguration | Ingestion stops; entity properties drift (not caught by health, but by data drift checks) | | Port frontend CDN failure | Portal monitor fires; API health stays green | | Agent network policy change blocks egress | Agent health monitor fires; catalog sync stops | | Self-service action timeout under load | Action receiver response time increases; set Vigilmon timeout alert |

Port is the connective tissue between your platform engineering investment and your developers' day-to-day experience. When the API is down, self-service stops. When the agent disconnects, your software catalog goes stale. When action receivers fail, developers lose trust in the portal. Vigilmon gives you external visibility into every layer — API availability, portal rendering, agent connectivity, and webhook delivery — so platform engineering incidents are caught before developers open support tickets.

Start monitoring Port 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