API-Tracing

OpenAPI   |  gRPC

Nachdem Sie den Extensible Service Proxy (ESP) oder Extensible Service Proxy V2 (ESPv2) und den Backend-Code Ihrer API bereitgestellt haben, fängt der Proxy alle Anfragen ab und führt alle erforderlichen Prüfungen durch, bevor die Anfrage an die Backend API weitergeleitet wird. Wenn das Backend antwortet, sammelt und meldet der Proxy Telemetriedaten. Ein Teil der vom Proxy erfassten Telemetriedaten ist Tracing mithilfe von Cloud Trace.

Auf dieser Seite erfahren Sie, wie Sie:

• Traces in der Google Cloud Console ansehen,
• Ihre Kosten für Trace schätzen und
• Konfigurieren Sie den Proxy zum Deaktivieren von Trace Sampling.

Traces ansehen

Traces verfolgen eingehende Anfragen an Ihre API sowie verschiedene Ereignisse, z. B. RPC-Aufrufe oder instrumentierte Codeabschnitte und die genauen Zeitdaten jedes Ereignisses. Diese Ereignisse werden im Trace als Spans dargestellt.

Traces für Ihr Projekt rufen Sie auf der Seite „Cloud Trace“ in der Google Cloud Console auf:

Zu Trace

Auf der Seite Trace Explorer (Trace-Explorer) können Sie einzelne Traces aufschlüsseln und anzeigen und die Spans abrufen, die der ESP in einem Trace erzeugt. Sie können den Filter verwenden, um Traces für eine einzelne API oder einen einzelnen Vorgang anzeigen zu lassen.

Die für Ihre API erstellten Traces und Spans unterscheiden sich je nachdem, ob Ihre API ESPv2 oder ESP verwendet. Im Folgenden finden Sie eine Zusammenfassung der Trace-Formate für jede Implementierung.

Weitere Informationen zur Seite Trace Explorer finden Sie unter Traces suchen und untersuchen.

Von ESPv2 erstellte Spans

ESPv2 erstellt Traces im folgenden Format:

ESPv2 erstellt mindestens 2 Spans pro Trace:

• Ein ingress OPERATION_NAME-Span für die gesamte Anfrage und Antwort.
• Ein router BACKEND egress-Span für die Zeit, die ESPv2 wartet, bis das Backend die Anfrage verarbeitet und antwortet. Dazu gehört der Netzwerk-Hop zwischen ESPv2 und dem Backend.

Je nach Konfiguration Ihrer API erstellt ESPv2 möglicherweise zusätzliche Spans:

• Wenn die API eine Authentifizierung erfordert, speichert ESPv2 den für die Authentifizierung benötigten öffentlichen Schlüssel 5 Minuten lang. Befindet sich der öffentliche Schlüssel nicht im Cache, ruft ESPv2 ihn ab, speichert ihn im Cache und erstellt einen JWT Remote PubKey Fetch-Span.
• Wenn für die API ein API-Schlüssel erforderlich ist, speichert ESPv2 die zur Prüfung des API-Schlüssels benötigten Informationen im Cache. Befinden sich die Informationen nicht im Cache, ruft der ESPv2 die Service Control API auf und erstellt einen Service Control remote call: Check-Span.

Im Allgemeinen erstellt ESPv2 nur Spans für Netzwerkaufrufe, die die eingehende Anfrage blockieren. Nicht blockierende Anfragen werden nicht verfolgt. Bei jeder lokalen Verarbeitung werden Zeitereignisse anstelle von Spans erstellt. Beispiel:

• Für die Erzwingung von Kontingenten sind Remoteaufrufe erforderlich. Die Aufrufe werden jedoch nicht im Pfad einer API-Anfrage ausgeführt und haben keine Spans, die mit ihnen im Trace verknüpft sind.
• API-Schlüssel werden von ESPv2 für kurze Zeit im Cache gespeichert. Alle Anfragen, die den Cache verwenden, haben ein Zeitereignis im Trace.

Von ESP erstellte Spans

Warnung: Der ESP stellt keine detaillierten Informationen für Spans bereit. Außerdem werden zusätzliche Spans erstellt, die nicht aussagekräftig sind. Migrieren Sie zu ESPv2, um detaillierte Traces gemäß den Best Practices für das Tracing aufzurufen.

Der ESP erstellt Traces im folgenden Format:

ESP erstellt mindestens 4 Spans pro Trace:

• Ein Span für die gesamte Anfrage und Antwort.
• Ein CheckServiceControl-Span zum Aufrufen der Service Control-Methode services.check, mit der die Konfiguration für die API abgerufen wird.
• Ein QuotaControl-Span zum Prüfen, ob in der API ein Kontingent konfiguriert wurde.
• Ein Backend-Span, der die im Back-End-Code Ihrer API verbrachte Zeit misst.

