tutorial

Monitoring Cortex Engineering Intelligence with Vigilmon: Service Catalog API Health, Scorecard Availability, and Integration Checks

How to monitor Cortex engineering intelligence platform with Vigilmon — API health, service catalog availability, scorecard endpoint checks, webhook receivers, and SSL certificate alerts.

Cortex is a cloud-native engineering intelligence platform that gives platform engineering teams a service catalog, software quality scorecards, developer insights, and initiative tracking across their entire engineering organization. CTOs and platform engineers rely on Cortex's API, dashboard, and integrations — with GitHub, PagerDuty, Datadog, and Kubernetes — to measure software quality, track adoption of platform standards, and give developers a single pane of glass for service ownership. When the Cortex API is unreachable, scorecard data stops refreshing, on-call ownership queries fail, and developers can't look up service documentation. Vigilmon gives you external, agent-free monitoring of every Cortex availability surface.

What You'll Build

  • An HTTP monitor on the Cortex API to detect catalog and scorecard availability failures
  • A dashboard availability check to confirm the web UI is accessible for developers
  • A webhook receiver monitor for Cortex integration event delivery
  • SSL certificate monitoring for Cortex-connected internal services
  • An alerting setup that distinguishes API failures from integration degradation

Prerequisites

  • A Cortex account with a service catalog and at least one integration configured
  • API credentials (your Cortex API token) for authenticated endpoint checks
  • A free account at vigilmon.online

Step 1: Understand Cortex's API Structure

Cortex exposes a REST API for querying service catalog entities, scorecard results, and integration status. The primary base URL is:

curl -s https://api.getcortexapp.com/api/v1/catalog/entities \
  -H "Authorization: token $CORTEX_API_TOKEN"
# Returns JSON array of catalog entities

For a lightweight availability probe that doesn't require full entity enumeration:

curl -s -o /dev/null -w "%{http_code}" \
  "https://api.getcortexapp.com/api/v1/catalog/entities?pageSize=1" \
  -H "Authorization: token $CORTEX_API_TOKEN"
# Returns: 200

A healthy Cortex API returns 200. When Cortex is degraded, scorecard evaluations stop, GitHub sync jobs fail, and on-call lookups return stale data. Because Cortex aggregates data from many integrations, partial degradation — where the API is up but a specific integration feed is broken — is a common failure mode.

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

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://api.getcortexapp.com/api/v1/catalog/entities?pageSize=1.
  3. Check interval: 60 seconds.
  4. Response timeout: 20 seconds.
  5. Expected status: 200.
  6. HTTP Headers: add Authorization: token YOUR_CORTEX_API_TOKEN.
  7. Keyword: entityTag (present in the catalog entity response).
  8. Click Save.

This monitor catches:

  • Cortex API service outages or degraded availability windows
  • Authentication token expiry that blocks all API access
  • Platform-wide rate-limit responses that prevent catalog queries
  • Integration pipeline failures that cause API timeouts on entity retrieval
  • Regional routing issues affecting your engineering team's geography

Alert sensitivity: Trigger after 1 consecutive failure. When the Cortex API is down, engineering dashboards go dark, scorecard data becomes stale, and platform adoption metrics stop flowing.

Step 3: Monitor the Cortex Dashboard

The Cortex dashboard is the primary web interface for engineers checking service ownership, inspecting scorecards, and browsing the software catalog. Dashboard unavailability prevents developers from accessing on-call contacts, runbooks, and architecture documentation:

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

When the dashboard monitor fires but the API monitor stays green, the failure is in the frontend delivery layer — CDN, asset build, or SPA routing — not the catalog data API. These are different on-call paths.

Step 4: Monitor Cortex Scorecard Endpoints

Cortex scorecards are the core engineering quality measurement — they evaluate services against custom rules (test coverage, on-call configuration, documentation completeness, SLO adherence). Scorecard API availability is distinct from the entity catalog API:

curl -s https://api.getcortexapp.com/api/v1/scorecards \
  -H "Authorization: token $CORTEX_API_TOKEN"
# Returns JSON array of scorecard definitions
  1. Add Monitor → HTTP.
  2. URL: https://api.getcortexapp.com/api/v1/scorecards.
  3. Check interval: 3 minutes.
  4. Response timeout: 20 seconds.
  5. Expected status: 200.
  6. HTTP Headers: add Authorization: token YOUR_CORTEX_API_TOKEN.
  7. Keyword: tag (present in scorecard JSON).
  8. Label: Cortex Scorecards API.
  9. Click Save.

