API-Nutzung überwachen

Auf dieser Seite wird beschrieben, wie Sie mit API-Messwerten Ihre Nutzung von Google APIs und Google Cloud APIs verfolgen und besser verstehen.

Google APIs bietet detaillierte Nutzungsmesswerte, die Ihnen helfen können:

• Verfolgen und verstehen Sie Ihre Nutzung von Google APIs.
• Überwachen Sie die Leistung Ihrer Anwendungen und Google APIs.
• Probleme zwischen Ihren Anwendungen und Google APIs ermitteln.

Sie kann erheblich schneller helfen, wenn Sie Probleme beheben oder technischen Support von Google benötigen.

Die von Google APIs erzeugten Messwerte sind die Standardsignale, anhand derer Site Reliability Engineers den Zustand eines Dienstes bewerten. Diese Messwerte umfassen Anfrageanzahl, Fehlerraten, Gesamtlatenzen, Backend-Latenzen, Anfragegrößen und Antwortgrößen. Informationen zu API-Messwerten finden Sie in der Cloud Monitoring-Dokumentation.

Sie können sich API-Messwerte an zwei Orten ansehen: im API-Dashboard und in Cloud Monitoring. Die angezeigten Messwerte beziehen sich auf Ihr Projekt und geben nicht den Gesamtstatus des Dienstes wieder.

API-Dashboard verwenden

Die API-Messwerte lassen sich am einfachsten über das API-Dashboard der Google Cloud Console aufrufen. Hier erhalten Sie eine Übersicht über sämtliche Messwerte zu Ihrer API-Nutzung oder können sich die Nutzung einer bestimmten API im Detail ansehen.

So erhalten Sie eine Übersicht über Ihre API-Nutzung:

1. Rufen Sie in der Cloud Console den Abschnitt APIs und Dienste auf. Das Haupt-API-Dashboard wird standardmäßig angezeigt. Hier sehen Sie alle APIs, die momentan für Ihr Projekt aktiviert sind, sowie Übersichtsdiagramme für die folgenden Messwerte:

   • Traffic: die Anzahl der Anfragen pro Sekunde, die von oder zu Ihrem Projekt an aktivierten APIs gesendet wurden
   • Fehler: der Prozentsatz der Anfragen zu aktivierten APIs, die zu Fehlern geführt haben
   • Medianlatenz: Die Medianlatenz für Anfragen zu aktivierten APIs, sofern verfügbar.

Hinweis: Die IAM-Berechtigung "Projektbetrachter" ist zum Aufrufen dieses Dashboards ausreichend.

So können Sie Details zur Nutzung für eine bestimmte API anzeigen lassen:

1. Wählen Sie in der Liste auf der Hauptseite des API-Dashboards die gewünschte API aus. Die Übersichtsseite der API zeigt ein detailliertes Traffic-Diagramm mit einer Aufschlüsselung nach Antwortcode an.

2. Wenn Sie noch mehr Details zu den Nutzungsinformationen sehen möchten, wählen Sie Messwerte aufrufen aus. Standardmäßig werden die folgenden vorgefertigten Diagramme angezeigt. Es stehen jedoch noch mehr zur Verfügung:

   • Traffic nach Antwortcode
   • Fehler nach API-Methode
   • Gesamtlatenz für das 50., 95. und 99. Perzentil
   • Latenz nach API-Methode (Medianwert)

3. Wenn Sie weitere Diagramme hinzufügen möchten, können Sie über das Drop-down-Menü Grafiken auswählen weitere vorgefertigte Diagramme auswählen.

Cloud Monitoring verwenden

Wenn Sie Cloud Monitoring verwenden, erhalten Sie mithilfe des Metrics Explorers einen Überblick über die verfügbaren Messwertdaten, um einen besseren Einblick in Ihre API-Nutzung zu erhalten. Cloud Monitoring unterstützt eine Vielfalt an Messwerten, die Sie mit Filtern und Aggregationen kombinieren können. Auf diese Weise erhalten Sie neue und aufschlussreiche Einblicke in Ihre Kontingentnutzung. So haben Sie z. B. die Möglichkeit, einen Messwert zur Anzahl der Anfragen mit einem Filter für die Klasse des HTTP-Antwortcodes zu kombinieren, um dann in einem erstellten Dashboard Fehlerraten im Zeitverlauf anzeigen zu lassen. Sie können sich aber auch für das 95. Perzentil die Latenz von Anfragen an die Cloud Pub/Sub API ansehen.

Verfügbare Messwerte

