API-Observability (Beobachtbarkeit) ist die Fähigkeit zu verstehen, warum sich Ihre API auf eine bestimmte Weise verhält, indem Sie die von ihr ausgegebenen Telemetriedaten untersuchen: Metriken, Logs und Traces. Es geht über das Betrachten eines festen Satzes von Dashboards hinaus. Eine gut instrumentierte API ermöglicht es Ihnen, neue Fragen über ihren internen Zustand zu stellen, einschließlich solcher, die Sie nie erwartet hätten, indem Sie nur die Daten verwenden, die sie bereits produziert.
Was API-Observability tatsächlich bedeutet
Der Begriff stammt aus der Regelungstechnik, wo ein System beobachtbar ist, wenn man seinen internen Zustand aus seinen externen Ausgaben ableiten kann. Auf Software angewendet ist eine API beobachtbar, wenn ihre Ausgaben (Telemetriedaten) ausreichen, um jedes Verhalten zu diagnostizieren, ohne neuen Code zur Hinzufügung einer Log-Zeile bereitstellen zu müssen.
Dieser letzte Teil ist wichtig. Mit Observability sollten Sie, wenn ein Kunde um 2 Uhr morgens langsame Checkout-Anfragen für Benutzer in einer bestimmten Region und einer bestimmten API-Version meldet, das „Warum“ aus bereits gesammelten Daten beantworten können. Sie instrumentieren ausreichend, um Fehlermodi zu untersuchen, die Sie nicht vorhergesagt haben. Dies ist ein anderes Ziel als Uptime-Checks, die nur Fragen beantworten, die Sie bereits wussten.
Observability vs. Monitoring
Diese Begriffe werden oft synonym verwendet, beschreiben aber unterschiedliche Dinge.
Monitoring überwacht bekannte Signale und alarmiert, wenn diese einen Schwellenwert überschreiten. Sie entscheiden im Voraus, was überwacht werden soll (Fehlerrate, CPU, p99-Latenz) und was als schlecht gilt. Monitoring beantwortet die Frage: „Geht das, was ich erwartet habe, kaputt?“
Observability ist eine Eigenschaft des Systems: wie gut seine Telemetriedaten es Ihnen ermöglichen, beliebige Fragen zum internen Zustand zu stellen. Sie beantwortet die Frage: „Warum verhält sich das so?“, selbst wenn „das“ etwas ist, wofür Sie nie ein Dashboard erstellt haben.
Einfach ausgedrückt: Monitoring sagt Ihnen, dass etwas nicht stimmt. Observability hilft Ihnen herauszufinden, warum. Sie benötigen beides. Monitoring gibt Ihnen den Alarm; Observability zeigt Ihnen den Weg vom Alarm zur Grundursache. Wenn Sie eine tiefere Behandlung der Alarmierungsseite wünschen, deckt unser Leitfaden zum API-Monitoring dies ausführlich ab.
Hier ist der Unterschied in einer Tabelle.
| Aspekt | Monitoring | Observability |
|---|---|---|
| Beantwortete Frage | Ist ein bekanntes Signal außerhalb des Bereichs? | Warum verhält sich das System so? |
| Definiert wann | Im Voraus (vordefinierte Prüfungen) | Zum Zeitpunkt der Untersuchung (Ad-hoc-Abfragen) |
| Am besten geeignet für | Bekannte Fehlermodi, SLO-Verletzungen | Neue, unerwartete Probleme |
| Ausgabe | Alarme, Status-Dashboards | Telemetriedaten mit hoher Kardinalität, abfragbar |
Die drei Säulen: Metriken, Logs, Traces
Observability basiert auf drei Arten von Telemetriedaten, oft als die drei Säulen bezeichnet. OpenTelemetry, der herstellerneutrale Standard, formalisiert diese als Telemetrie-„Signale“. OpenTelemetry unterstützt derzeit Traces, Metriken, Logs und Baggage, wobei Ereignisse und Profile in Entwicklung sind. Die klassischen drei entsprechen seinen ersten drei Signalen.
Metriken
Metriken sind numerische Messwerte, die über die Zeit aggregiert werden. Für eine API sind die wichtigsten die Anfragerate, Fehlerrate und Latenzverteilung. Melden Sie die Latenz als Perzentile (p95 und p99), nicht nur als Durchschnittswerte. Ein Durchschnitt verbirgt den langsamen "Tail", den echte Benutzer erleben.
Metriken sind kostengünstig zu speichern und schnell abzufragen, was sie ideal für Dashboards und Alarme macht. Ihre Schwäche ist die geringe Kardinalität: Sie sagen Ihnen, dass die p99-Latenz gestiegen ist, aber nicht, welche Anfragen dies verursacht haben.
Logs
Logs sind mit Zeitstempel versehene Aufzeichnungen diskreter Ereignisse. Strukturierte Logs, die als JSON mit konsistenten Feldern ausgegeben werden, sind weitaus nützlicher als Freitextzeilen, da Sie sie filtern und aggregieren können.
{
"timestamp": "2026-06-22T02:14:09Z",
"level": "error",
"method": "POST",
"path": "/v2/checkout",
"status": 503,
"duration_ms": 4812,
"trace_id": "8f3a1c9d2e7b4a16",
"user_region": "ap-southeast-1",
"api_version": "2026-05"
}
Beachten Sie das Feld trace_id. Diese ID verbindet eine Log-Zeile mit dem gesamten Anfragestrom, was uns zur dritten Säule bringt.
Traces
Ein verteilter Trace verfolgt eine Anfrage, während sie durch Dienste wandert. Jeder Hop wird zu einem Span, und Spans teilen sich eine Trace-ID, sodass Sie den vollständigen Pfad rekonstruieren und sehen können, wo Zeit verbracht wurde. Wenn eine Anfrage ein Gateway, einen Authentifizierungsdienst und drei Microservices durchläuft, zeigt der Trace, welcher Hop die 4 Sekunden hinzugefügt hat.
Traces machen das Debugging von Microservices handhabbar. Ohne sie raten Sie, welcher Dienst in der Kette langsam ist.
Die drei Säulen arbeiten zusammen. Ein Metrik-Alarm kennzeichnet den Anstieg. Ein Trace verweist auf den langsamen Dienst. Logs dieses Dienstes, gefiltert nach Trace-ID, sagen Ihnen genau, was passiert ist.
Die RED-Methode und Goldene Signale
Sie müssen nicht alles verfolgen. Die RED-Methode bietet Ihnen einen fokussierten Ausgangspunkt für jeden anfragegesteuerten Dienst. Tom Wilkie stellte sie 2015 bei Weaveworks vor, abgeleitet von Googles vier goldenen Signalen.
RED steht für:
- Rate: Anfragen pro Sekunde, die Ihre API verarbeitet.
- Errors: Die Anzahl oder Rate fehlgeschlagener Anfragen, wie z.B. 5xx-Antworten und unerwartete 4xx-Antworten.
- Duration: Die Verteilung der Anfragelatenzen, angegeben als p95 und p99.
Rate = Anfragen/Sek.
Errors = % von 5xx (und unerwarteten 4xx) Antworten
Duration = Latenzverteilung, Angabe p95 und p99 (nicht nur Durchschnitt)
RED ist anfragezentriert, was gut zu APIs, Gateways und Service Meshes passt. Sein Gegenstück, USE (Utilization, Saturation, Errors), zielt auf Infrastrukturressourcen wie CPU und Festplatte ab. Für eine API beginnen Sie mit RED und fügen USE für die darunterliegenden Hosts hinzu.
SLIs und SLOs: Signale in Ziele verwandeln
Observability-Daten werden nutzbar, wenn Sie ihnen Ziele zuweisen. Das Google SRE-Buch definiert hier zwei Begriffe.
Ein Service Level Indicator (SLI) ist ein quantitatives Maß für einen Aspekt Ihres Dienstes. Gängige SLIs sind Anfragelatenz, Fehlerrate (der Anteil aller fehlgeschlagenen Anfragen) und Durchsatz in Anfragen pro Sekunde. Diese passen gut zur RED-Methode.
Ein Service Level Objective (SLO) ist ein Zielwert oder ein Bereich für einen SLI. Zum Beispiel: „99,9 Prozent der Anfragen innerhalb eines 28-Tage-Fensters werden in weniger als 300 ms abgeschlossen.“ Das SLO sagt Ihnen und Ihrem Team, wann die API ausreichend gesund ist und wann Ingenieurszeit für Zuverlässigkeit statt für neue Funktionen aufgewendet werden sollte.
SLIs und SLOs geben Ihren Metriken Bedeutung. Ohne sie ist ein Latenzdiagramm nur eine Wellenlinie; mit ihnen ist es ein Vertrag, an dem Sie sich messen lassen können.
Die Tools: OpenTelemetry und Backends
Sie können die Observability-Tools in zwei Ebenen unterteilen: wie Sie Telemetriedaten erzeugen und wohin Sie sie senden.
Für die Erzeugung ist OpenTelemetry der Standard, den es sich lohnt zu lernen. Es ist ein Projekt der Cloud Native Computing Foundation (CNCF), entstanden aus der Fusion von OpenTracing und OpenCensus. Es ist hersteller- und toolunabhängig und funktioniert daher mit einer breiten Palette von Backends. Sein Kernprinzip ist, dass Sie die von Ihnen generierten Daten besitzen, ohne Anbieterbindung (Vendor Lock-in). Es bietet APIs, Sprach-SDKs, semantische Konventionen, das OTLP-Wire-Protokoll, Auto-Instrumentierung und den OpenTelemetry Collector.
Für Speicherung und Analyse haben Sie Optionen. Prometheus in Kombination mit Grafana ist ein gängiger Open-Source-Stack für Metriken und Dashboards. Kommerzielle Plattformen wie Datadog und Honeycomb erfassen Traces, Metriken und Logs und bieten Abfragen mit hoher Kardinalität. Wenn Sie Datadog verwenden, zeigt unser Walkthrough der Datadog API, wie Sie Daten programmatisch pushen und pullen können.
Der Sinn von OpenTelemetry ist, dass Sie einmal instrumentieren und dann Backends wechseln können, ohne neu instrumentieren zu müssen. Diese Portabilität ist der Hauptgrund, es frühzeitig einzuführen.
Wo Tests und synthetische Prüfungen passen
Observability ist nicht nur ein Anliegen der Produktion. Einige der nützlichsten Signale stammen aus Tests, die Sie absichtlich durchführen, sowohl vor als auch nach der Bereitstellung.
Shift left: Vertragstests und CI-Läufe
Bevor Code ausgeliefert wird, überprüfen Vertragstests, ob Ihre API weiterhin ihrer Spezifikation entspricht. Das Ausführen dieser Tests in CI fängt Breaking Changes ab, bevor sie Benutzer erreichen. Jeder CI-Testlauf ist ein Signal: ein Pass oder Fail, verbunden mit einem Commit, einer Umgebung und einem Zeitstempel. Diese Historie sind Observability-Daten über Ihre Release-Qualität.
Der Apidog CLI führt Ihre Testszenarien in einer Pipeline aus. Er basiert auf Node.js und benötigt Node v16 oder höher.
npm install -g apidog-cli
# Installation überprüfen
node -v && apidog -v
Führen Sie ein Testszenario gegen eine Umgebung aus. Das Umgebungs-Flag ist erforderlich, und Sie übergeben Ihr Token explizit.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Hier ist -t die ID des Testszenarios, -e die Umgebungs-ID und -r legt die Berichtsformate fest (cli, html, json, junit). Der Standard-Reporter ist cli. Um das Szenario aus einer CSV- oder JSON-Datei zu steuern, fügen Sie -d ./data.csv hinzu (das Flag -d oder --iteration-data akzeptiert einen Dateipfad). Sie können auch eine Berichtsübersicht in die Apidog-Cloud pushen.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report
Für eine vollständige Pipeline, die Sie kopieren und anpassen können, siehe unseren Apidog CLI für CI/CD-Leitfaden oder die vollständige CLI-Referenz für jedes Flag.
Synthetisches Monitoring in der Produktion
Synthetisches Monitoring führt skriptgesteuerte Anfragen gegen Ihre Live-API nach einem Zeitplan von außen aus, so wie ein Benutzer es tun würde. Es erkennt Probleme, bevor echter Traffic dies tut, und liefert Ihnen einen stetigen Strom von Latenz- und Verfügbarkeitsdatenpunkten. Ein grundlegender API-Health-Check ist die einfachste Form. Umfassendes synthetisches Monitoring erweitert dies auf mehrstufige Abläufe wie Login und anschließend Checkout.
Diese Prüfungen sind eigenständige Observability-Signale. Ein fehlgeschlagener synthetischer Lauf um 02:00 Uhr mit einer Dauer von 4 Sekunden ist genau die Art von Ereignis, die Sie in Ihre Traces und Logs einspeisen möchten. Für einen Überblick über spezialisierte Tools siehe unsere Zusammenfassung der Tools für synthetische Tests und für Produktionsüberwachungsplattformen unsere Liste der API-Monitoring-Tools.
Generieren echter Signale mit Apidog Scheduled Tasks
Apidog kann wiederkehrende synthetische Signale über Scheduled Tasks (geplante Aufgaben) erzeugen. Die Funktion führt konfigurierte Testszenarien automatisch zu festgelegten Zeiten aus, erfasst die Ergebnisse und unterstützt geplante Regressionstests. Sie finden diese Funktion unter dem Modul „Tests“ in „Scheduled Tasks“.
Ein paar Dinge, die Sie wissen sollten, bevor Sie sich darauf verlassen. Scheduled Tasks befindet sich derzeit in der Beta-Phase, behandeln Sie es also eher als sich entwickelnde als als langfristig stabile Funktion. Es erfordert auch einen konfigurierten selbst gehosteten Runner; die Optionen unter „Runs On“ listen heute einen selbst gehosteten Runner auf, wobei Apidog Cloud als „bald verfügbar“ gelistet ist. Es gibt also noch keine vollständig cloud-gehostete geplante Überprüfung.
Wenn Sie eine einrichten, wählen Sie:
- Testszenarien: ein oder mehrere auszuführende Szenarien.
- Ausführungsmodus: ein Zeitzyklus, z.B. jeden Sonntag um 23 Uhr oder alle 6 Stunden.
- Benachrichtigung: Alarme nach jedem Lauf oder nur bei Fehlern.
Die Anzahl der Läufe hängt von Ihrem Abonnementplan ab. Für eine praktische Anleitung, siehe unseren Apidog Scheduled Tasks Walkthrough.
Der Wert hier liegt im Schließen des Kreislaufs. Sie entwerfen und testen Ihre API an einem Ort und führen dann dieselben Szenarien in einem Rhythmus aus, sodass sie weiterhin Pass/Fail- und Latenzsignale erzeugen, auf die Sie reagieren können. Testen Sie Apidog kostenlos, keine Kreditkarte erforderlich, und verwandeln Sie Ihre bestehenden Testszenarien in wiederkehrende Signale.
Ein praktischer Weg zu einer beobachtbaren API
- Strukturierte Logs ausgeben mit einem konsistenten Schema und einer Trace-ID bei jeder Anfrage.
- Instrumentieren mit OpenTelemetry, damit Traces, Metriken und Logs Kontext teilen und über Backends hinweg portabel bleiben.
- RED-Metriken verfolgen (Rate, Fehler, Dauer mit p95 und p99) und diese auf einem Dashboard anzeigen.
- SLIs und SLOs definieren, damit Ihre Metriken Ziele haben, nicht nur Trends.
- Vertragstests in CI hinzufügen, um Breaking Changes vor der Veröffentlichung abzufangen.
- Synthetische Prüfungen nach einem Zeitplan gegen die Produktion durchführen, zum Beispiel mit Apidog Scheduled Tasks.
Sie müssen nicht alle sechs Schritte auf einmal ausführen. Schon der erste Schritt, strukturierte Logs mit Trace-IDs, bringt Sie weit über einfache Textlogs hinaus.
Häufig gestellte Fragen
Was ist API-Observability?
API-Observability ist die Fähigkeit, den internen Zustand einer API anhand der von ihr ausgegebenen Telemetriedaten – nämlich Metriken, Logs und Traces – zu verstehen. Eine beobachtbare API ermöglicht es Ihnen, zu untersuchen, warum sie sich auf eine bestimmte Weise verhält, einschließlich Problemen, die Sie nicht erwartet haben, ohne zuerst neue Instrumentierung hinzuzufügen.
API-Observability vs. Monitoring: Was ist der Unterschied?
Monitoring überwacht vordefinierte Signale und alarmiert, wenn sie einen Schwellenwert überschreiten, und beantwortet die Frage: „Geht etwas kaputt, das ich erwartet habe, dass es kaputt geht?“ Observability ist eine Eigenschaft des Systems, die es Ihnen ermöglicht, neue, beliebige Fragen zu seinem Verhalten zu stellen und zu beantworten: „Warum passiert das?“ Monitoring sagt Ihnen, dass etwas nicht stimmt; Observability hilft Ihnen, die Ursache zu finden. Sie benötigen beides.
Was sind die drei Säulen der Observability?
Die drei Säulen sind Metriken, Logs und Traces. Metriken sind aggregierte Zahlen wie Anfragerate und Latenz-Perzentile. Logs sind mit Zeitstempel versehene Aufzeichnungen diskreter Ereignisse, idealerweise als JSON strukturiert. Traces verfolgen eine Anfrage über Dienste hinweg, sodass Sie sehen können, wo Zeit verbraucht wurde. OpenTelemetry formalisiert diese als Telemetrie-Signale.
Wie macht man eine API beobachtbar?
Beginnen Sie mit der Ausgabe strukturierter Logs mit einer Trace-ID bei jeder Anfrage. Instrumentieren Sie Ihren Code mit OpenTelemetry, damit Metriken, Logs und Traces Kontext teilen. Verfolgen Sie RED-Metriken, definieren Sie SLIs und SLOs als Ziele, fügen Sie Vertragstests in CI hinzu und führen Sie geplante synthetische Prüfungen gegen die Produktion durch. Jeder Schritt fügt ein abfragbares Signal hinzu.
Ist OpenTelemetry für Observability erforderlich?
Nein. Observability ist eine Eigenschaft, die Sie mit jedem Telemetrie-Tooling erreichen können, und viele Teams verwendeten proprietäre Agenten lange bevor OpenTelemetry existierte. Allerdings ist OpenTelemetry der herstellerneutrale CNCF-Standard, sodass Sie durch die Einführung einmal instrumentieren und Backends wie Prometheus, Datadog oder Honeycomb wechseln können, ohne neu instrumentieren zu müssen. Es ist eine starke Standardoption, keine Anforderung.