Monitoring Permify with Vigilmon

Permify is an open source fine-grained authorization service built on Google's Zanzibar model. Instead of scattering permission logic across every microservice, teams centralize it: store relationship tuples ("user A is owner of document B"), define a schema, and call Permify's check API to answer "is user X allowed to do Y?" at every access point. That centralization is powerful — but it also means Permify becomes a critical shared dependency. If Permify is slow, every authorization check in every upstream service slows down. If it's down, access checks fail across the board. Vigilmon monitors Permify's HTTP API, gRPC server, database, and Redis cache so you know about degradation before your applications do.

What You'll Set Up

• HTTP API health endpoint monitor (GET /healthz)
• gRPC server port availability check (port 3476)
• Authorization check API response time monitoring
• Schema write API health check
• Relationship write API health check
• PostgreSQL/MongoDB database connectivity monitor
• Redis cache availability monitor
• TLS certificate expiry alerts

Prerequisites

• Permify running and accessible (default ports: 3476 for gRPC, 3478 for HTTP API)
• HTTP API reachable at https://permify.yourdomain.com or http://localhost:3478
• A free Vigilmon account

Step 1: Monitor the HTTP API Health Endpoint

Permify exposes GET /healthz as its canonical health check. This is your primary uptime signal.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. URL: https://permify.yourdomain.com/healthz (or http://localhost:3478/healthz if not behind a reverse proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

A healthy Permify returns 200 from /healthz with a JSON body indicating service readiness. If Permify is starting up, connecting to the database, or in a degraded state, this endpoint returns a non-200 status — exactly what you want to detect.

Step 2: Monitor the gRPC Server (Port 3476)

Permify's primary interface for production authorization checks is gRPC on port 3476. Most applications use the gRPC API because it's lower latency than HTTP for the high-frequency check calls that authorization requires.

1. Click Add Monitor → TCP Port.
2. Host: your Permify server's hostname or IP.
3. Port: 3476.
4. Interval: 1 minute.
5. Save.

This TCP check confirms the gRPC listener is up. If Permify crashes or the gRPC server fails to bind (port conflict, OOM), this monitor triggers before your applications start reporting unavailable errors from the gRPC client.

Step 3: Monitor Authorization Check API Response Times

The check API — POST /v1/tenants/:tenantId/permissions/check — is Permify's most latency-sensitive endpoint. It's called on every user action that requires an access gate. Slow authorization checks translate directly into slow application responses for every user.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://permify.yourdomain.com/v1/tenants/YOUR_TENANT_ID/permissions/check
3. Method: POST
4. Set a request body with a minimal test check:

{
  "metadata": {
    "schema_version": "",
    "snap_token": "",
    "depth": 20
  },
  "entity": {
    "type": "document",
    "id": "health-check-doc"
  },
  "permission": "view",
  "subject": {
    "type": "user",
    "id": "health-check-user"
  }
}

5. Add a header: Content-Type: application/json and your authorization header if required.
6. Expected status: 200.
7. Interval: 2 minutes.
8. Save.

This check validates that the authorization engine is executing — not just that the HTTP listener is up. Set up a dedicated test entity and user in Permify for monitoring purposes so the health check tuple always exists and the check always returns a deterministic result.

Step 4: Monitor the Schema Write API

The schema write API — POST /v1/tenants/:tenantId/schemas/write — defines the authorization model (entity types, relations, permissions). Schema writes happen infrequently, but if this endpoint is degraded when you need to push a schema change, your authorization model is stuck.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://permify.yourdomain.com/v1/tenants/YOUR_TENANT_ID/schemas/write
3. Method: POST
4. Body:

{
  "schema": "entity user {}\nentity document {\n  relation owner @user\n  permission view = owner\n}"
}

5. Authorization header if required.
6. Expected status: 200.
7. Interval: 5 minutes.
8. Save.

Writing the same minimal health-check schema repeatedly is safe — Permify is idempotent on schema writes for the same definition. This confirms the schema pipeline (API → database write) is functioning end to end.

Step 5: Monitor the Relationship Write API