In der folgenden Tabelle sind die verfügbaren serviceruntime-Messwerte aufgeführt. Zu den Messwerten zur API-Nutzung gehören solche, bei denen consumed_api als überwachte Ressource angegeben ist.

Den Strings vom Typ "metric type" in dieser Tabelle muss serviceruntime.googleapis.com/ vorangestellt werden. Dieses Präfix wurde in den Einträgen der Tabelle weggelassen. Verwenden Sie beim Abfragen eines Labels das Präfix metric.labels.. Beispiel: metric.labels.LABEL="VALUE".

Messwerttyp ^Startphase (Ebenen der Ressourcenhierarchie) Anzeigename
Art, Typ, Einheit Überwachte Ressourcen	Beschreibung Labels
api/request_count ^GA  (Projekt) Anzahl der Anfragen
DELTA, INT64, 1 api consumed_api produced_api	Die Anzahl der abgeschlossenen Anfragen. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 1.800 Sekunden lang keine Daten angezeigt. protocol: Das Protokoll der Anfrage, z. B. „http“ oder „grpc“. response_code: HTTP-Antwortcode für HTTP-Anfragen oder HTTP-äquivalenter Code für gRPC-Anfragen. Weitere Informationen zur Codezuordnung finden Sie unter https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto. response_code_class: Die Antwortcodeklasse für HTTP-Anfragen oder die entsprechende HTTP-Klasse für gRPC-Anfragen, z.B. „2xx“, „4xx“. grpc_status_code: Der numerische gRPC-Antwortcode für gRPC-Anfragen oder gRPC-äquivalenter Code für HTTP-Anfragen. Weitere Informationen zur Codezuordnung finden Sie unter https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto.
api/request_latencies ^GA (Projekt) Anfragelatenzen
DELTA, DISTRIBUTION, s api consumed_api produced_api	Verteilung der Latenzen in Sekunden für Nicht-Streaming-Anfragen. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 1.800 Sekunden keine Daten angezeigt.
api/request_latencies_backend ^GA (Projekt) Backend-Latenzen anfordern
DELTA, DISTRIBUTION, s api produced_api	Verteilung der Backend-Latenzen in Sekunden für Nicht-Streaming-Anfragen. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 1.800 Sekunden lang keine Daten angezeigt.
api/request_latencies_overhead ^GA  (Projekt) Latenzen für den Anfrage-Overhead
DELTA, DISTRIBUTION, s api produced_api	Verteilung der Anfragelatenzen in Sekunden für Nicht-Streaming-Anfragen ohne das Backend. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 1.800 Sekunden keine Daten angezeigt.
api/request_sizes ^GA  (Projekt) Anfragegrößen
DELTA, DISTRIBUTION, By api consumed_api produced_api	Verteilung der Anfragegrößen in Byte, die beim Abschluss der Anfrage erfasst wurden. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 1.800 Sekunden keine Daten angezeigt.
api/response_sizes ^GA  (project) Antwortgrößen
DELTA, DISTRIBUTION, By api consumed_api produced_api	Verteilung der Antwortgrößen in Byte, die beim Abschluss der Anfrage aufgezeichnet werden. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 1.800 Sekunden keine Daten angezeigt.
quota/allocation/usage ^GA (Projekt, Ordner, Organisation) Nutzung von Zuteilungskontingenten
GAUGE, INT64, 1 consumer_quota producer_quota	Das gesamte verbrauchte Zuteilungskontingent. Werte, die mehr als einmal pro Minute gemeldet werden, werden verworfen. Wenn keine Änderungen an der Kontingentnutzung eingehen, wird der letzte Wert mindestens alle 24 Stunden wiederholt. Alle 60 Sekunden wird eine Stichprobe erstellt. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe.
quota/concurrent/exceeded ^ALPHA  (project, folder, organization) Concurrent Quota Exceeded
DELTA, INT64, 1 consumer_quota	Die Anzahl der Versuche, das gleichzeitige Kontingent zu überschreiten. Alle 86.400 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 180 Sekunden lang keine Daten angezeigt. limit_name: Der Name des Kontingentlimits, z. B. „Anfragen pro Tag“. oder „IP-Adressen in Verwendung“. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe. time_window: Die Fenstergröße für die Limits für parallele Vorgänge.
quota/concurrent/limit ^ALPHA  (project, folder, organization) Gleichzeitiges Kontingentlimit
GAUGE, INT64, 1 consumer_quota producer_quota	Das gleichzeitige Limit für das Kontingent. Die Stichprobenerhebung erfolgt alle 86.400 Sekunden. Nach der Stichprobe werden bis zu 180 Sekunden lang keine Daten angezeigt. limit_name: Der Name des Kontingentlimits, z. B. „Anfragen pro Tag“. oder „IP-Adressen in Verwendung“. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe. time_window: Die Fenstergröße für die Limits für parallele Vorgänge.
quota/concurrent/usage ^ALPHA  (project, folder, organization) Gleichzeitige Inanspruchnahme des Kontingents
GAUGE, INT64, 1 consumer_quota producer_quota	Die gleichzeitige Nutzung des Kontingents. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 180 Sekunden lang keine Daten angezeigt. limit_name: Der Name des Kontingentlimits, z. B. „Anfragen pro Tag“ oder „Besetzte IP-Adressen“. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe. time_window: Die Fenstergröße für die Limits für parallele Vorgänge.
quota/exceeded ^GA (Projekt, Ordner, Organisation) Fehler: Kontingent überschritten
GAUGE, BOOL, 1 consumer_quota	Der Fehler ist aufgetreten, als das Kontingentlimit überschritten wurde. Alle 60 Sekunden wird eine Stichprobe erstellt. limit_name: Der Name des Kontingentlimits, z. B. „Anfragen pro Tag“ oder „Besetzte IP-Adressen“. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe.
quota/limit ^GA  (project, folder, organization) Kontingentlimit
GAUGE, INT64, 1 consumer_quota producer_quota	Das Limit für das Kontingent. Die Stichprobenerhebung erfolgt alle 86.400 Sekunden. limit_name: Der Name des Kontingentlimits, z. B. „Anfragen pro Tag“. oder „IP-Adressen in Verwendung“. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe.
quota/rate/net_usage ^GA (Projekt, Ordner, Organisation) Nutzung von Ratenkontingenten
DELTA, INT64, 1 consumer_quota producer_quota	Das gesamte genutzte Ratenkontingent. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 240 Sekunden lang keine Daten angezeigt. method: Der Name der API-Methode, z. B. „disks.list“. quota_metric: Der Name des Kontingentmesswerts oder der Kontingentgruppe.
reserved/metric1 ^EARLY_ACCESS  (project) Eingestellt
DELTA, INT64, 1 deprecated_resource	Eingestellt. Alle 60 Sekunden wird eine Stichprobe erstellt. Nach der Stichprobe werden bis zu 180 Sekunden lang keine Daten angezeigt. quota_name: Deprecated. credential_id: Deprecated. quota_location: Eingestellt.

