{
  "status": "healthy",
  "service": "furt-lua",
  "version": "0.1.4",
  "content_hash": "abc123def456",
  "vcs_info": {
    "type": "git",
    "hash": "7a8b9c0d",
    "branch": "main"
  },
  "timestamp": 1632150000,
  "source": "merkwerk",
  "features": {
    "smtp_configured": true,
    "auth_enabled": true,
    "rate_limiting": true,
    "rate_limits": {
      "default_rpm": 60,
      "burst_size": 10
    },
    "merkwerk_integrated": true
  }
}

Degraded System Response (HTTP 200)

{
  "status": "degraded",
  "service": "furt-lua", 
  "version": "0.1.4",
  "timestamp": 1632150000,
  "features": {
    "smtp_configured": false,
    "auth_enabled": true,
    "rate_limiting": true,
    "merkwerk_integrated": false
  },
  "issues": [
    "SMTP configuration missing",
    "merkwerk integration not available"
  ]
}

Response Fields

Core Fields

Field	Type	Description
`status`	string	`healthy`, `degraded`, or `unhealthy`
`service`	string	Service identifier (`furt-lua`)
`version`	string	Current service version
`timestamp`	integer	Unix timestamp of health check

Version Information

Field	Type	Description
`content_hash`	string	Content verification hash
`vcs_info`	object	Version control information
`vcs_info.type`	string	VCS type (`git`, `none`)
`vcs_info.hash`	string	Commit hash
`vcs_info.branch`	string	Git branch name
`source`	string	Version info source (`merkwerk`, `fallback-no-merkwerk`)

Feature Status

Field	Type	Description
`features.smtp_configured`	boolean	Mail service availability
`features.auth_enabled`	boolean	API-Key authentication status
`features.rate_limiting`	boolean	Rate limiting functionality
`features.rate_limits`	object	Rate limiting configuration
`features.merkwerk_integrated`	boolean	merkwerk version tracking

Status Levels

`healthy`

Alle Kern-Features funktionsfähig
SMTP-Konfiguration vorhanden
Authentication funktioniert
Keine kritischen Issues

`degraded`

Service läuft, aber mit eingeschränkter Funktionalität
Möglicherweise fehlende SMTP-Konfiguration
Nicht-kritische Components offline
API bleibt verfügbar

`unhealthy`

Service nicht betriebsbereit
Kritische Components ausgefallen
API möglicherweise nicht verfügbar

Warum gestufte Status: Monitoring-Systeme können zwischen "funktioniert perfekt", "funktioniert eingeschränkt" und "ist kaputt" unterscheiden.

merkwerk Integration

merkwerk ist das Dragons@Work Version-Tracking-System. Es bietet:

Version Information

Precise Version: Exakte Versionsnummer (nicht nur Git-Tag)
Content Hash: Verifikation des Code-Inhalts
VCS Integration: Git-Commit und Branch-Information
Build Metadata: Build-Zeitpunkt und Umgebung

Fallback Behavior

Wenn merkwerk nicht verfügbar ist:

{
  "service": "furt-lua",
  "version": "?.?.?",
  "content_hash": "unknown", 
  "vcs_info": {
    "type": "none",
    "hash": "",
    "branch": ""
  },
  "source": "fallback-no-merkwerk"
}

Warum Fallback: Service funktioniert auch ohne merkwerk-Integration. Version-Tracking ist nice-to-have, nicht kritisch.

Feature Detection

SMTP Configuration

"smtp_configured": true/false

Checked: Ob config.smtp_default.host konfiguriert ist. Purpose: Monitoring kann erkennen ob Mail-Service funktionsfähig ist.

Rate Limiting Details

"rate_limits": {
  "default_rpm": 60,
  "burst_size": 10
}

Information: Aktuelle Rate-Limiting-Konfiguration. Purpose: Clients können ihre Request-Rate entsprechend anpassen.

Development Test Endpoint

GET /test

Zweck: Development-Testing ohne Side-Effects. Status: Nur verfügbar wenn in Konfiguration aktiviert.

Test Response (HTTP 200)

