Health Endpoint hinzugefügt
parent
88702c55ea
commit
ec1b44ad7c
1 changed files with 366 additions and 0 deletions
366
Health-Endpoint.md
Normal file
366
Health-Endpoint.md
Normal file
|
|
@ -0,0 +1,366 @@
|
||||||
|
# Health Endpoint
|
||||||
|
|
||||||
|
**System-Monitoring und Service-Diagnostics**
|
||||||
|
|
||||||
|
## Endpoint
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /health
|
||||||
|
```
|
||||||
|
|
||||||
|
**Zweck:** Öffentlicher Health-Check für Monitoring-Systeme. Zeigt Service-Status, Version-Informationen und Feature-Verfügbarkeit.
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
**Keine Authentication erforderlich** - der Health-Endpoint ist öffentlich zugänglich für Monitoring-Systeme.
|
||||||
|
|
||||||
|
**Warum öffentlich:** Monitoring-Tools müssen den Service-Status prüfen können, auch wenn die API-Authentifizierung ausgefallen ist.
|
||||||
|
|
||||||
|
## Response Format
|
||||||
|
|
||||||
|
### Healthy System Response (HTTP 200)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "healthy",
|
||||||
|
"service": "furt-lua",
|
||||||
|
"version": "0.1.2",
|
||||||
|
"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)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "degraded",
|
||||||
|
"service": "furt-lua",
|
||||||
|
"version": "0.1.2",
|
||||||
|
"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:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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
|
||||||
|
```json
|
||||||
|
"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
|
||||||
|
```json
|
||||||
|
"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)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "Endpoint not found"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Warum optional:** Test-Endpoint soll in Production deaktiviert werden können.
|
||||||
|
|
||||||
|
## Monitoring Integration
|
||||||
|
|
||||||
|
### Nagios/Icinga
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/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
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# prometheus.yml
|
||||||
|
scrape_configs:
|
||||||
|
- job_name: 'furt-gateway'
|
||||||
|
metrics_path: '/health'
|
||||||
|
static_configs:
|
||||||
|
- targets: ['api.dragons-at-work.de: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
|
||||||
|
# nginx upstream health check
|
||||||
|
upstream furt_backend {
|
||||||
|
server api.example.com:7811;
|
||||||
|
# Health check via /health endpoint
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```haproxy
|
||||||
|
# HAProxy health check
|
||||||
|
backend furt_servers
|
||||||
|
option httpchk GET /health
|
||||||
|
server furt1 api.example.com:7811 check
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration Examples
|
||||||
|
|
||||||
|
### Simple Status Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s http://localhost:7811/health | jq '.status'
|
||||||
|
# Output: "healthy"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Version Information
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s http://localhost:7811/health | jq '.version'
|
||||||
|
# Output: "0.1.2"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Feature Status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s http://localhost:7811/health | jq '.features.smtp_configured'
|
||||||
|
# Output: true
|
||||||
|
```
|
||||||
|
|
||||||
|
### Complete Status Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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.2, source=merkwerk
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request-ID:** Health-Checks erhalten keine Request-ID da sie stateless sind.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue