tutorial

Monitoring Apicurio Registry with Vigilmon

Apicurio Registry is the open-source schema registry powering event-driven architectures — here's how to monitor server health, schema compatibility violations, resolution latency, and storage backends with Vigilmon.

Apicurio Registry is the open-source, vendor-neutral schema and API registry that event-driven architectures depend on. Every Kafka producer serializing an Avro message and every consumer deserializing it calls Apicurio to resolve the schema — if Apicurio goes down or slows down, your entire messaging pipeline stalls. Vigilmon gives you continuous visibility into Apicurio server health, storage backend connectivity, schema resolution latency, and compatibility rule enforcement before a silent registry failure cascades across your microservices.

What You'll Set Up

  • HTTP health checks for Apicurio's liveness and readiness probes
  • Storage backend connectivity monitoring (KafkaSQL or PostgreSQL)
  • Schema resolution latency alerting
  • Compatibility rule violation tracking
  • Confluent-compatible API endpoint health
  • Web console availability monitoring
  • Kafka topic lag alerts for KafkaSQL deployments

Prerequisites

  • Apicurio Registry 2.x or later deployed (Docker, Kubernetes, or bare metal)
  • Apicurio accessible over HTTP/HTTPS
  • A free Vigilmon account

Why Monitoring Apicurio Registry Matters

Apicurio Registry sits at the critical path of every event your system produces or consumes. Schema resolution happens at serialization time — a Kafka producer cannot publish a message if it cannot fetch the schema, and a consumer cannot deserialize a message if Apicurio is unavailable. Unlike most services where downtime causes degraded performance, an unmonitored Apicurio outage causes silent data loss: producers fail, messages are dropped, and consumer lag accumulates before anyone notices.

Schema compatibility enforcement adds another monitoring dimension. When a breaking schema change is rejected by Apicurio's compatibility rules, that rejection is correct behavior — but it signals that a developer attempted a backward-incompatible change that would have broken consumers in production. You want to know about this immediately.

The KafkaSQL storage backend adds Kafka consumer group lag as an operational concern: if Apicurio's internal consumer group falls behind on the storage topic, schema writes are not acknowledged and producers block.

Step 1: Monitor Apicurio Server Liveness and Readiness

Apicurio exposes standard MicroProfile Health endpoints. Add two Vigilmon monitors — one for liveness (is the process alive?) and one for readiness (is the registry ready to serve requests?):

Readiness probe:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter URL: https://your-apicurio-host/health/ready
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Alert conditions, set Alert after to 1 failure.
  7. Click Save.

Liveness probe:

Repeat the above with URL: https://your-apicurio-host/health/live

A readiness failure means the registry is not accepting schema requests. An alert here gives you time to restart Apicurio or fail over to a replica before producers start dropping messages.

Step 2: Monitor Schema Storage Backend Health

Apicurio's data durability depends on its storage backend. A storage failure causes all schema writes to fail, which blocks any service registering a new schema version.

PostgreSQL backend

If you are using the SQL storage backend (PostgreSQL), add a TCP port monitor for your PostgreSQL server:

  1. Click Add Monitor → set Type to TCP Port.
  2. Enter Host: your-postgres-host and Port: 5432.
  3. Set Check interval to 1 minute.
  4. Enable alerts on connection failure.
  5. Click Save.

KafkaSQL backend

For KafkaSQL deployments, monitor the Kafka broker:

  1. Click Add Monitor → set Type to TCP Port.
  2. Enter Host: your-kafka-broker and Port: 9092.
  3. Set Check interval to 1 minute.
  4. Enable alerts on connection failure.
  5. Click Save.

If Kafka becomes unreachable, Apicurio cannot persist schema changes. Combine this with the readiness probe: if Kafka goes down, Apicurio will eventually fail its readiness check too.

Step 3: Monitor the Confluent-Compatible API Endpoint

Apicurio exposes a Confluent Schema Registry-compatible API at /apis/ccompat/v7. Kafka producers and consumers configured with schema.registry.url pointing to Apicurio use this endpoint. If it becomes unhealthy while the main Apicurio API is up (a partial failure mode that happens during upgrades), Confluent-native clients will fail while Apicurio-native clients continue to work.

  1. Click Add Monitor → set Type to HTTP / HTTPS.
  2. Enter URL: https://your-apicurio-host/apis/ccompat/v7
  3. Set Check interval to 1 minute.
  4. Set Expected HTTP status to 200.
  5. Click Save.

This endpoint returns an empty subjects list by default, which gives a 200 response — making it a clean synthetic health check for Confluent-compatible clients.

Step 4: Monitor the Apicurio Web Console

The Apicurio web console lets your schema team browse artifacts, inspect schema versions, and manually register schemas. A console outage blocks schema management workflows even when the REST API is healthy.

  1. Click Add Monitor → set Type to HTTP / HTTPS.
  2. Enter URL: https://your-apicurio-host/ui
  3. Set Check interval to 5 minutes.
  4. Set Expected HTTP status to 200.
  5. Click Save.

Step 5: Monitor the Apicurio REST API Error Rate

Add a keyword-based check on the Apicurio REST API metrics endpoint to catch rising 5xx error rates. If Apicurio exposes Prometheus metrics (via the /q/metrics endpoint in the Quarkus-based server), you can create a monitor that fetches this page and checks for expected content:

  1. Click Add Monitor → set Type to HTTP / HTTPS.
  2. Enter URL: https://your-apicurio-host/q/metrics
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200.
  5. Under Keyword check, add apicurio_rest_requests_total to confirm the metrics endpoint is publishing data.
  6. Click Save.