Die Tabelle wurde am 10.10.2024 um 16:45:27 UTC erstellt.

Wenn Sie sich API-Messwerte im Metrics Explorer ansehen möchten, wählen Sie als Ressourcentyp Consumed API und dann einen der serviceruntime Messwerte aus. Anschließend können Sie die Daten mithilfe der Filter- und Aggregationsoptionen verfeinern. Nachdem Sie die gewünschten API-Nutzungsinformationen gefunden haben, können Sie mit Cloud Monitoring benutzerdefinierte Dashboards und Benachrichtigungen erstellen. Dies hilft Ihnen, eine robuste Anwendung aufrechtzuerhalten. Auf den folgenden Seiten erhalten Sie Informationen über die Vorgehensweise:

• Diagramme erstellen
• Einführung in Benachrichtigungen
• Benachrichtigungsrichtlinien verwalten

Weitere Informationen finden Sie unter Metrics Explorer.

Mithilfe von API-Messwerten Fehler beheben

API-Messwerte können besonders hilfreich sein, wenn Sie sich bei auftretenden Problemen an Google wenden müssen – Sie können daran aber eventuell auch erkennen, dass Sie den Support gar nicht erst kontaktieren müssen. Beispiel:

• Wenn sämtliche Aufrufe eines Dienstes mit einer bestimmten Anmelde-ID fehlschlagen, mit allen anderen Anmelde-IDs jedoch erfolgreich sind, stimmt wahrscheinlich mit dem Konto etwas nicht. Sie können dieses Problem leicht selbst lösen können, ohne ein Ticket eröffnen zu müssen.
• Bei der Behebung eines Fehlers in Ihrer Anwendung bemerken Sie, dass deren reduzierte Leistung mit einer anhaltenden Erhöhung der Latenz für das 50. Perzentil eines kritischen GCP-Dienstes korreliert. In diesem Fall sollten Sie uns sofort kontaktieren und auf die betreffenden Daten hinweisen, damit wir uns so schnell wie möglich um das Problem kümmern können.
• Die Latenzen für einen GCP-Dienstbericht sehen gut und unverändert aus, aber Ihre In-App-Messwerte melden bei Aufrufen des Dienstes eine ungewöhnlich hohe Latenz. Das ist ein Hinweis auf Probleme im Netzwerk. Wenden Sie sich an Ihren Netzwerkanbieter (in einigen Fällen ist das Google), damit dieser mit der Fehlerbehebung beginnen kann.