Der ESP erstellt abhängig von der Konfiguration Ihrer API zusätzliche Spans:

• Wenn für die API eine Authentifizierung erforderlich ist, erstellt der ESP in jedem Trace einen CheckAuth-Span. Zur Authentifizierung einer Anfrage wird der für die Authentifizierung benötigte öffentliche Schlüssel vom ESP fünf Minuten lang im Cache gespeichert. Befindet sich der öffentliche Schlüssel nicht im Cache, ruft der ESP ihn ab, speichert ihn im Cache und erstellt einen HttpFetch-Span.
• Wenn für die API ein API-Schlüssel erforderlich ist, erstellt der ESP in jedem Trace einen CheckServiceControlCache-Span. Der ESP speichert die Informationen im Cache, die zur Überprüfung des API-Schlüssels benötigt werden. Befinden sich die Informationen nicht im Cache, ruft der ESP die Service Control API auf und erstellt einen Call ServiceControl server-Span.
• Wenn Sie für die API ein Kontingent festgelegt haben, erstellt der ESP in jedem Trace einen QuotaServiceControlCache-Span. Der ESP speichert die Informationen im Cache, die zur Überprüfung des Kontingents benötigt werden. Befinden sich die Informationen nicht im Cache, ruft der ESP die Service Control API auf und erstellt einen Call ServiceControl server-Span.

Trace Sampling-Rate

ESP nimmt eine kleine Anzahl von Anfragen an Ihre API als Stichprobe, um Trace-Daten zu erhalten. Zur Steuerung der Sampling-Rate hat ESP einen Anfragezähler und einen Timer. Die Sampling-Rate wird von der Anzahl der Anfragen bestimmt, die Ihre API pro Sekunde erhält. Wenn innerhalb einer Sekunde keine Anfragen eingehen, sendet ESP keinen Trace.

Ist die Anzahl der Anfragen in einer Sekunde:

• kleiner als oder gleich 999, sendet ESP 1 Trace.
• zwischen 1000 und 1999, sendet ESP 2 Traces.
• zwischen 2000 und 2999, sendet ESP 3 Traces.
• Dies sind nur einige Beispiele für die Bedeutung von Data Governance.

Zusammenfassend können Sie die Sampling-Rate mit der ceiling-Funktion schätzen: ceiling(requests per second/1000)

Trace-Kosten kalkulieren

Sie können die Trace-Kosten kalkulieren, indem Sie die Anzahl der Spans schätzen, die ESP in einem Monat an Trace sendet.

So schätzen Sie die Anzahl der Spans pro Monat:

1. Schätzen Sie die Anzahl der Anfragen, die pro Sekunde an der API eingehen. Für diese Schätzung verwenden Sie die Anfragegrafik unter Endpoints > Dienste oder Cloud Logging. Weitere Informationen finden Sie unter API überwachen.
2. Berechnen Sie die Anzahl der Traces, die der ESP pro Sekunde an Trace sendet: ceiling(requests per second/1000)
3. Schätzen Sie die Anzahl der Spans in einem Trace. Orientieren Sie sich dabei an den Informationen unter Vom ESP erstellte Spans oder prüfen Sie auf der Seite Trace List (Trace-Liste) die Traces für Ihre API.
4. Schätzen Sie die Anzahl der Sekunden pro Monat, in denen Ihre API Traffic erhält. Einige APIs erhalten beispielsweise nur zu bestimmten Tageszeiten Anfragen, andere nur sporadisch.
5. Multiplizieren Sie die Anzahl der Sekunden pro Monat mit der Anzahl der Spans.

Beispiel:

1. Angenommen, die maximale Anzahl von Anfragen pro Sekunde für eine API beträgt 5.
2. Die Trace Sampling-Rate ist: Ceiling (5/1000) = 1
3. Für die API wurde kein Kontingent konfiguriert. Es ist kein API-Schlüssel und keine Authentifizierung erforderlich. Die Anzahl der von ESP pro Trace erstellten Spans beträgt daher 4.
4. Diese API erhält nur während der Geschäftszeiten von Montag bis Freitag Anfragen. Sie erhält Traffic an ca. 576.000 Sekunden pro Monat (3.600 x 8 x 20 = 576.000).
5. Die Anzahl der Spans pro Monat beträgt ungefähr 576.000 x 4 = 2.304.000

Da Sie nun die ungefähre Anzahl von Spans in einem Monat kennen, können Sie auf der Seite Trace-Preise die detaillierten Preise ermitteln.

Trace Sampling deaktivieren

Wenn Sie verhindern möchten, dass der ESP Anfragenstichproben nimmt und Traces sendet, können Sie eine ESP-Startoption festlegen und den ESP neu starten. Die Traces, die der ESP an Cloud Trace sendet, sind unabhängig von den Grafiken, die auf der Seite Endpoints > Dienste angezeigt werden. Auch wenn Sie Trace Sampling deaktivieren, sind die Grafiken weiterhin verfügbar.