{
  "message": "Test endpoint working",
  "received_data": null,
  "headers_count": 8,
  "warning": "This is a development endpoint (enabled via config)"
}

Test Disabled (HTTP 404)

Wenn Test-Endpoint in Konfiguration deaktiviert:

{
  "error": "Endpoint not found"
}

Warum optional: Test-Endpoint soll in Production deaktiviert werden können.

Monitoring Integration

Nagios/Icinga

#!/bin/bash
# check_furt_health.sh

RESPONSE=$(curl -s http://localhost:7811/health)
STATUS=$(echo $RESPONSE | jq -r '.status')

case $STATUS in
  "healthy")
    echo "OK - Furt Gateway healthy"
    exit 0
    ;;
  "degraded") 
    echo "WARNING - Furt Gateway degraded"
    exit 1
    ;;
  "unhealthy")
    echo "CRITICAL - Furt Gateway unhealthy"
    exit 2
    ;;
  *)
    echo "UNKNOWN - Could not determine Furt status"
    exit 3
    ;;
esac

Prometheus

# prometheus.yml
scrape_configs:
  - job_name: 'furt-gateway'
    metrics_path: '/health'
    static_configs:
      - targets: ['api.example.com:443']

Health-to-Metrics Mapping:

status="healthy" → furt_health_status = 1
status="degraded" → furt_health_status = 0.5
status="unhealthy" → furt_health_status = 0

Load Balancer Health Checks

# nginx upstream health check
upstream furt_backend {
  server api.example.com:7811;
  # Health check via /health endpoint
}

# HAProxy health check  
backend furt_servers
  option httpchk GET /health
  server furt1 api.example.com:7811 check

Integration Examples

Simple Status Check

curl -s http://localhost:7811/health | jq '.status'
# Output: "healthy"

Version Information

curl -s http://localhost:7811/health | jq '.version'
# Output: "0.1.4"

Feature Status

curl -s http://localhost:7811/health | jq '.features.smtp_configured'
# Output: true

Complete Status Script

#!/bin/bash
# furt_status.sh - Complete health check

HEALTH_URL="http://localhost:7811/health"
RESPONSE=$(curl -s $HEALTH_URL)

if [ $? -ne 0 ]; then
  echo "ERROR: Could not reach Furt Gateway"
  exit 1
fi

STATUS=$(echo $RESPONSE | jq -r '.status')
VERSION=$(echo $RESPONSE | jq -r '.version')
SMTP=$(echo $RESPONSE | jq -r '.features.smtp_configured')

echo "Furt Gateway Status: $STATUS"
echo "Version: $VERSION"
echo "SMTP Configured: $SMTP"

if [ "$STATUS" = "healthy" ]; then
  echo "✓ All systems operational"
  exit 0
elif [ "$STATUS" = "degraded" ]; then
  echo "⚠ System degraded but functional"
  exit 1
else
  echo "✗ System unhealthy"
  exit 2
fi

Troubleshooting

Common Issues

Health endpoint not responding:

Service nicht gestartet: systemctl status furt
Port nicht offen: netstat -ln | grep 7811
Firewall blockiert: Prüfe iptables/pf-Regeln

Status "degraded":

SMTP-Konfiguration prüfen
Log-Files auf Errors checken
Disk-Space und Memory prüfen

merkwerk not integrated:

merkwerk-Package fehlt oder fehlerhaft installiert
Funktionalität bleibt verfügbar, nur Version-Info limitiert

Debug Information

# Detaillierte Response anzeigen
curl -s http://localhost:7811/health | jq .

# Nur Feature-Status
curl -s http://localhost:7811/health | jq '.features'

# Version-Tracking-Status
curl -s http://localhost:7811/health | jq '.source'

Log Correlation

Health-Endpoint-Aufrufe erscheinen in den Server-Logs:

[2024-09-10 12:34:56] Health endpoint called - Status: healthy
[2024-09-10 12:34:56] merkwerk health info: version=0.1.4, source=merkwerk

Request-ID: Health-Checks erhalten keine Request-ID da sie stateless sind.