Scorecard evaluations run on a schedule and pull data from integrations. If the scorecards API is healthy but a specific integration (GitHub, Datadog) is disconnected, scores silently become stale — caught not by API health checks but by comparing evaluation timestamps in your catalog entity responses.

Step 5: Monitor the Cortex Webhook Integration Receiver

Cortex accepts inbound webhooks from GitHub, PagerDuty, Opsgenie, and other tools to keep service ownership and incident data current in real time. If your webhook delivery fails, on-call assignments stop updating and incident data goes stale:

# Test a Cortex webhook endpoint (replace with your specific integration webhook URL)
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.getcortexapp.com/api/v1/webhooks/pagerduty \
  -H "Authorization: token $CORTEX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":{"type":"ping"}}'
# Returns: 200
  1. Add Monitor → HTTP.
  2. URL: https://api.getcortexapp.com/api/v1/catalog/entities?pageSize=1 (use the general API health as the integration gateway proxy signal).
  3. Configure separate uptime monitors for webhook receiver infrastructure if self-hosted.
  4. Label: Cortex Webhook Gateway.

For teams running a self-hosted Cortex integration proxy, add:

  1. URL: https://cortex-proxy.example.com/healthz.
  2. Check interval: 2 minutes.
  3. Expected status: 200.
  4. Label: Cortex Integration Proxy.

Step 6: Monitor SSL Certificates for Cortex-Connected Services

Many Cortex integrations connect to internal services over HTTPS — internal GitHub Enterprise instances, self-hosted PagerDuty connectors, or internal Kubernetes API servers. An expired certificate on any of these breaks Cortex's data sync:

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

Cortex polls GitHub on a short cycle for pull request activity, code coverage, and deployment events. When the internal GitHub TLS certificate expires, Cortex silently stops receiving this data — scorecard rules based on GitHub metrics start failing across all services simultaneously.

Step 7: Monitor On-Call Team API Lookups

Cortex's on-call ownership feature queries PagerDuty and Opsgenie to surface who is on call for each service. This data powers incident routing and severity triage dashboards. When on-call lookups fail, engineers escalating incidents must manually look up ownership:

curl -s https://api.getcortexapp.com/api/v1/teams \
  -H "Authorization: token $CORTEX_API_TOKEN"
# Returns JSON list of teams with ownership mappings
  1. Add Monitor → HTTP.
  2. URL: https://api.getcortexapp.com/api/v1/teams.
  3. Check interval: 5 minutes.
  4. Response timeout: 20 seconds.
  5. HTTP Headers: add Authorization: token YOUR_CORTEX_API_TOKEN.
  6. Expected status: 200.
  7. Keyword: tag (present in team response).
  8. Label: Cortex Teams API.
  9. Click Save.

Step 8: Configure Alerting

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

| Monitor | Trigger | Action | |---|---|---| | Cortex catalog API | Non-200 or keyword missing | Cortex service incident; check Cortex status page | | Cortex dashboard | Non-200 or keyword missing | Frontend failure; API may still be healthy | | Cortex scorecards API | Non-200 or keyword missing | Scorecard evaluation blocked; check Cortex API status | | Cortex teams API | Non-200 or keyword missing | On-call ownership data unavailable; manual escalation needed | | SSL certificate | < 30 days to expiry | Renew certificate; integration sync stops at expiry |

Alert after: 1 consecutive failure for the catalog and teams API monitors. 2 consecutive failures for the dashboard and scorecards API monitors.

Common Cortex Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Cortex API service outage | Catalog API monitor fires within 60 s | | API token expiry | Monitor returns 401; caught by keyword check failure | | Scorecard evaluation stuck | Scorecards API returns 200 but job queue is stalled (add a data-freshness check) | | GitHub integration disconnected | GitHub SSL/connectivity monitor fires; scorecard metrics go stale | | Dashboard CDN failure | Dashboard monitor fires; API monitor stays green | | On-call data goes stale | Teams API monitor detects availability; staleness requires timestamp logic | | PagerDuty webhook stops delivering | Inbound webhook gateway health check fires | | Integration proxy TLS expiry | SSL monitor alerts 30 days ahead |

Cortex is the engineering intelligence layer that keeps your platform standards enforced, your service ownership clear, and your incident response fast. When the API is down, scorecards freeze and on-call lookups fail. When integrations disconnect, the catalog drifts from reality. Vigilmon gives you continuous external visibility into Cortex availability — API health, dashboard rendering, scorecard endpoints, and the SSL certificates that keep integrations alive — so engineering intelligence stays current when it matters most.

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