How to Monitor Cortex Service Catalog with Vigilmon

Cortex is an engineering intelligence platform built around a service catalog — it tracks ownership, maturity scorecards, dependencies, and on-call schedules across your entire software estate. When Cortex is degraded or your integrations break, engineering teams lose the visibility they rely on to answer "who owns this?" during incidents and "how healthy is our software?" during planning.

This tutorial covers how to monitor Cortex and its surrounding integrations using Vigilmon — free tier, no credit card required.

Why Cortex monitoring matters

Cortex is often invisible until it breaks. Teams build workflows around it:

• On-call handoff lookups — engineers check Cortex to find the right team during an incident; a stale or unreachable catalog causes dangerous delays
• Scorecard-driven gates — CI/CD pipelines and promotion workflows that query Cortex scorecards will fail silently if the API is down
• Integration pipelines — Cortex ingests data from GitHub, PagerDuty, Datadog, and cloud providers; if those syncs stop, scorecard data goes stale
• GitOps entity descriptors — cortex.yaml descriptor pushes from repositories power entity updates; a broken webhook breaks catalog accuracy

External monitoring catches these failures independently of Cortex's own health checks.

What you'll need

• A Cortex account and API key (Settings → API Keys in your Cortex dashboard)
• A free Vigilmon account

Step 1: Map what to monitor

Cortex has several layers worth monitoring independently:

| Component | Endpoint type | Why it matters | |-----------|--------------|----------------| | Cortex API | HTTP | Powers all catalog queries and scorecard reads | | GitOps webhook receiver | HTTP | Receives cortex.yaml pushes from GitHub/GitLab | | Cortex UI | HTTP | What engineers open during incidents | | Integration sync jobs | Heartbeat | Confirm PagerDuty, Datadog, GitHub syncs are running |

Step 2: Monitor the Cortex API

Cortex's REST API powers every programmatic catalog lookup. Set up an authenticated HTTP monitor:

1. Log in to vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS
3. Use the Cortex catalog API endpoint — for example, list all services:

   https://api.getcortexapp.com/api/v1/catalog/entities
   

4. Add your API key as a request header:

   Authorization: Bearer <your_cortex_api_key>
   

5. Set expected status code to 200
6. Set the check interval to 1 minute
7. Save the monitor

This confirms that the Cortex API is reachable and authenticated requests succeed — covering both Cortex-side outages and network path issues from your environment.

Step 3: Monitor your GitOps webhook receiver

If you use cortex.yaml descriptor files in your repositories, Cortex receives pushes via webhooks from your source control provider. Monitor the webhook endpoint to catch receiver downtime:

1. Add an HTTP monitor for your webhook receiver URL
2. If Cortex is SaaS, the receiver is on Cortex's infrastructure — monitor https://api.getcortexapp.com for a baseline health check
3. If you use a custom relay or middleware between GitHub and Cortex, monitor that relay:

# Example: Cortex descriptor in your repo
apiVersion: cortex.io/v1alpha1
kind: Service
metadata:
  name: payments-service
  x-cortex-tag: payments
  x-cortex-owners:
    - type: group
      name: payments-team
  x-cortex-oncall:
    pagerduty:
      id: P1234AB
      type: service

When your relay or webhook receiver is down, pushes from CI fail silently and the catalog drifts from reality.

Step 4: Set up heartbeat monitors for integration sync jobs

Cortex syncs data from external tools on a schedule. If those syncs stop, scorecard data becomes stale. Add heartbeat monitors for each integration:

1. Go to Monitors → New Monitor → Heartbeat
2. Create one heartbeat per integration:
   • "Cortex PagerDuty sync"
   • "Cortex GitHub sync"
   • "Cortex Datadog metrics sync"
3. Set intervals matching each integration's expected sync frequency
4. Add the heartbeat ping to the end of each sync script or cron job:

#!/bin/bash
# sync_pagerduty_to_cortex.sh

# Run the sync
python sync_pagerduty.py --cortex-api-key "$CORTEX_API_KEY"

# Signal success
curl -fsS "$VIGILMON_HEARTBEAT_PAGERDUTY_SYNC" > /dev/null

Step 5: Monitor scorecard query latency

If you have pipelines or dashboards that query Cortex scorecards at build time, slow responses are as damaging as outages. Add a response-time threshold to your API monitor:

1. Edit your Cortex API monitor in Vigilmon
2. Under Response time, set a threshold alert at 3000ms — a scorecard query taking more than 3 seconds indicates a performance regression
3. Save

This catches degradation that doesn't cause HTTP errors but still breaks CI pipelines that time out waiting for scorecard responses.

Step 6: Configure targeted alerts

Cortex monitoring alerts should route based on severity:

For the API monitor (immediate impact):

1. Go to Alert Channels → Add Channel → Slack
2. Route to #platform-oncall with a high-priority mention
3. Optionally integrate with PagerDuty for after-hours coverage

For integration sync heartbeats (delayed impact):

1. Route to #platform-alerts in Slack
2. Use email for non-urgent sync job failures

For the Cortex UI (user-facing):

1. Route to #engineering in Slack so teams know to use alternate paths during an incident

Recommended thresholds:

| Monitor | Alert after | |---------|-------------| | Cortex API | 1 failure | | Webhook receiver / relay | 2 consecutive failures | | Integration sync heartbeat | 1 missed interval | | Cortex UI | 2 consecutive failures | | API response time | Exceeds 3000ms |

Step 7: Create a platform reliability status page

Publish a status page that shows the health of your Cortex integration to other engineering teams:

1. Go to Status Pages → New Status Page in Vigilmon
2. Add monitors: Cortex API, webhook receiver, sync heartbeats
3. Name it "Engineering Platform Health" and publish
4. Link it from your engineering wiki and the Cortex portal itself

Teams can check this page instead of filing a Slack message every time something feels off.

Key Cortex-specific signals to watch

Beyond uptime, track these Cortex-specific leading indicators:

• Entity lastUpdated timestamps — if Cortex entities haven't updated in 24h+ during active development, a sync pipeline is broken
• Scorecard unknown entries — components showing "unknown" for a metric often mean the integration feeding that metric stopped
• Webhook delivery retries — Cortex logs webhook retries; a spike in retries means your relay or receiver is intermittently failing
• API 401 errors — token rotation without updating Cortex's stored credentials causes cascading catalog staleness

What's next

• SSL monitoring — ensure TLS certificates on your webhook relay and custom integrations are valid; Vigilmon alerts before expiry
• Multi-region monitoring — if your engineering teams are distributed, verify Cortex API reachability from each major region
• Incident history reports — use Vigilmon's incident data to build quarterly reliability reports for your platform team

Get started free at vigilmon.online — no credit card, monitors go live in seconds.