For detailed 5xx rate alerting, configure your metrics pipeline (Prometheus + Alertmanager) to consume these metrics and page on rate(apicurio_rest_requests_total{status=~"5.."}[5m]) > 0.01.

Step 6: Configure Schema Resolution Latency Alerts

Schema resolution latency is invisible until it becomes a problem. Kafka producers call Apicurio at serialization time on every message that uses a schema that is not yet cached. If p95 latency exceeds 200ms, producer throughput suffers.

Expose latency as a health endpoint in your application layer and monitor it with Vigilmon, or configure Prometheus alerting on the apicurio_rest_request_duration_seconds histogram:

# Prometheus alerting rule
- alert: ApicurioHighSchemaResolutionLatency
  expr: histogram_quantile(0.95, rate(apicurio_rest_request_duration_seconds_bucket{uri=~"/apis/registry/v2/ids/.*"}[5m])) > 0.2
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Apicurio schema resolution p95 > 200ms"
    description: "Schema fetch latency is {{ $value | humanizeDuration }} — Kafka producers may be slowing down."

Step 7: Set Up Alerting for Schema Compatibility Violations

Schema compatibility rule violations mean a service tried to register a breaking schema change. Apicurio correctly rejected it, but you want to know so the responsible team can be notified immediately.

  1. In Vigilmon, go to Alert Policies and click New Policy.
  2. Name it Apicurio Schema Violations.
  3. Add your email, Slack webhook, or PagerDuty integration as the alert destination.
  4. Set Quiet hours if applicable and click Save.

For API-level detection, query Apicurio's audit log or configure a Prometheus counter on compatibility rule rejections:

- alert: ApicurioCompatibilityViolation
  expr: increase(apicurio_schema_compatibility_violations_total[1h]) > 0
  labels:
    severity: warning
  annotations:
    summary: "Schema compatibility violation detected"
    description: "A backward-incompatible schema registration was rejected. Check the Apicurio audit log."

Step 8: Monitor Kafka Consumer Group Lag (KafkaSQL Only)

When using the KafkaSQL storage backend, Apicurio writes schema data as messages to a Kafka topic and reads them back via a dedicated consumer group. Consumer group lag on the storage topic means schema writes are being acknowledged before they are fully durable — or that Apicurio's internal consumer is falling behind.

Monitor the Kafka consumer group lag using your Kafka monitoring tool (Kafka Lag Exporter, Burrow, or Conduktor Console). Alert when the lag for Apicurio's storage consumer group exceeds 0 for more than 5 minutes:

- alert: ApicurioKafkaSQLLag
  expr: kafka_consumergroup_lag{consumergroup=~"apicurio.*"} > 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Apicurio KafkaSQL consumer group is lagging"
    description: "The Apicurio storage consumer group has lag {{ $value }}. Schema durability may be delayed."

Step 9: Monitor Artifact Count for Catalog Integrity

An unexpected spike or drop in the Apicurio artifact count is worth alerting on. A spike could indicate artifact spam from a misconfigured pipeline. A drop could indicate accidental bulk deletion.

You can expose this via a cron-driven heartbeat: write a small script that calls GET /apis/registry/v2/search/artifacts?limit=1 and checks the count field in the response, then pushes the result to a Vigilmon heartbeat:

#!/bin/bash
COUNT=$(curl -s "https://your-apicurio-host/apis/registry/v2/search/artifacts?limit=1" | jq '.count')
echo "Apicurio artifact count: $COUNT"
curl -s "https://vigilmon.online/api/v1/heartbeats/YOUR_HEARTBEAT_SLUG"

Schedule this with cron every 15 minutes. If the script fails (curl returns non-200 or jq parse fails), the heartbeat is not sent and Vigilmon alerts on the missed ping.

Alert Reference

| Monitor | Alert Threshold | Severity | Impact | |---|---|---|---| | Readiness probe /health/ready | Any failure | Critical | All schema resolution blocked | | Liveness probe /health/live | Any failure | Critical | Process dead | | PostgreSQL / Kafka TCP | Connection refused | Critical | Schema writes failing | | Confluent API /apis/ccompat/v7 | Non-200 | High | Confluent-native producers blocked | | Web console /ui | Non-200 | Low | Schema management blocked | | Schema resolution p95 | > 200ms | Warning | Producer throughput degraded | | Compatibility violations | Any count | Warning | Breaking change attempted | | KafkaSQL consumer group lag | > 0 for 5m | Warning | Schema durability delayed | | Artifact count | Unexpected ±20% | Warning | Bulk delete or import event |

Conclusion

Apicurio Registry is a quiet but critical dependency of your entire event-driven architecture. The monitoring setup in this guide gives you coverage across every failure mode: server process death, storage backend disconnection, Confluent API degradation, schema resolution latency, and breaking schema change attempts. With Vigilmon handling uptime, TCP, and heartbeat checks and Prometheus alerting covering latency and rates, you have the observability to catch Apicurio problems before Kafka producers start dropping messages.

Start with the readiness probe and storage backend TCP checks — those two monitors cover the most severe failure modes in under five minutes. Then layer in the latency and compatibility violation alerts as your team grows more comfortable with the system.

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