Health Endpoint

curl --request GET \
  --url https://api.example.com/health

import requests

url = "https://api.example.com/health"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/health"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/health")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "healthy_backends": "<string>",
  "uptime_seconds": 123
}

GET

health

Health Endpoint

curl --request GET \
  --url https://api.example.com/health

import requests

url = "https://api.example.com/health"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/health"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/health")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "healthy_backends": "<string>",
  "uptime_seconds": 123
}

Overview

The /health endpoint provides real-time information about the load balancer’s operational status and backend server health.

Endpoint

GET /health

Response

status

string

Overall health status

ok: Load balancer is operating normally
degraded: Some backends are down but service continues
down: No healthy backends available

healthy_backends

string

Ratio of healthy backends (e.g., “3/3” or “2/3”)

uptime_seconds

number

Load balancer uptime in seconds since start

Example Request

curl http://localhost:8080/health

const response = await fetch('http://localhost:8080/health');
const health = await response.json();
console.log(health);

import requests

response = requests.get('http://localhost:8080/health')
health = response.json()
print(health)

resp, err := http.Get("http://localhost:8080/health")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var health map[string]interface{}
json.NewDecoder(resp.Body).Decode(&health)

Example Response

All Backends Healthy

200 OK

{
  "status": "ok",
  "healthy_backends": "3/3",
  "uptime_seconds": 3600
}

Degraded State

200 OK

{
  "status": "degraded",
  "healthy_backends": "2/3",
  "uptime_seconds": 7200
}

No Healthy Backends

503 Service Unavailable

{
  "status": "down",
  "healthy_backends": "0/3",
  "uptime_seconds": 1800
}

Use Cases

Kubernetes Liveness Probe

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

Docker Healthcheck

HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

Monitoring Script

#!/bin/bash
response=$(curl -s http://localhost:8080/health)
status=$(echo $response | jq -r '.status')

if [ "$status" != "ok" ]; then
  echo "ALERT: Load balancer unhealthy"
  # Send alert
fi

Load Balancer Health Check

If you have multiple UltraBalancer instances behind a load balancer:

upstream ultrabalancer_cluster {
  server ultra1:8080;
  server ultra2:8080;
}

# Health check
health_check interval=5s fails=3 passes=2 uri=/health;

Status Interpretation

All configured backends are healthy. The load balancer is fully operational.

degraded

One or more backends are unhealthy, but at least one backend is available. Service continues with reduced capacity.

down

No backends are available. The load balancer cannot serve requests.

Uptime Calculation

The uptime_seconds field represents how long the load balancer has been running since its last start. This counter resets to 0 when:

The process is restarted
Configuration is reloaded (in future versions)
The system reboots

Use this field to track restart frequency and overall stability.

Integration Examples

Prometheus Blackbox Exporter

Monitor health endpoint availability:

prometheus.yml

scrape_configs:
  - job_name: 'ultrabalancer-health'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
        - http://ultrabalancer:8080/health
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115

Grafana Alert

Create alert when health degrades:

alert: UltraBalancerDegraded
expr: ultrabalancer_healthy_backends_ratio < 1
for: 5m
labels:
  severity: warning
annotations:
  summary: "UltraBalancer has unhealthy backends"
  description: "Only {{ $value }} backends are healthy"

Next Steps

Metrics Endpoint

Get detailed performance metrics

Health Checks

Configure health checking

Monitoring Guide

Set up comprehensive monitoring

Prometheus

Prometheus metrics format

Admin API

/metrics Endpoint

⌘I

Getting Started

Concepts

Configuration

Deployment

Testing

Integration

API

Advanced

Health Endpoint

Overview

Endpoint

Response

Example Request

Example Response

All Backends Healthy

Degraded State

No Healthy Backends

Use Cases

Status Interpretation

Uptime Calculation

Integration Examples

Prometheus Blackbox Exporter

Grafana Alert

Next Steps

Metrics Endpoint

Health Checks

Monitoring Guide

Prometheus

​Overview

​Endpoint

​Response

​Example Request

​Example Response

​All Backends Healthy

​Degraded State

​No Healthy Backends

​Use Cases

​Status Interpretation

​Uptime Calculation

​Integration Examples

​Prometheus Blackbox Exporter

​Grafana Alert

​Next Steps

Metrics Endpoint

Health Checks

Monitoring Guide

Prometheus

Overview

Endpoint

Response

Example Request

Example Response

All Backends Healthy

Degraded State

No Healthy Backends

Use Cases

Status Interpretation

Uptime Calculation

Integration Examples

Prometheus Blackbox Exporter

Grafana Alert

Next Steps