Im folgenden Abschnitt wird davon ausgegangen, dass Sie Ihre API und ESP bereits bereitgestellt haben oder mit dem Bereitstellungsprozess vertraut sind. Weitere Informationen finden Sie unter API-Back-End bereitstellen.

Compute Engine

So deaktivieren Sie ESP Trace Sampling in Compute Engine mit Docker:

1. Stellen Sie eine Verbindung zur VM-Instanz her:

   gcloud compute ssh [INSTANCE_NAME]

2. Fügen Sie in den ESP-Flags für den Befehl docker run die Option --disable_cloud_trace_auto_sampling hinzu:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. Geben Sie den Befehl docker run aus, um den ESP neu zu starten.

So aktivieren Sie Trace Sampling wieder:

1. Entfernen Sie --disable_cloud_trace_auto_sampling.
2. Geben Sie den Befehl docker run aus, um den ESP neu zu starten.

GKE

So deaktivieren Sie ESP Trace Sampling in GKE:

1. Öffnen Sie die Manifestdatei der Bereitstellung (deployment.yaml) und fügen Sie den folgenden Code in den Abschnitt containers ein:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. Starten Sie den Kubernetes-Dienst mit dem Befehl kubectl create:

   kubectl create -f deployment.yaml

So aktivieren Sie Trace Sampling wieder:

1. Entfernen Sie die Option --disable_cloud_trace_auto_sampling.
2. Starten Sie den Kubernetes-Dienst:

   kubectl create -f deployment.yaml

Wenn Sie den ESP auf einer Compute Engine-VM-Instanz ohne einen Docker-Container ausführen, gibt es für die Option --disable_cloud_trace_auto_sampling kein äquivalentes Schlüssel/Wert-Paar in den Metadaten der VM-Instanz. Sie müssen den ESP in einem Container ausführen, wenn Sie Trace Sampling deaktivieren möchten.

Ein Client kann erzwingen, dass eine Anfrage verfolgt wird. Dazu muss der Header X-Cloud-Trace-Context in die Anfrage eingefügt werden, wie unter Erzwingen der Rückverfolgung einer Anfrage beschrieben. Wenn eine Anfrage den Header X-Cloud-Trace-Context enthält, sendet der ESP die Trace-Daten auch dann an Trace, wenn Sie Trace Sampling deaktiviert haben.

Weitergabe von Trace-Kontext

Beim verteilten Tracing kann ein Anfrageheader einen Trace-Kontext enthalten, der eine Trace-ID angibt. Die Trace-ID wird verwendet, wenn ESPv2 neue Trace-Spans erstellt und an Cloud Trace sendet. Die Trace-ID wird verwendet, um alle Traces zu durchsuchen und Spans für eine einzelne Anfrage zu verknüpfen. Wenn kein Trace-Kontext in der Anfrage angegeben und Trace aktiviert ist, wird für alle Trace-Spans eine zufällige Trace-ID generiert.

Im folgenden Beispiel verknüpft Cloud Trace Spans, die von ESPv2 (1) mit Spans erstellt wurden, die vom Backend (2) für eine einzelne Anfrage erstellt wurden. Dies hilft bei der Behebung von Latenzproblemen im gesamten System:

Weitere Informationen finden Sie unter OpenTelemetry-Kernkonzepte: Kontextverteilung.

Hinweis: Verteiltes Tracing erfordert, dass Ihre Clients und/oder Ihre Back-Ends das Tracing unterstützen. Dies wird in dieser Dokumentation nicht behandelt. Wir empfehlen die Verwendung von OpenTelemetry.

Unterstützte Header

ESPv2 unterstützt die folgenden Weitergabe-Header für Trace-Kontext:

• traceparent: Der Standardheader W3C-Trace-Kontext. Unterstützt von den meisten modernen Tracing-Frameworks.
• x-cloud-trace-context: Header der Verteilung des Trace-Kontextes der GCP. Unterstützt von älteren Tracing-Frameworks und Google-Bibliotheken, aber anbieterspezifisch.
• grpc-trace-bin: Header zur Verteilung des Trace-Kontextes, der von gRPC-Back-Ends mit der Tracing-Bibliothek OpenCensus verwendet wird.

Wenn Sie eine neue Anwendung erstellen, empfehlen wir die Verwendung von traceparent Weitergabe von Trace-Kontext. ESPv2 extrahiert und leitet diesen Header standardmäßig weiter. Weitere Informationen zum Ändern des Standardverhaltens finden Sie unter Startoptionen für ESPv2 Tracing.

Hinweis: Im Gegensatz zu ESPv2 muss die Weitergabe von Trace-Kontext in ESP manuell über die Startoptionen aktiviert werden. Der ESP unterstützt den Header traceparent nicht.