OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche: Unterschied zwischen den Versionen
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt] |
Statistik: Aufruf über F8 in den Listen Zugänge und Endpunkte ergänzt [Volltext ersetzt] |
||
| Zeile 147: | Zeile 147: | ||
== Statistik == | == Statistik == | ||
Die Tabelle <code>RESTSRV_STATS</code> enthält eine Zeile je Anfrage, die bis zur Verarbeitung kommt. Dazu gehören auch Anfragen, die bei der Authentifizierung abgewiesen werden. Die Statistik zeigt damit alle verarbeiteten Anfragen, das Protokoll die Auffälligkeiten. | Die Tabelle <code>RESTSRV_STATS</code> enthält eine Zeile je Anfrage, die bis zur Verarbeitung kommt. Dazu gehören auch Anfragen, die bei der Authentifizierung abgewiesen werden. Die Statistik zeigt damit alle verarbeiteten Anfragen, das Protokoll die Auffälligkeiten. In OBS öffnet {{F8}} in der Liste der [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] bzw. der [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]] die Statistik des markierten Eintrags. | ||
{| class="wikitable" | {| class="wikitable" | ||
Version vom 17. November 2026, 07:36 Uhr
Betrieb und Fehlersuche
Diese Seite beschreibt, was der REST-Server im laufenden Betrieb aufzeichnet und wie Sie damit Störungen eingrenzen. Sie richtet sich an Administratoren und Betreuer der OBS-Installation sowie an Entwickler, die eine eigene Anbindung testen. Jede Antwort trägt eine Korrelations-ID. Mit ihr finden Sie zu jeder Anfrage Statistik und Protokoll, ohne dass interne Details nach außen gehen.
Protokoll
Die Tabelle RESTSRV_PROTO enthält die Auffälligkeiten des Betriebs. Erfolgreiche Anfragen stehen dort nicht, sie stehen in der Statistik. Ausgenommen sind einzelne Ereignisse wie Anmeldungen am JWT-Endpunkt, siehe Typische Meldungen.
Ins Protokoll gehen:
- abgewiesene und fehlerhafte Anfragen, auch fachliche Ablehnungen durch das Endpunkt-Skript
- Verbindungs- und TLS-Fehler
- Fehler und ausgewählte Ereignisse rund um JWT und Sitzungen
- Start des Servers, Bindungen, Zertifikat und Zertifikats-Pin
- Skriptfehler
- die Nutzung des vorherigen API-Keys nach einem Schlüsseltausch
- Abweisungen durch Rate-Limit und Andrangsgrenze
Spalten
| Feld | Inhalt |
|---|---|
rp_date |
Datum |
rp_time |
Uhrzeit |
rp_host |
Quelle der Zeile, siehe unten |
rp_text |
Meldung |
rp_trace |
Korrelations-ID der Anfrage, gleich dem Header X-Trace-Id der Antwort. Leer bei Meldungen ohne Anfragebezug |
Mögliche Werte in rp_host:
| Wert | Bedeutung |
|---|---|
| Name des Zugangs | Die Anfrage war einem Zugang zugeordnet |
| IP-Adresse | Die Anfrage war keinem Zugang zugeordnet, z.B. bei unbekanntem API-Key, Rate-Limit oder Andrangsgrenze |
System |
Start, Bindungen, Zertifikat, Aufräumläufe |
TLS:<Profil> |
Verbindungs- und TLS-Fehler eines Server-Profils, Klartext auf einem TLS-Port |
TLS |
Abgelehntes Client-Zertifikat bei mTLS |
JWTAuthentication |
Token konnte nicht geprüft werden |
ACME, ACME-WARNUNG, ACME-FEHLER |
Automatische Zertifikatserneuerung, siehe Zertifikatserneuerung |
Fehlerzeile einer Anfrage
Je fehlgeschlagener Anfrage schreibt der Server genau eine Fehlerzeile:
Fehler <Kennung> [<Status> <HTTP-Verb> <Pfad>] [trace=<Korrelations-ID>]: <Meldung>
- Kennung: Bei Fehlern, die der Server selbst feststellt, eine interne Kennung, z.B.
Y00C71CSDV. Sie steht auch alsuidin der Fehlerantwort. Setzt das Endpunkt-Skript eine Fehlerantwort (Status ab 400), steht hier dessenerror.code. Fehlt daserror-Objekt, steht hier der Code zum Status und als Meldung „Antwort ohne error-Objekt“. - Meldung: die ausführliche Begründung. Der Client erhält nur eine allgemeine Meldung, z.B. „Zugriff verweigert“.
Beispiel für einen unbekannten API-Key. Host ist hier die IP-Adresse:
Fehler Y00C71CSDV [401 GET /service/app/settings] [trace=20261117T091512345-00002A]: Kein Account mit diesem API-Key gefunden
Maskierung
Werte aus der Anfrage stammen vom Absender. Der Server schreibt sie deshalb nur bereinigt in Protokoll und Statistik:
- Steuerzeichen erscheinen als
\xNN, ungültiges UTF-8 als\uFFFD. - Der Pfad wird nach 200 Zeichen gekürzt und endet dann mit
.... - Parameter im Query-String mit den Namen
password,pass,token,secret,apikey,api_key,authorization,cookieundproxy-authorizationerscheinen als***. - Schickt der Client den Header X-Forwarded-For, hängt der Server dessen Wert als
[xff=…]an die Meldung an, siehe Betrieb hinter einem Reverse-Proxy.
Typische Meldungen
Platzhalter in spitzen Klammern stehen für die Werte im Einzelfall.
| Meldung | Bedeutung |
|---|---|
REST-Server [<Profil>] gestartet |
Das Server-Profil nimmt Anfragen an |
Bindung für <IP-Adresse>:<Port> auf Server [<Profil>] angelegt |
Eine Bindung ist aktiv |
Fehler: Bindung für <IP-Adresse> auf Server [<Profil>] konnte nicht angelegt werden |
Die Bindung ist nicht aktiv |
Fehler: Server [<Profil>] konnte nicht gestartet werden (<Grund>) |
Das Server-Profil läuft nicht. Den Grund nennt die Klammer |
Warnung: Kein aktiver Server in RESTSRV_SERVER konfiguriert |
Kein Server-Profil ist Aktiv |
Fehler: Modul nicht aktiv |
Das Modul REST-Server ist nicht freigeschaltet. Der Dienst startet keinen Server |
Server [<Profil>]: SSL-TLS aktiv (Standard-TLS ohne Client-Cert) |
TLS ist eingerichtet, ohne mTLS |
Server [<Profil>]: SSL-TLS aktiv (mTLS - alle Clients müssen Cert vorlegen) |
TLS mit mTLS ist eingerichtet |
Server [<Profil>]: Plain-HTTP aktiv (no_ssl=1, Debug-Modus) |
Das Profil läuft mit kein SSL (Plain-HTTP - nur für Debug!) |
Fehler: Server [<Profil>]: SSL/TLS-Konfiguration fehlt (rsv_cert/rsv_key) - Server kann nicht starten |
Zertifikat (cert) oder Schlüssel (key) fehlt am Server-Profil |
Fehler: Server [<Profil>]: rsv_root_cert fehlt - mTLS aktiv erfordert CA-Zertifikat |
mTLS-Modus aktiv ist gesetzt, Root-Zertifikat (ca) ist aber leer |
Warnung: Server [<Profil>]: rsv_cert trägt NUR das Server-Zertifikat, kein Zwischenzertifikat. … |
Die Zertifikatskette ist unvollständig. Hängen Sie das Zwischenzertifikat hinter das Server-Zertifikat an |
Server [<Profil>]: ACHTUNG, Zertifikats-Pin hat sich geändert: <neu> statt <alt>. Alle bisher ausgegebenen Zugangscodes sind damit ungültig. |
Der Schlüssel des Serverzertifikats hat sich geändert. Geräte mit dem alten Pin verbinden sich nicht mehr |
Klartext-HTTP-Anfrage auf TLS-Port von <IP-Adresse> (<Verb> <Pfad>) - mit 400 abgewiesen |
Ein Client hat http:// statt https:// verwendet
|
Plain-HTTP-Profil: TLS-Handshake-Versuch von <IP-Adresse> |
Ein Client hat https:// auf einem Profil ohne TLS verwendet. Die Verbindung wurde getrennt
|
TLS-Handshake erst nach Verbindungsaufbau von <IP-Adresse> (Methode …) - mit 400 abgewiesen |
Wie vorher, der Client hat aber erst später gesendet |
Ungültige Anfragezeile von <IP-Adresse> (Methode …) - mit 400 abgewiesen |
Die Anfrage war kein gültiges HTTP |
Verbindungs-Fehler von <IP-Adresse>: <Klasse> (<Grund>) |
Die Verbindung ist vor oder während des TLS-Handshakes gescheitert, z.B. fehlendes Client-Zertifikat bei mTLS |
Peer-Cert-Verifikation fehlgeschlagen: depth=…, err=… (…), subject=… |
Das Client-Zertifikat ließ sich nicht gegen das Root-Zertifikat (ca) prüfen |
Rate-Limit überschritten [<Profil>] <Verb> <Pfad> (…, key=…, retry=<n>s) [trace=…] |
Die Anfrage wurde mit 429 abgewiesen |
Andrangsgrenze erreicht [<Profil>] <Verb> <Pfad> (<n> von <max>) [trace=…] |
max. Anfragen war erreicht, Antwort 503 |
Unbehandelter Fehler [<Verb> <Pfad>] [trace=…]: <Grund> |
Unerwarteter Fehler, Antwort 500. Für diese Anfrage gibt es keine Statistikzeile |
Vorheriger API-Key benutzt von <IP-Adresse> (gültig bis <Zeitpunkt>) |
Ein Gerät verwendet nach einem Schlüsseltausch noch den alten API-Key. So sehen Sie, welche Geräte den neuen Zugangscode noch nicht eingelesen haben |
JWT-Token erstellt, JWT-Token rotiert (Refresh) |
Anmeldung bzw. Erneuerung am JWT-Endpunkt war erfolgreich |
JWT-Logout: Sitzung gesperrt (<n> Zeilen) |
Die Abmeldung war erfolgreich |
TokenStore: WIEDERVORLAGE eines verbrauchten Refresh-Token (…) - Sitzung wird gesperrt |
Ein bereits verbrauchtes Refresh-Token wurde erneut vorgelegt. Der Server sperrt die ganze Sitzung, siehe Anmeldung mit JWT |
TokenStore: Sitzung konnte nicht hinterlegt werden: <Grund> |
Die Sitzung ließ sich nicht in RESTSRV_TOKEN schreiben. Die Anmeldung scheitert mit 503
|
Idempotenz: gespeicherte Antwort zurückgespielt (…) |
Eine Wiederholung mit demselben Idempotency-Key hat die gespeicherte Antwort erhalten |
Idempotenz: offene Reservierung seit <Zeitpunkt> - … manuelle Klärung nötig |
Ein Schreibvorgang wurde hart abgebrochen. Ob er gewirkt hat, ist offen, siehe Wartung der Server-Tabellen |
WebHook: <Kennung> |
Ein WebHook-Endpunkt wurde aufgerufen |
Statistik
Die Tabelle RESTSRV_STATS enthält eine Zeile je Anfrage, die bis zur Verarbeitung kommt. Dazu gehören auch Anfragen, die bei der Authentifizierung abgewiesen werden. Die Statistik zeigt damit alle verarbeiteten Anfragen, das Protokoll die Auffälligkeiten. In OBS öffnet F8 in der Liste der Zugänge bzw. der Endpunkte die Statistik des markierten Eintrags.
| Feld | Inhalt |
|---|---|
rs_date, rs_time |
Datum und Uhrzeit |
rs_host |
IP-Adresse der Verbindung |
rs_account |
Kennung des Zugangs. Leer, wenn die Anfrage keinem Zugang zugeordnet werden konnte |
rs_endpoint |
Kennung des Endpunkts. Leer, wenn kein Endpunkt gefunden wurde |
rs_cmd |
HTTP-Verb. Am JWT-Endpunkt Authenticate für die Anmeldung bzw. Refresh für die Erneuerung |
rs_request |
Angefragter Pfad, maskiert wie im Protokoll, höchstens 200 Zeichen |
rs_response |
HTTP-Status der Antwort, bei Dateien auch 206 und 416 |
rs_runtime |
Laufzeit in Millisekunden |
rs_trace |
Korrelations-ID, gleich X-Trace-Id und rp_trace
|
rs_server |
Server-Profil, über das die Anfrage hereinkam |
Keine Statistikzeile erhalten:
- CORS-Preflight-Anfragen (OPTIONS)
- Anfragen, die das Rate-Limit mit 429 abweist
- Anfragen, die die Andrangsgrenze mit 503 abweist
- die 400-Abweisungen beim Verbindungsaufbau: Klartext auf einem TLS-Port, ungültige Anfragezeile
- Anfragen mit unerwartetem Fehler (500, Protokollzeile „Unbehandelter Fehler“)
Bis auf OPTIONS stehen diese Fälle im Protokoll.
Aufbewahrung
| Tabelle | Aufbewahrung |
|---|---|
RESTSRV_PROTO |
Gekappt bei 40.000 Sätzen |
RESTSRV_STATS |
Gekappt bei 100.000 Sätzen |
RESTSRV_IDEMPOTENCY |
Gespeicherte Antworten 30 Tage |
RESTSRV_TOKEN |
Bis Access- und Refresh-Token abgelaufen sind |
Brauchen Sie Protokoll oder Statistik länger, sichern Sie die Tabellen rechtzeitig.
Fehlersuche mit der Trace-ID
Jede Antwort des REST-Servers trägt den Header X-Trace-Id. Fehlerantworten enthalten denselben Wert zusätzlich als traceId im error-Objekt. Aufbau der Fehlerantwort und Bedeutung der Codes beschreibt HTTP-Schnittstelle.
- Lassen Sie sich die Trace-ID vom Client geben, z.B. aus dem Log der App oder aus den Entwicklerwerkzeugen des Browsers.
- Suchen Sie die Statistikzeile. Sie zeigt Zugang, Endpunkt, Status, Laufzeit und Server-Profil.
- Suchen Sie die Protokollzeilen. Sie nennen den Grund, den der Client nicht erhält.
- Gibt es keine Statistikzeile, suchen Sie im Protokoll nach der Trace-ID oder nach Uhrzeit und IP-Adresse, z.B. bei Rate-Limit, Andrangsgrenze oder TLS-Fehlern.
SELECT rs_date, rs_time, rs_host, rs_cmd, rs_request, rs_response, rs_runtime, rs_server
FROM RESTSRV_STATS
WHERE rs_trace = '20261117T091512345-00002A';
SELECT rp_date, rp_time, rp_host, rp_text
FROM RESTSRV_PROTO
WHERE rp_trace = '20261117T091512345-00002A';
Meldungen ohne Anfragebezug haben keine Trace-ID, z.B. Start, Bindungen, Zertifikat oder TLS-Fehler beim Verbindungsaufbau. Sie finden diese über rp_host:
SELECT rp_date, rp_time, rp_host, rp_text
FROM RESTSRV_PROTO
WHERE rp_host IN ('System', 'TLS') OR rp_host LIKE 'TLS:%'
ORDER BY rp_date DESC, rp_time DESC;
Häufige Fehlerbilder
Die Meldung an den Client ist bewusst allgemein. Den Grund finden Sie jeweils über die Trace-ID im Protokoll.
| Erscheinung | Ursache | Abhilfe |
|---|---|---|
| Verbindung bricht ab oder 400 mit dem Text „Ungültige Anfragezeile.“ | Der Client verwendet https://, das Profil läuft mit kein SSL (Plain-HTTP - nur für Debug!) |
http:// verwenden oder das Profil auf TLS umstellen. Im Betrieb nur TLS-Profile verwenden
|
| 400 mit dem Text „Dieser Port erwartet eine TLS-Verbindung. …“ | Der Client verwendet http:// auf einem TLS-Profil |
https:// verwenden
|
Verbindung bricht beim Aufbau ab, im Protokoll Verbindungs-Fehler oder Peer-Cert-Verifikation fehlgeschlagen |
mTLS-Modus aktiv ist gesetzt, der Client legt kein oder kein vertrauenswürdiges Client-Zertifikat vor | Client-Zertifikat installieren. Root-Zertifikat (ca) am Server-Profil prüfen |
401 CLIENT_CERT_INVALID |
Das Client-Zertifikat passt nicht zum mTLS-Subject des Zugangs | mTLS-Subject oder Client-Zertifikat korrigieren |
401 API_KEY_INVALID |
API-Key unbekannt, oder nach einem Schlüsseltausch ist die Frist des vorherigen Keys abgelaufen | API-Key im Zugang prüfen. Neuen Zugangscode ausgeben |
403 FORBIDDEN_ROLE „Zugriff verweigert“ |
Zugang nicht Aktiv, Anfrage nicht vom eingetragenen Host, CORS-Origin nicht erlaubt oder Zugang für den Endpunkt nicht freigeschaltet | Grund im Protokoll nachlesen, dann Zugang bzw. Freischaltung korrigieren |
404 NOT_FOUND |
Kein Pfad-Template passt, die Segmentzahl stimmt nicht, der Endpunkt ist nicht Aktiv oder einem anderen Server zugeordnet | Endpunkt prüfen. Änderungen an Endpunkten wirken nach spätestens 60 Sekunden |
405 METHOD_NOT_ALLOWED |
Das Endpunkt-Skript hat keine Methode für dieses HTTP-Verb | Methode im Skript ergänzen. Der Header Allow nennt die vorhandenen |
415 UNSUPPORTED_MEDIA_TYPE bei einem Upload |
Datei-Upload ist am Endpunkt nicht gesetzt | Datei-Upload setzen |
429 RATE_LIMITED |
Zu viele Anfragen oder Fehlanfragen im Rate-Limit-Fenster. Alle Geräte mit demselben API-Key teilen sich einen Zähler | Retry-After abwarten. Bei vielen Fehlanfragen den API-Key prüfen. Grenzen am Server-Profil anpassen |
503 SERVICE_UNAVAILABLE mit Retry-After: 2 |
max. Anfragen am Server-Profil ist erreicht | Anfrage wiederholen. Bei Dauerlast die Grenze am Server-Profil prüfen |
400 IDEMPOTENCY_KEY_MISSING |
Schreibende Anfrage ohne Header Idempotency-Key | Der Client sendet je Vorgang einen Idempotency-Key |
409 IDEMPOTENCY_UNRESOLVED |
Ein früherer Versuch mit demselben Key wurde hart abgebrochen | Fachdaten prüfen, siehe Wartung der Server-Tabellen |
| 503 bei Anmeldung oder Abmeldung am JWT-Endpunkt | Die Sitzung ließ sich in RESTSRV_TOKEN nicht schreiben bzw. nicht sperren |
Protokoll unter TokenStore: prüfen. Fehlt die Tabelle, Datenbankabgleich durchführen. Eine gescheiterte Abmeldung muss der Client wiederholen
|
| Gerät wird unerwartet abgemeldet | Ein Refresh-Token wurde doppelt verwendet, die Sitzung ist gesperrt | Im Protokoll nach WIEDERVORLAGE suchen
|
| Neue Bindung antwortet nicht | Bindungen liest der Dienst beim Start | REST-Dienst neu starten |
Konsole
Startet der REST-Server ohne den Parameter /service, zeigt er eine Konsole. Sie enthält ein Live-Log und einen festen Kopfbereich mit den gerade laufenden Anfragen. Als Windows-Dienst gestartet gibt es keine Konsole. Die Meldungen stehen dann nur in RESTSRV_PROTO.
| Befehl | Wirkung |
|---|---|
show <handle> |
Details einer Anfrage: Anfrage, Protokollzeilen, Antwort. Das Handle steht in der Abschlusszeile der Anfrage, z.B. 7F
|
1 … 9 |
Auswahl einer Anfrage im Kopfbereich, mit mouse on auch per Klick
|
ps |
Laufende Anfragen auflisten |
level <stufe> |
Anzeigestufe: quiet, normal oder debug. Ohne Angabe nennt die Konsole die aktuelle Stufe
|
filter <ausdruck> |
Anzeige einschränken: path=<text>, account=<name>, status>=<code>. filter aus hebt die Einschränkung auf
|
panel on / panel off |
Kopfbereich ein- bzw. ausschalten. Ausgeschaltet lässt sich das Konsolenfenster wieder zurückblättern |
mouse on / mouse off |
Auswahl per Klick. Eingeschaltet lässt sich Text nicht mehr mit der Maus markieren |
cert |
Zustand der automatischen Zertifikatserneuerung |
cert renew |
Erneuerung sofort anstoßen. Der Verlauf steht im Protokoll |
cert test |
Selbsttest gegen die Staging-Umgebung der Zertifizierungsstelle |
help / ? |
Befehlsliste anzeigen |
exit / quit |
Server geordnet beenden |
Zu den cert-Befehlen siehe Zertifikatserneuerung.
RESTSRV_PROTO enthält trotzdem jede Zeile.Betrieb hinter einem Reverse-Proxy
Ein Reverse-Proxy nimmt die Anfragen von außen an und reicht sie an den REST-Dienst weiter. Wann sich das lohnt, beschreibt Öffentliche Freigabe.
Am Proxy richten Sie ein:
- Zertifikat: Das öffentlich gültige Zertifikat liegt am Proxy. Für die Strecke zum REST-Server genügt dort ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut. Auch dieses läuft ab und muss rechtzeitig getauscht werden.
- Weiterleitung: per HTTPS an
https://<Server des REST-Dienstes>:<Port>. Eine Weiterleitung perhttp://an ein TLS-Profil weist der REST-Server mit 400 ab. - Header: alle HTTP-Methoden und Header unverändert durchreichen, insbesondere apikey, Authorization und Idempotency-Key. X-Trace-Id in der Antwort nicht entfernen. Den Header X-Forwarded-For mit der IP-Adresse des Clients setzen.
- Anfragegröße: nicht kleiner als die maximale Dateigröße (MB) der Upload-Endpunkte.
- Firewall: den Port des REST-Servers intern nur für den Proxy öffnen.
Hinter dem Proxy sieht der REST-Server als Absender nur den Proxy. Das wirkt sich so aus:
| Bereich | Auswirkung |
|---|---|
| Protokoll | rp_host bzw. die IP-Adresse in der Meldung ist die des Proxys. Den Wert von X-Forwarded-For hängt der Server als [xff=…] an Meldungen zu einer Anfrage an, höchstens 100 Zeichen. Meldungen beim Verbindungsaufbau tragen ihn nicht
|
| Statistik | rs_host ist die IP-Adresse des Proxys. X-Forwarded-For steht dort nicht
|
| Host-Beschränkung | Der Host eines Zugangs wird mit der IP-Adresse des Proxys verglichen. Einzelne Clients lassen sich nicht unterscheiden |
| Rate-Limit | Anfragen mit API-Key zählen wie gewohnt je Key. Alle Anfragen ohne API-Key teilen sich den Zähler der Proxy-Adresse |
Wartung der Server-Tabellen
Die Tabellen des REST-Servers räumen sich selbst auf. Ein regelmäßiger Eingriff ist nicht nötig.
| Tabelle | Aufräumen |
|---|---|
RESTSRV_PROTO, RESTSRV_STATS |
Gekappt, siehe Aufbewahrung |
RESTSRV_IDEMPOTENCY |
Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen, die älter als 24 Stunden sind, meldet der Server im Protokoll und löscht sie dann. Der Aufräumlauf läuft beim Start und danach höchstens stündlich |
RESTSRV_TOKEN |
Zeilen werden gelöscht, wenn Access- und Refresh-Token abgelaufen sind. Gesperrte Sitzungen bleiben bis dahin stehen. Der Aufräumlauf läuft beim Start und danach höchstens stündlich |
Eine offene Reservierung entsteht nur, wenn ein Schreibvorgang hart abgebrochen wurde, z.B. weil der Dienst beendet wurde. Ob der Vorgang gewirkt hat, ist dann offen. Wiederholt der Client ihn, erhält er 409 IDEMPOTENCY_UNRESOLVED. Prüfen Sie anhand der Protokollzeile die Fachdaten. Soll der Client vor Ablauf der 24 Stunden weitermachen, löschen Sie den Eintrag nach der Prüfung in RESTSRV_IDEMPOTENCY.