Best Practices

API-Messwerte sind zwar äußerst hilfreich, es gibt allerdings einige Dinge zu beachten, damit sie auch wirklich nützliche Informationen liefern. Das gilt insbesondere bei der Einrichtung von auf Messwerten basierenden Benachrichtigungen. Die folgenden Best Practices helfen Ihnen, API-Messwertdaten optimal zu nutzen.

Verursacht die Latenz ein Problem?

Während einige Dienste recht latenzempfindlich sind, spielen für andere Skalierbarkeit und Zuverlässigkeit eine größere Rolle. Einige APIs wie Cloud Storage oder BigQuery können für mehrere Sekunden eine hohe Latenz haben, ohne dass es Kunden auffällt. Daten aus API-Messwerten liefern Ihnen Informationen dazu, was Ihre Nutzer bei einem bestimmten Dienst brauchen.

Abweichungen von der Norm sind der Schlüssel

Bevor Sie für einen bestimmten Messwert eine Benachrichtigung einrichten, überlegen Sie sich, was als ungewöhnliches Verhalten gilt. Ein Blick auf Ihre API-Messwerte liefert Ihnen die Information, dass bei den meisten Diensten die Latenz einer Normalverteilung folgt: ein hoher Ausschlag in der Mitte, der nach beiden Seiten hin abfällt. Mithilfe der Messwerte können Sie die Normalverteilung "lesen" und Ihre App entsprechend so entwickeln, dass sie im Bereich der Verteilungskurve gut funktioniert. Mithilfe von Messwerten können Sie Änderungen bei der Verteilung mit Zeitpunkten korrelieren, zu denen die App nicht wie vorgesehen funktioniert, und auf diese Weise einem Problem auf den Grund gehen. Das 99. Perzentil unterscheidet sich erwartungsgemäß sehr stark vom Median. Die Perzentile selbst sollten sich im Laufe der Zeit jedoch nicht stark verändern.

Vielleicht können Sie auch beobachten, dass einige Arten von Anfragen länger dauern als andere. Wenn die mittlere Größe eines in Google Fotos hochgeladenen Bildes 4 MB beträgt, Sie normalerweise aber RAW-Dateien mit einer Größe von 20 MB hochladen, ist Ihre durchschnittliche Zeit zum Hochladen von 20 Fotos wahrscheinlich wesentlich länger als die der meisten anderen Nutzer – trotzdem ist das Verhalten für Sie normal.

All das bedeutet: Eine Benachrichtigung gleich beim ersten Auftreten eines sekundenlangen RPC- oder 5xx-HTTP-Aufrufs einzurichten, ist nicht besonders nützlich. Wenn Sie einen Google-Dienst als mögliche Ursache für ein Problem bei Ihrer Anwendung untersuchen, vergleichen Sie stattdessen die Rückgabecodes und die Latenzzeiten im Zeitverlauf und achten Sie auf anhaltende Abweichungen von der Norm, die mit beobachteten Problemen in Ihrer Anwendung korrelieren.

Traffic-Rate

API-Messwerte sind am nützlichsten, wenn ein hohes Volumen an Traffic zur API anfällt. Wenn Sie einen Dienst nur zeitweise aufrufen, sind Ihre API-Messwerte statistisch nicht valide und liefern Ihnen keine aussagekräftigen Erkenntnisse.

Wenn Sie beispielsweise die Latenz für das 99,5. Perzentil für einen Dienst verfolgen und nur 100 Aufrufe pro Stunde durchführen, erhalten Sie bei der Messung über einen Zeitraum von zwei Stunden lediglich einen Datenpunkt, der das 99,5. Perzentil repräsentiert. Das verrät Ihnen nicht viel über das normale Verhalten der API oder der Anwendung. Achten Sie darauf, dass die Traffic-Rate, das verfolgte Perzentil und das berücksichtigte Zeitfenster viele aufschlussreiche Datenpunkte generieren, denn ansonsten helfen Ihnen die Daten beim Monitoring nicht weiter.

Unterstützte APIs

Alle Google APIs und Google Cloud APIs sowie APIs, die auf Cloud Endpoints und API Gateway basieren, unterstützen API-Messwerte. Wenn Sie API-Nutzer sind, können Sie die Consumed API-Messwerte im API-Dashboard aufrufen. Wenn Sie API-Ersteller sind, können Sie sich die Produzierten API-Messwerte im Endpoints-Dashboard ansehen.