Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

API-Tracing

Nachdem Sie den Extensible Service Proxy (ESP) oder Extensible Service Proxy V2 (ESPv2) und den Back-End-Code Ihrer API bereitgestellt haben, Der Proxy fängt alle Anfragen ab und führt alle erforderlichen Prüfungen durch, bevor die Anfrage an das API-Back-End weitergeleitet wird. Wenn das Back-End 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, um Trace Sampling zu deaktivieren.

Traces ansehen

Traces verfolgen eingehende Anfragen an Ihre API sowie die verschiedenen Ereignisse (z. B. RPC-Aufrufe oder instrumentierte Codeabschnitte) und die hierfür benötigten Zeiten genau. Diese Ereignisse werden im Trace als Spans dargestellt.

Rufen Sie die Seite "Cloud Trace" in der Google Cloud Console auf, um Traces für Ihr Projekt anzusehen:

Zu Trace

Auf der Seite Trace-Liste können Sie per Aufschlüsselung ein einzelner Trace 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 aufzurufen.

Die für Ihre API erstellten Traces und Spans variieren, 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 List (Trace-Liste) finden Sie unter Traces in der Cloud Console ansehen.

Von ESPv2 erstellte Spans

ESPv2 erstellt Traces im folgenden Format:

Beispiel-Trace mit Spans für ESPv2

ESPv2 erstellt mindestens zwei Spans pro Trace:

  • Ein ingress OPERATION_NAME-Span für die gesamte Anfrage und Antwort.
  • Ein router BACKEND egress-Span für die Zeit, in der ESPv2 auf das Back-End wartet, bis das Back-End die Anfrage verarbeitet und geantwortet hat. Dies beinhaltet den Netzwerk-Hop zwischen ESPv2 und dem Back-End.

Abhängig von der Konfiguration Ihrer API kann ESPv2 zusätzliche Spans erstellen:

  • Wenn für die API eine Authentifizierung erforderlich ist, speichert ESPv2 den für die Authentifizierung benötigten öffentlichen Schlüssel 5 Minuten lang im Cache. Befindet sich der öffentliche Schlüssel nicht im Cache, ruft ESPv2 den öffentlichen Schlüssel 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 Informationen, die zur Überprüfung des API-Schlüssels benötigt werden, im Cache. Befinden sich die Informationen nicht im Cache, ruft ESPv2 Service Control auf und erstellt einen Service Control remote call: Check-Span.

Im Allgemeinen erstellt ESPv2 nur Spans für Netzwerkaufrufe, die die eingehende Anfrage blockieren. Anfragen, die nicht blockiert werden, werden nicht verfolgt. Bei jeder lokalen Verarbeitung werden Zeitereignisse statt 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. Jeder Anfrage, die den Cache verwendet, wird ein Trace-Ereignis in Trace zugeordnet.

Von ESP erstellte Spans

Der ESP erstellt Traces im folgenden Format:

Beispiel-Trace mit Spans für den ESP

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 der Seite Trace-Preise detaillierte Preisinformationen entnehmen.

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.

App Engine

So deaktivieren Sie ESP Trace Sampling in der flexiblen App Engine-Umgebung:

  1. Bearbeiten Sie die Datei app.yaml. Fügen Sie im Abschnitt endpoints_api_service die Option trace_sampling hinzu und setzen Sie den Wert auf false. Beispiel:
    endpoints_api_service:
      name: example-project-12345.appspot.com
      rollout_strategy: managed
      trace_sampling: false
    

    Wenn Ihre Anwendung auf Mikrodiensten basiert, müssen Sie in jeder app.yaml-Datei trace_sampling: false einfügen.

  2. Wenn Sie das Cloud SDK kürzlich nicht aktualisiert haben, führen Sie folgenden Befehl aus:
    gcloud components update
    
  3. Speichern Sie die app.yaml-Datei (oder -Dateien).
  4. Stellen Sie den Back-End-Code und den ESP in App Engine bereit:
    gcloud app deploy
    

So aktivieren Sie Trace Sampling wieder:

  1. Entfernen Sie die Option trace_sampling aus der Datei app.yaml.
  2. Stellen Sie den Back-End-Code und den ESP in App Engine bereit:
    gcloud app deploy
    

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 zum Durchsuchen aller Traces und Join-Spans für eine einzelne Anfrage verwendet. Wenn in der Anfrage kein Trace-Kontext angegeben und Trace aktiviert ist, wird für alle Trace-Spans eine zufällige Trace-ID generiert.

Im folgenden Beispiel korreliert Cloud Trace Spans von ESPv2 (1) mit Spans, die vom Back-End (2) für eine einzelne Anfrage erstellt wurden. Damit lassen sich Latenzprobleme im gesamten System beheben:

Beispiel-Trace-Kontextverteilung für ESPv2

Weitere Informationen finden Sie unter OpenTelemetry Core Concepts: Context Propagation (in englischer Sprache).

Unterstützte Header

ESPv2 unterstützt die folgenden Header zur Verteilung des Trace-Kontexts:

  • traceparent: Der Standard-Header zur Verteilung des Trace-Kontexts in W3C. Wird von den meisten modernen Tracing-Frameworks unterstützt.
  • x-cloud-trace-context: Header-Header zur Verteilung des Trace-Kontexts auf der GCP Wird von älteren Tracing-Frameworks und den Google-Bibliotheken unterstützt, 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 Referenzverfolgung des traceparent-Kontexts. ESPv2 extrahiert diesen Header standardmäßig und übergibt ihn. Weitere Informationen zum Ändern des Standardverhaltens finden Sie unter ESPv2-Tracing-Startoptionen.