tutorial

Monitoring Port.io with Vigilmon: API Health, Blueprint Availability, Scorecard Status & Ingestion Pipeline Heartbeats

How to monitor Port.io (developer portal and internal developer platform) with Vigilmon — API health checks, blueprint catalog availability, scorecard status, SSL certificate monitoring, and ingestion pipeline heartbeats.

Port.io is a developer portal and internal developer platform (IDP) that lets platform teams build software catalogs, scorecards, self-service actions, and developer workflows without custom tooling. Port's API server powers the software catalog, blueprints define the data model for services and environments, and ingestion pipelines keep catalog data synchronized with external systems like GitHub, Jira, and Kubernetes. A degraded Port API blocks developers from accessing service ownership data, failed blueprint ingestion leaves the catalog stale and unreliable, and a broken scorecard engine prevents teams from tracking production readiness standards. Vigilmon gives you external visibility into Port's API health, blueprint catalog availability, scorecard status, SSL certificates, and ingestion pipeline heartbeats so you catch failures before they erode trust in your developer portal.

What You'll Build

  • A monitor on the Port.io API health endpoint
  • A blueprint catalog availability check via the Port REST API
  • A scorecard status check via keyword matching
  • SSL certificate monitoring for the Port.io API endpoint
  • A heartbeat monitor confirming scheduled ingestion pipeline jobs complete on time

Prerequisites

  • A Port.io account with API access enabled
  • Port API accessible over HTTPS at api.getport.io
  • A free account at vigilmon.online

Step 1: Verify the Port.io API Health Endpoint

Port.io exposes an API status endpoint confirming the server is operational:

curl https://api.getport.io/v1/health

A healthy Port API returns:

{"status":"ok","message":"Port is up and running"}

This confirms the Port API server is alive and accepting requests.

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: 10 seconds.
  5. Expected status: 200.
  6. Keyword: ok.
  7. Label: Port.io API Health.
  8. Click Save.

Set alerts to trigger after 2 consecutive failures — Port.io is a cloud-managed SaaS platform; a single failure may be a transient network blip, while two consecutive failures indicate a genuine outage.

Step 3: Monitor the Blueprint Catalog

Port's blueprint system defines the data model for all entities in your software catalog — services, teams, environments, deployments, and more. When the blueprints endpoint is unavailable, developers cannot view or interact with catalog data:

curl https://api.getport.io/v1/blueprints \
  -H "Authorization: Bearer your-access-token"

A healthy response returns an array of blueprint definitions:

{"blueprints":[{"identifier":"service","title":"Service"},{"identifier":"environment","title":"Environment"}]}

Add a monitor using keyword matching:

  1. Add Monitor → HTTP.
  2. URL: https://api.getport.io/v1/blueprints.
  3. Check interval: 5 minutes.
  4. Expected status: 200.
  5. Keyword: blueprints.
  6. HTTP Headers: Authorization: Bearer your-access-token.
  7. Label: Port.io Blueprint Catalog.
  8. Click Save.

Access token: Generate a Port API token via Settings → Credentials in the Port.io dashboard. Tokens are long-lived and suitable for monitoring header authentication.

Step 4: Monitor Entity Availability

Port entities are the catalog records for each service, team, and environment in your organization. An unavailable entity endpoint means developers cannot find service ownership, check runbooks, or trigger self-service actions:

curl "https://api.getport.io/v1/blueprints/service/entities?limit=1" \
  -H "Authorization: Bearer your-access-token"

A healthy response returns entity records or an empty array:

{"entities":[]}

Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://api.getport.io/v1/blueprints/service/entities?limit=1.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: entities.
  6. Label: Port.io Entity Catalog.
  7. Click Save.

Replace service with your primary blueprint identifier if it differs.

Step 5: Monitor Scorecard Availability

Port scorecards track production readiness, DevOps maturity, and compliance standards across all services in your catalog. When the scorecard engine fails, teams lose visibility into which services meet standards and which require remediation:

curl https://api.getport.io/v1/blueprints/service/scorecards \
  -H "Authorization: Bearer your-access-token"