The relationship write API — POST /v1/tenants/:tenantId/data/write — stores relationship tuples ("user A is viewer of document B"). These tuples are the raw data behind every permission check. If writes are failing, your system's permission state is drifting from reality.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://permify.yourdomain.com/v1/tenants/YOUR_TENANT_ID/data/write
3. Method: POST
4. Body:

{
  "metadata": {
    "schema_version": ""
  },
  "tuples": [
    {
      "entity": {
        "type": "document",
        "id": "health-check-doc"
      },
      "relation": "owner",
      "subject": {
        "type": "user",
        "id": "health-check-user"
      }
    }
  ]
}

5. Expected status: 200.
6. Interval: 5 minutes.
7. Save.

Writing the same tuple repeatedly is safe since Permify deduplicates relationship tuples. This validates that the write path to the database is functioning.

Step 6: Monitor PostgreSQL or MongoDB

Permify stores relationship tuples and schema definitions in either PostgreSQL or MongoDB. A database failure means check queries start failing as the in-memory cache ages out and Permify can't refresh from the source of truth.

For PostgreSQL:

1. Click Add Monitor → TCP Port.
2. Host: your PostgreSQL server hostname or IP.
3. Port: 5432.
4. Interval: 2 minutes.
5. Save.

For MongoDB:

1. Click Add Monitor → TCP Port.
2. Host: your MongoDB server.
3. Port: 27017.
4. Interval: 2 minutes.
5. Save.

If your database is on a private network not reachable from Vigilmon's probes, use a cron heartbeat instead: schedule a database connectivity check on the Permify host and ping Vigilmon's heartbeat URL on success.

#!/bin/bash
# Check Permify's PostgreSQL connectivity via the health endpoint
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
  https://permify.yourdomain.com/healthz)

if [ "$RESPONSE" = "200" ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_TOKEN
fi

Step 7: Monitor Redis Cache Connectivity

Permify caches permission check results in Redis to avoid re-evaluating the same tuple graph on every request. When Redis is unreachable, Permify falls back to evaluating every check against the database — this significantly increases check latency and database load under high traffic.

1. Click Add Monitor → TCP Port.
2. Host: your Redis server hostname or IP.
3. Port: 6379.
4. Interval: 1 minute.
5. Save.

Redis connectivity issues are often the first symptom of broader infrastructure problems (network partition, memory pressure, container restart). Detecting Redis loss early lets you scale database read capacity proactively before the latency impact reaches users.

Step 8: TLS Certificate Expiry Monitoring

If Permify's HTTP API is exposed over HTTPS, enable SSL certificate monitoring on your main health check monitor:

1. Open the HTTP monitor for https://permify.yourdomain.com/healthz.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Save.

Authorization services often run on internal networks where TLS certificate management gets less attention than public-facing services. An expired certificate causes gRPC and HTTP clients to start throwing TLS errors simultaneously — set the 21-day alert to stay well ahead of this.

Step 9: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or PagerDuty.
2. For the /healthz monitor and the gRPC port monitor, set Consecutive failures before alert to 2 — Permify restart takes a few seconds during deployments.
3. For the Redis monitor, set Consecutive failures before alert to 1 — Redis loss degrades performance immediately and warrants prompt attention.
4. For the TLS certificate monitor, set Consecutive failures before alert to 1.

Route the gRPC port monitor and /healthz monitor to your on-call rotation. Route the schema write and relationship write monitors to a secondary channel — they're important but typically not the reason users notice an outage.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP health | GET /healthz | Permify down or not ready | | TCP port 3476 | gRPC server | gRPC listener down | | Check API | POST /permissions/check | Authorization engine degraded | | Schema API | POST /schemas/write | Schema write path broken | | Data write API | POST /data/write | Tuple write path broken | | TCP port 5432 / 27017 | PostgreSQL / MongoDB | Database unreachable | | TCP port 6379 | Redis | Cache down, latency spike | | SSL certificate | HTTPS endpoint | TLS expiry |

Permify centralizes authorization so your applications can stay simple — but that centralization makes it a single point of failure your whole stack depends on. With Vigilmon checking the health endpoint, gRPC port, cache layer, and database, degradation shows up as a Slack alert rather than a cascade of permission denied errors across every service in your infrastructure.