API-Tracing

Nachdem Sie den Extensible Service Proxy (ESP) und den Back-End-Code Ihrer API bereitgestellt haben, fängt der ESP alle Anfragen ab und führt die erforderlichen Prüfungen durch, bevor die Anfrage an das API-Back-End weitergeleitet wird. Wenn das Back-End antwortet, sammelt und meldet der ESP Telemetriedaten. Ein Teil der vom ESP 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
  • ESP so einstellen, dass Trace Sampling deaktiviert wird.

Traces für Ihre API anzeigen lassen

So können Sie Traces für Ihre API anzeigen lassen:

  1. Wechseln Sie zur Seite Endpoints > Dienste für Ihr Projekt.

    Zur Seite "Endpoints-Dienste"

  2. Wenn Sie mehrere APIs haben, klicken Sie einfach auf die API, für die Sie Traces anzeigen lassen möchten.

  3. Achten Sie darauf, dass Sie sich auf dem Tab Übersicht befinden.

  4. Scrollen Sie nach unten und klicken Sie auf Traces ansehen. Die Seite Trace-Liste von Cloud Trace wird angezeigt.

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

Auf der Seite Trace List (Trace-Liste) können Sie individuelle Traces aufschlüsseln und die Spans abrufen, die der ESP in einem Trace erzeugt.

Beispiel-Trace mit Spans

Weitere Informationen zur Seite Trace List (Trace-Liste) finden Sie unter Traces in der Cloud Console ansehen.

Vom ESP erstellte Spans

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.
  • Und so weiter.

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 den 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.