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