Marquez is the open-source metadata service that collects, stores, and visualizes data lineage across your entire data ecosystem — ingesting OpenLineage events from Airflow, Spark, dbt, and Flink to build a complete graph of how data flows from sources to consumers. When the Marquez API server becomes unavailable, pipeline tools stop emitting lineage events and the metadata record goes dark — new jobs run without leaving a trace, schema changes go unlinked to downstream impacts, and compliance audits lose the evidence trail they depend on. When the Marquez web UI fails, data engineers and analysts cannot explore the lineage graph, trace the root cause of a data quality incident upstream, or identify which dashboards are affected by a broken upstream table. Vigilmon gives you external visibility into the Marquez infrastructure: the API server, the web UI, and your OpenLineage event receivers, so you know the moment the lineage service itself needs attention.
What You'll Build
- An HTTP monitor on the Marquez web UI to detect frontend availability failures
- A health-check monitor on the Marquez API server to catch backend degradation
- A monitor on the OpenLineage event ingestion endpoint to verify lineage events are flowing
- A monitor on your Marquez notification webhook to catch downstream alert failures
- An SSL certificate monitor for your Marquez domain
- Alerting that distinguishes API server outages from UI and event ingestion failures
Prerequisites
- A self-hosted Marquez deployment (API server + web UI) accessible via HTTPS
- Pipelines emitting OpenLineage events to your Marquez deployment
- A free account at vigilmon.online
Step 1: Understand Marquez's Service Architecture
Marquez operates as a two-tier metadata service with several monitorable components:
| Component | Default port | Role |
|---|---|---|
| Marquez API server | 5000 (HTTP) | Accepts OpenLineage events, stores lineage metadata, serves REST API for graph queries |
| Marquez web UI | 3000 (HTTP) | Visualizes the lineage graph, job/dataset relationships, and run history |
| PostgreSQL database | 5432 | Persistent metadata storage for all lineage events and namespace data |
| OpenLineage ingest endpoint | /api/v1/lineage | Receives OpenLineage events from Airflow, Spark, dbt, and other producers |
External monitoring focuses on the API server and web UI — these surface the availability of the entire Marquez deployment and are the interfaces your pipeline tools and data engineers interact with directly.
Step 2: Monitor the Marquez Web UI
The Marquez web UI is the primary interface for exploring the data lineage graph — viewing job-to-dataset relationships, tracing how a broken upstream table propagates downstream, reviewing run history for specific jobs, and identifying which dashboards and reports depend on a given data source:
curl -I https://your-marquez.example.com
# Returns HTTP 200 with HTML when the frontend is healthy
- Log in to Vigilmon → Add Monitor → HTTP.
- URL:
https://your-marquez.example.com(your Marquez web UI hostname). - Check interval: 60 seconds.
- Response timeout: 15 seconds.
- Expected status:
200. - Keyword:
Marquez(appears in the page title and HTML content). - Click Save.
This monitor catches:
- Marquez UI container crashes or failed Docker restarts
- Nginx or reverse proxy misconfigurations returning 5xx errors
- Failed Marquez upgrades that break the frontend before the API is restored
- DNS resolution failures for your Marquez web UI hostname
Alert sensitivity: Set to trigger after 1 consecutive failure. When the Marquez web UI is unavailable, data engineers cannot explore the lineage graph, root-cause incidents by tracing upstream dependencies, or verify that a pipeline change didn't break downstream consumers — leaving the team without the observability layer they depend on during data incidents.
Step 3: Monitor the Marquez API Server
The Marquez API server is the core of the lineage system — it accepts OpenLineage events from every connected pipeline tool, stores the metadata in PostgreSQL, and serves graph queries used by the web UI and any downstream integrations. When the API degrades, pipeline tools queue or drop lineage events, the lineage graph stops updating, and tools that query Marquez for dependency information return stale or missing data:
curl https://your-marquez.example.com:5000/api/v1/namespaces
# Returns the list of namespaces when the API is operational
Or use the dedicated ping endpoint if available:
curl https://your-marquez.example.com:5000/ping
# Returns: {"version": "x.y.z"} when the server is running
- Add Monitor → HTTP.
- URL:
https://your-marquez.example.com:5000/ping. - Check interval: 60 seconds.
- Response timeout: 10 seconds.
- Expected status:
200. - Keyword:
version(present in the ping response). - Label:
Marquez API server. - Click Save.
Why monitor the API separately from the UI? The Marquez web UI may serve cached graph visualizations even when the API cannot accept new lineage events. A failing API means Airflow DAGs, Spark jobs, and dbt runs emit OpenLineage events that are lost — the lineage graph appears current in the UI but is actually missing all job runs that occurred during the API outage.
Step 4: Monitor the OpenLineage Ingest Endpoint
The /api/v1/lineage endpoint is where all pipeline tools (Airflow, Spark, dbt Cloud, Flink) send their OpenLineage START, COMPLETE, and FAIL events. When this endpoint is degraded or returning errors, pipeline lineage stops being recorded — jobs complete without leaving a trace in the metadata graph, schema changes go unlinked to their downstream impacts, and the lineage record develops gaps that make future audits unreliable:
curl -X POST https://your-marquez.example.com:5000/api/v1/lineage \
-H "Content-Type: application/json" \
-d '{"eventType":"START","eventTime":"2026-01-01T00:00:00Z","run":{"runId":"health-check"},"job":{"namespace":"health","name":"check"},"inputs":[],"outputs":[],"producer":"vigilmon-probe"}'
# Returns HTTP 201 when the ingest endpoint is accepting events
- Add Monitor → HTTP.
- URL:
https://your-marquez.example.com:5000/api/v1/lineage. - Method:
POST. - Request body: A minimal valid OpenLineage event (as above).
- Check interval: 5 minutes.
- Response timeout: 10 seconds.
- Expected status:
201. - Label:
Marquez OpenLineage ingest. - Click Save.
Alternatively, if you prefer not to inject test events into your lineage graph, monitor the /api/v1/namespaces endpoint instead — a 200 response with a JSON array confirms the API server can accept and serve metadata requests without inserting test records.
Step 5: Monitor Your Marquez Notification Webhook
If you use Marquez alongside a data quality or alerting system that posts webhook notifications when lineage events arrive, monitoring that webhook receiver ensures the downstream notification flow is healthy. A failing receiver means lineage events are recorded in Marquez but alerts for job failures, schema changes, or data quality regressions are never dispatched to on-call teams:
curl https://your-webhook-receiver.example.com/health
# Returns: {"status": "ok"} when the receiver is up
- Add Monitor → HTTP.
- URL:
https://your-webhook-receiver.example.com/health. - Check interval: 2 minutes.
- Response timeout: 10 seconds.
- Expected status:
200. - Keyword:
ok. - Label:
Marquez notification webhook. - Click Save.
Step 6: Monitor SSL Certificates
The Marquez API server and web UI are accessed over HTTPS by both data engineers using the browser UI and automated pipeline tools (Airflow operators, Spark listeners, dbt Cloud) that post OpenLineage events on every job run. An expired certificate breaks browser access to the lineage graph and causes all OpenLineage producers to fail their event posts with TLS errors — stopping lineage recording across your entire data stack:
openssl s_client -connect your-marquez.example.com:443 2>/dev/null | openssl x509 -noout -dates
- Add Monitor → SSL Certificate.
- Domain:
your-marquez.example.com. - Alert when expiry is within: 30 days.
- Alert again: 14 days, 7 days, 3 days, 1 day.
- Click Save.
Broad pipeline impact: When Marquez's TLS certificate expires, every OpenLineage-enabled pipeline tool (Airflow, Spark, dbt Cloud, Flink) that posts events to Marquez will fail its lineage emission on the next scheduled run. Depending on how each tool handles lineage emission errors, this may cause the pipeline to fail entirely or continue without recording lineage — both are bad outcomes during an active data incident investigation.
Step 7: Configure Alerting
In Vigilmon under Settings → Notifications, configure your alert channels:
| Monitor | Trigger | Action |
|---|---|---|
| Web UI | Non-200 or Marquez missing | Check Marquez UI container; review Docker/K8s logs |
| API server | Non-200 or version missing | API down; lineage events dropping; check server logs and PostgreSQL connection |
| OpenLineage ingest | Non-201 response | Ingest endpoint rejecting events; pipeline lineage gaps forming |
| Notification webhook | Non-200 or ok missing | Alerts not delivering; verify receiver deployment and logs |
| SSL certificate | < 30 days to expiry | Renew certificate; verify all OpenLineage producers reconnect after renewal |
Alert after: 1 consecutive failure for the API server and ingest monitors. 2 consecutive failures for the web UI and notification webhook monitors to reduce noise from transient container restarts during deployments.
Common Marquez Failure Modes and What Vigilmon Catches
| Scenario | Vigilmon monitor | |---|---| | Marquez UI container crash | Web UI monitor fires; engineers cannot explore lineage graph | | API server failure | API monitor fires; lineage events drop; graph stops updating | | OpenLineage ingest endpoint errors | Ingest monitor fires; pipeline lineage gaps form silently | | PostgreSQL connection failure | API monitor fires with 5xx; no events can be stored or served | | Notification webhook receiver crash | Webhook monitor fires; job failure alerts stop posting | | TLS certificate expired | SSL monitor alerts; all OpenLineage producers fail event posts | | DNS misconfiguration | All monitors fire simultaneously | | Marquez upgrade failure | UI and/or API monitor fires depending on which component is broken |
Monitoring Data Lineage Completeness (Beyond Infrastructure)
Vigilmon monitors Marquez's infrastructure endpoints — the web UI, API server, ingest endpoint, and notification webhook. The completeness of lineage coverage across your pipelines is a separate concern managed within each OpenLineage producer:
- OpenLineage producer configuration: Audit which Airflow DAGs, Spark jobs, and dbt projects have OpenLineage emission enabled to ensure all critical pipelines are contributing to the lineage graph.
- Namespace organization: Maintain consistent namespace naming across producers so the Marquez lineage graph remains navigable as the number of jobs and datasets grows.
- Event replay: If Marquez experiences an outage during which events are dropped, some OpenLineage producers support event replay — verify your producers' buffering and retry configuration so gaps can be backfilled after the service is restored.
Vigilmon catches infrastructure-level failures — when Marquez itself is down or rejecting events. Lineage completeness and graph coverage within a healthy Marquez deployment require OpenLineage producer configuration on each pipeline tool.
Marquez is the metadata backbone that makes your data ecosystem traceable — when it goes down, lineage recording stops, pipeline tools lose their observability integration, and data incidents become harder to root-cause because the dependency graph is no longer current. Vigilmon gives you external visibility into Marquez's availability that doesn't depend on Marquez self-reporting: web UI uptime, API server health, OpenLineage ingest status, and SSL certificate validity, so you know the moment the lineage service itself needs attention and can restore metadata recording before the next pipeline run leaves gaps in your compliance audit trail.
Start monitoring Marquez in under 5 minutes — register free at vigilmon.online.