A healthy response includes scorecard definitions:

{"scorecards":[{"identifier":"production-readiness","title":"Production Readiness"}]}

Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://api.getport.io/v1/blueprints/service/scorecards.
  3. Check interval: 5 minutes.
  4. Expected status: 200.
  5. Keyword: scorecards.
  6. Label: Port.io Scorecards.
  7. Click Save.

Step 6: Set Up Ingestion Pipeline Heartbeat Monitoring

Port.io catalogs are kept fresh by ingestion pipelines that sync data from GitHub, GitLab, Jira, Kubernetes, and other systems. A silently failed ingestion pipeline leaves the catalog showing stale service ownership, outdated deployment statuses, or missing entities — eroding developer trust over time. Use Vigilmon heartbeat monitoring to confirm ingestion jobs complete on schedule:

Step 6a — Create a Heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Name: Port.io GitHub ingestion pipeline.
  3. Expected interval: 1 hour (or match your ingestion schedule).
  4. Grace period: 15 minutes.
  5. Copy the generated ping URL (e.g., https://vigilmon.online/ping/abc123).

Step 6b — Add a ping step to your ingestion workflow:

# GitHub Actions example — Port.io catalog ingestion
- name: Ingest services from GitHub to Port
  run: |
    # Use Port's GitHub Action or direct API calls to sync entities
    curl -X POST https://api.getport.io/v1/blueprints/service/entities/upsert \
      -H "Authorization: Bearer ${{ secrets.PORT_ACCESS_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"identifier":"my-service","title":"My Service","properties":{"language":"typescript"}}'

- name: Notify Vigilmon on success
  run: curl -fsS -m 10 https://vigilmon.online/ping/abc123

For Port's official GitHub app, add the Vigilmon ping as a final step in the workflow:

# At the end of your Port integration script
curl -fsS -m 10 https://vigilmon.online/ping/abc123

If the ingestion job fails before reaching the ping step, Vigilmon fires an alert after the grace period expires, surfacing stale catalog data before developers notice.

Step 7: Monitor SSL Certificates

Port.io is a SaaS platform with TLS managed by their infrastructure. If you deploy a self-hosted Port gateway or proxy (e.g., for on-premises integration), monitor its SSL certificate:

  1. Add Monitor → SSL Certificate.
  2. Domain: api.getport.io (or your self-hosted gateway domain).
  3. Alert when expiry is within: 30 days.
  4. Alert again at: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

Step 8: Configure Alerting

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

| Monitor | Trigger | Action | |---|---|---| | API health | Non-200 or ok missing | Check Port.io status page; contact Port support | | Blueprint catalog | Non-200 or blueprints absent | Catalog degraded; developer portal views broken | | Entity catalog | Non-200 or entities absent | Entity data unavailable; service pages broken | | Scorecards | Non-200 or scorecards absent | Scorecard engine down; readiness tracking stalled | | Ingestion heartbeat | No ping within window | Pipeline failed; catalog data is stale | | SSL certificate | < 30 days | Renew; verify TLS config on self-hosted components |

Common Port.io Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Port.io API outage | Health endpoint unreachable; alert within 60 s | | Blueprint endpoint degraded | Blueprint monitor fires; catalog views fail | | Entity data unavailable | Entity monitor fires; service pages return errors | | Scorecard engine failure | Scorecard monitor fires; readiness tracking stalls | | GitHub ingestion pipeline fails | Heartbeat monitor alerts; catalog shows stale data | | API token expires in CI | All API monitors return 401; alert immediately | | SSL certificate expires | SSL monitor alerts at 30-day threshold | | Port.io rate limit hit | API monitors return 429; ingestion pipeline stalls |

Port.io's value as a developer portal depends entirely on catalog freshness and API reliability — stale entity data erodes developer trust faster than an outage does, because developers don't notice until they've already acted on outdated information. Vigilmon's layered monitoring of the API health, blueprint catalog, entity availability, scorecard engine, ingestion pipeline heartbeats, and SSL certificates gives you external visibility across every layer of Port's developer portal infrastructure, so you catch failures before they degrade your organization's service catalog.

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