Metrics & Health¶

Verity exposes operational metrics in Prometheus format and a health-check endpoint for liveness/readiness probes.

Health Check¶

GET /v1/health

Returns the overall health status of the API Gateway and its downstream dependencies. Use this endpoint for Kubernetes liveness and readiness probes.

No authentication required

The health endpoint does not require a Bearer token.

Example Request¶

curl -s "http://localhost:8000/v1/health"

Example Response¶

{
  "status": "healthy",
  "version": "0.4.0",
  "checks": {
    "postgres": "ok",
    "clickhouse": "ok",
    "redis": "ok",
    "kafka": "ok"
  }
}

Health Statuses¶

Status	Description
`healthy`	All dependencies are reachable and functioning.
`degraded`	One or more non-critical dependencies are unhealthy.
`unhealthy`	One or more critical dependencies are unreachable.

Dependency Check Details¶

When a dependency is unhealthy, the check value includes an error message:

{
  "status": "degraded",
  "version": "0.4.0",
  "checks": {
    "postgres": "ok",
    "clickhouse": "ok",
    "redis": "timeout after 2s",
    "kafka": "ok"
  }
}

Prometheus Metrics¶

GET /v1/metrics

Returns metrics in Prometheus exposition format. All Verity-specific metrics use the verity_ prefix.

No authentication required

The metrics endpoint does not require a Bearer token.

Example Request¶

curl -s "http://localhost:8000/v1/metrics"

Example Response¶

# HELP verity_http_requests_total Total HTTP requests processed
# TYPE verity_http_requests_total counter
verity_http_requests_total{method="GET",endpoint="/v1/principals",status="200"} 14523
verity_http_requests_total{method="GET",endpoint="/v1/scores",status="200"} 8741
verity_http_requests_total{method="POST",endpoint="/v1/reviews/decide",status="200"} 342

# HELP verity_http_request_duration_seconds HTTP request latency in seconds
# TYPE verity_http_request_duration_seconds histogram
verity_http_request_duration_seconds_bucket{endpoint="/v1/principals",le="0.1"} 13200
verity_http_request_duration_seconds_bucket{endpoint="/v1/principals",le="0.5"} 14400
verity_http_request_duration_seconds_bucket{endpoint="/v1/principals",le="1.0"} 14520
verity_http_request_duration_seconds_bucket{endpoint="/v1/principals",le="+Inf"} 14523

# HELP verity_scores_computed_total Total decay scores computed
# TYPE verity_scores_computed_total counter
verity_scores_computed_total{trigger="scheduled"} 1250000
verity_scores_computed_total{trigger="event"} 87430
verity_scores_computed_total{trigger="manual"} 156

# HELP verity_reviews_created_total Total review packets created
# TYPE verity_reviews_created_total counter
verity_reviews_created_total{risk_level="CRITICAL"} 23
verity_reviews_created_total{risk_level="HIGH"} 187
verity_reviews_created_total{risk_level="MEDIUM"} 1542
verity_reviews_created_total{risk_level="LOW"} 4210

# HELP verity_reviews_pending Current number of pending reviews
# TYPE verity_reviews_pending gauge
verity_reviews_pending{risk_level="CRITICAL"} 2
verity_reviews_pending{risk_level="HIGH"} 15
verity_reviews_pending{risk_level="MEDIUM"} 87
verity_reviews_pending{risk_level="LOW"} 203

# HELP verity_grants_active Current number of active grants
# TYPE verity_grants_active gauge
verity_grants_active{platform="snowflake"} 24500
verity_grants_active{platform="fabric"} 18200
verity_grants_active{platform="databricks"} 9300

# HELP verity_connector_sync_duration_seconds Duration of connector sync operations
# TYPE verity_connector_sync_duration_seconds histogram
verity_connector_sync_duration_seconds_bucket{platform="snowflake",le="60"} 45
verity_connector_sync_duration_seconds_bucket{platform="snowflake",le="300"} 52
verity_connector_sync_duration_seconds_bucket{platform="snowflake",le="+Inf"} 52

# HELP verity_decay_engine_run_duration_seconds Duration of decay engine scoring runs
# TYPE verity_decay_engine_run_duration_seconds histogram
verity_decay_engine_run_duration_seconds_bucket{le="60"} 140
verity_decay_engine_run_duration_seconds_bucket{le="300"} 155
verity_decay_engine_run_duration_seconds_bucket{le="600"} 156
verity_decay_engine_run_duration_seconds_bucket{le="+Inf"} 156

Exported Metrics Reference¶

HTTP Metrics¶

Metric	Type	Labels	Description
`verity_http_requests_total`	counter	method, endpoint, status	Total HTTP requests processed.
`verity_http_request_duration_seconds`	histogram	endpoint	HTTP request latency.

Scoring Metrics¶

Metric	Type	Labels	Description
`verity_scores_computed_total`	counter	trigger	Total decay scores computed.
`verity_decay_engine_run_duration_seconds`	histogram	—	Duration of scoring runs.

Review Metrics¶

Metric	Type	Labels	Description
`verity_reviews_created_total`	counter	risk_level	Total review packets created.
`verity_reviews_pending`	gauge	risk_level	Current pending review count.

Grant Metrics¶

Metric	Type	Labels	Description
`verity_grants_active`	gauge	platform	Current active grant count.

Connector Metrics¶

Metric	Type	Labels	Description
`verity_connector_sync_duration_seconds`	histogram	platform	Duration of connector sync operations.

Prometheus / Grafana Integration¶

Add the Verity metrics endpoint to your Prometheus scrape configuration:

scrape_configs:
  - job_name: "verity-api"
    scrape_interval: 15s
    static_configs:
      - targets: ["verity-api-gateway:8000"]
    metrics_path: "/v1/metrics"

Verity ships with a pre-built Grafana dashboard. Import it from infra/grafana/dashboards/verity-overview.json or use the dashboard ID when available on Grafana.com.