Verteiltes Tracing aktivieren

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite werden die Schritte beschrieben, die zum Konfigurieren des verteilten Tracings für Ihre Apigee-Laufzeit erforderlich sind. Wenn Sie verteilte Tracing-Systeme noch nicht kennen und weitere Informationen erhalten möchten, lesen Sie den Artikel Verteiltes Tracing.

Einführung

Mit Systemen für verteiltes Tracing können Sie eine Anfrage in einem Softwaresystem über mehrere Anwendungen, Dienste und Datenbanken sowie Vermittler wie Proxys hinweg verfolgen. Diese Tracing-Systeme generieren Berichte, in denen die von einer Anfrage bei jedem Schritt benötigte Zeit angezeigt wird. Tracing-Berichte können auch eine detaillierte Ansicht der verschiedenen Dienste liefern, die während einer Anfrage aufgerufen werden. Dadurch erhalten Sie ein besseres Verständnis dafür, was bei jedem Schritt in Ihrem Softwaresystem geschieht.

Das Trace-Tool in Apigee Edge und das Debugging-Tool in Apigee sind nützlich, um Ihre API-Proxys zu debuggen und zu überwachen. Diese Tools senden jedoch keine Daten an Server für verteiltes Tracing wie Cloud Trace oder Jaeger. Wenn Sie Apigee-Laufzeitdaten in einem verteilten Tracing-Bericht ansehen möchten, müssen Sie das verteilte Tracing in Ihrer Apigee-Laufzeit explizit aktivieren. Nach dem Aktivieren von Tracing kann die Laufzeit Trace-Daten an verteilte Tracing-Server senden und an einem vorhandenen Trace teilnehmen. Dadurch können Sie Daten innerhalb und außerhalb des Apigee-Systems von einem einzigen Ort aus ansehen.

In den Berichten zum verteilten Tracing können Sie folgende Informationen sehen:

Ausführungszeit eines gesamten Ablaufs
Zeitpunkt, zu dem die Anfrage empfangen wird
Zeitpunkt, zu dem die Anfrage an das Ziel gesendet wird
Zeitpunkt, zu dem die Antwort vom Ziel empfangen wird
Ausführungszeit jeder Richtlinie in einem Ablauf
Ausführungszeit von Dienstaufrufen und Zielabläufen
Zeitpunkt, zu dem die Antwort an den Client gesendet wird

Im Bericht zum verteilten Tracing können Sie die Ausführungsdetails der Abläufe als Spans anzeigen lassen. Ein Span bezieht sich auf die Zeit, die ein Ablauf in einem Trace benötigt. Die für die Ausführung eines Ablaufs benötigte Zeit wird als Summe der Zeiten angezeigt, die zum Ausführen der einzelnen Richtlinien im Ablauf erforderlich sind. Sie können sich die folgenden Abläufe als einzelne Spans anzeigen lassen:

Anfrage
- Proxy
  - PreFlow
  - PostFlow
- Ziel
  - PreFlow
  - PostFlow
Antwort
- Proxy
  - PreFlow
  - PostFlow
- Ziel
  - PreFlow
  - PostFlow

Nachdem Sie das verteilte Tracing aktiviert haben, erfasst die Apigee-Laufzeit standardmäßig eine Reihe vordefinierter Variablen. Weitere Informationen finden Sie unter Standard-Trace-Variablen im Tracing-Bericht. Mit der TraceCapture-Richtlinie können Sie das Standardverhalten der Laufzeit erweitern und zusätzliche Ablauf-, Richtlinien- oder benutzerdefinierte Variablen erfassen. Weitere Informationen finden Sie unter TraceCapture-Richtlinie.

Ein eingehender API-Aufruf an Apigee kann Trace-Header enthalten, da der Aufruf Teil eines vorhandenen Trace ist. In diesem Fall nimmt Apigee den vorhandenen Trace auf und gibt die Header an den ausgehenden API-Aufruf weiter. Die Apigee-Laufzeit versteht das Headerformat Zipkin B3. Daher werden die Header x-b3-traceid, x-b3-spanid und x-b3-sampled erkannt, wenn Sie an einem vorhandenen Trace teilnehmen. Wenn jedoch im eingehenden API-Aufruf keine Trace-Header vorhanden sind, fügt Apigee seine Trace-Header hinzu und gibt sie an den ausgehenden API-Aufruf weiter. Andere Dienste können auf die Header zugreifen und am Tracing teilnehmen, falls erforderlich.

Standard-Trace-Variablen im Tracing-Bericht

Wenn das verteilte Tracing aktiviert ist, können Sie die folgenden vordefinierten Variablen im Tracing-Bericht sehen. Die Variablen sind in den folgenden Spans sichtbar:

POST_RESP_SENT: Dieser Span wird hinzugefügt, nachdem eine Antwort vom Zielserver empfangen wurde.
POST_CLIENT_RESP_SENT: Dieser Span wird hinzugefügt, nachdem die Proxyantwort an den Client gesendet wurde.

Variablen im Span POST_RESP_SENT

Die folgenden Variablen sind im Span POST_RESP_SENT sichtbar:

REQUEST_URL (request.url)
REQUEST_VERB (request.verb)
RESPONSE_STATUS_CODE (response.status.code)
ROUTE_NAME (route.name)
ROUTE_TARGET (route.target)
TARGET_BASE_PATH (target.basepath)
TARGET_HOST (target.host)
TARGET_IP (target.ip)
TARGET_NAME (target.name)
TARGET_PORT (target.port)
TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
TARGET_SSL_ENABLED (target.ssl.enabled)
TARGET_URL (target.url)

Variablen im Span POST_CLIENT_RESP_SENT

Die folgenden Variablen sind im Span POST_CLIENT_RESP_SENT sichtbar:

API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
ENVIRONMENT_NAME (environment.name)
FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
IS_ERROR (is.error)
MESSAGE_ID (message.id)
MESSAGE_STATUS_CODE (message.status.code)
PROXY_BASE_PATH (proxy.basepath)
PROXY_CLIENT_IP (proxy.client.ip)
PROXY_NAME (proxy.name)
PROXY_PATH_SUFFIX (proxy.pathsuffix)
PROXY_URL (proxy.url)

Unterstützte Systeme für verteiltes Tracing

Die Apigee-Laufzeit unterstützt die folgenden Systeme für verteiltes Tracing:

Cloud Trace
Jaeger

Sie können Ihre Apigee-Laufzeit so konfigurieren, dass die Trace-Daten entweder an ein Cloud Trace- oder an ein Jaeger-System gesendet werden.

Da das Tracing aller API-Aufrufe in der Apigee-Laufzeit die Leistung beeinträchtigen würde, können Sie in Apigee eine probabilistische Abtastrate konfigurieren. Mit der Abtastrate können Sie die Anzahl der API-Aufrufe angeben, die für verteiltes Tracing gesendet werden. Wenn Sie beispielsweise für die Abtastrate 0.4 angeben, werden 40 % der API-Aufrufe zum Tracing gesendet. Weitere Informationen finden Sie unter Überlegungen zur Leistung.

Die maximal konfigurierbare Abtastrate ist 0.5.

Apigee-Laufzeiten für Cloud Trace konfigurieren

Sowohl die Apigee-Laufzeit als auch die Apigee Hybrid-Laufzeit unterstützen verteiltes Tracing mithilfe von Cloud Trace. Wenn Sie Jaeger verwenden, können Sie diesen Abschnitt überspringen und mit Verteiltes Tracing für Jaeger aktivieren fortfahren.

Apigee-Laufzeit für Cloud Trace konfigurieren

Zur Verwendung von Cloud Trace mit einer Apigee-Laufzeit muss in Ihrem Google Cloud-Projekt die Cloud Trace API aktiviert sein. Mit dieser Einstellung kann Ihr Google Cloud-Projekt Trace-Daten von authentifizierten Quellen empfangen.

So prüfen Sie, ob die Cloud Trace API aktiviert ist:

Rufen Sie in der Google Cloud Console APIs und Dienste auf:
Zu "APIs und Dienste"
Klicken Sie auf APIs und Dienste aktivieren.
Geben Sie in der Suchleiste Trace API ein.
Wenn API aktiviert angezeigt wird, ist diese API bereits aktiviert und Sie müssen nichts tun. Klicken Sie andernfalls auf Aktivieren.

Apigee Hybrid-Laufzeit für Cloud Trace konfigurieren

Die Cloud Trace API muss aktiviert sein, um Cloud Trace mit einer Apigee Hybrid-Laufzeit zu verwenden. Führen Sie die Schritte unter Apigee-Laufzeit für Cloud Trace konfigurieren aus, um zu prüfen, ob die Cloud Trace API aktiviert ist.

Zusätzlich zur Aktivierung der Cloud Trace API müssen Sie das Dienstkonto iam.gserviceaccount.com hinzufügen, um Cloud Trace mit der Hybridlaufzeit verwenden zu können. Führen Sie die folgenden Schritte aus, um das Dienstkonto zusammen mit den erforderlichen Rollen und Schlüsseln hinzuzufügen:

Erstellen Sie ein neues Dienstkonto.

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

Fügen Sie dem Dienstkonto eine IAM-Richtlinienbindung hinzu:

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

Erstellen Sie einen Dienstkontoschlüssel:
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sind für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.
Fügen Sie Dienstkonto zur overrides.yaml-Datei hinzu.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

Wenden Sie die Änderungen auf die Laufzeit an.

apigeectl apply -f overrides.yaml --env=ENV_NAME

Verteiltes Tracing aktivieren

Erstellen Sie vor dem verteilten Tracing für Cloud Trace oder Jaeger die folgenden Umgebungsvariablen:

TOKEN="Authorization: Bearer $(gcloud auth print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

Wobei:

TOKEN definiert den Authentifizierungsheader mit einem Inhabertoken. Dieser Header wird beim Aufrufen von Apigee APIs verwendet. Weitere Informationen finden Sie auf der Referenzseite für den Befehl print-access-token.
ENV_NAME ist der Name einer Umgebung in Ihrer Organisation.
PROJECT_ID ist die ID des Google Cloud-Projekts.

Verteiltes Tracing für Cloud Trace aktivieren

Im folgenden Beispiel wird gezeigt, wie Sie das verteilte Tracing für Cloud Trace aktivieren:

Führen Sie diesen Apigee API-Aufruf aus:
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'",
    "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
```
Der Beispielanfragetext besteht aus folgenden Elementen:
- Die samplingRate ist auf 0.1 festgelegt. Dies bedeutet, dass ungefähr 10 % der API-Aufrufe an das verteilte Tracing gesendet werden. Weitere Informationen zum Festlegen von samplingRate für Ihre Laufzeitumgebung finden Sie unter Leistungsaspekte.
- Der Parameter exporter ist auf CLOUD_TRACE festgelegt.
- Der Endpunkt wird auf das Google Cloud-Projekt festgelegt, an das der Trace gesendet werden soll. HINWEIS: Dies muss mit dem Dienstkonto übereinstimmen, das im Konfigurationsschritt verwendet wurde.
Eine erfolgreiche Antwort sieht in etwa so aus:
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

Verteiltes Tracing für Jaeger aktivieren

Das folgende Beispiel zeigt, wie Sie das verteilte Tracing für Jaeger aktivieren:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

In diesem Beispiel:

samplingRate ist auf 0,4 festgelegt. Dies bedeutet, dass ungefähr 40 % der API-Aufrufe an das verteilte Tracing gesendet werden.
Der Parameter exporter ist auf JAEGER festgelegt.
Der Endpunkt wird auf den Ort gesetzt, an dem Jaeger installiert und konfiguriert ist.

Wenn Sie den Befehl ausführen, wird eine Antwort ähnlich der folgenden angezeigt:

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

Konfiguration des verteilten Tracings ansehen

Melden Sie sich in der Laufzeit an und führen Sie den folgenden Befehl aus, um die vorhandene Konfiguration des verteilten Tracings in Ihrer Laufzeit aufzurufen:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

Wenn Sie den Befehl ausführen, wird eine Antwort ähnlich der folgenden angezeigt:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

Konfiguration des verteilten Tracings aktualisieren

Mit dem folgenden Befehl erfahren Sie, wie Sie die vorhandene Konfiguration des verteilten Tracings für Cloud Trace aktualisieren:

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

Wenn Sie den Befehl ausführen, wird eine Antwort ähnlich der folgenden angezeigt:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

In diesem Beispiel wird die Abtastrate auf 0.05 aktualisiert.

Wenn Sie die Konfiguration für Jaeger aktualisieren möchten, legen Sie das Feld exporter in der Anfrage auf JAEGER fest.

Konfiguration des verteilten Tracings deaktivieren

Im folgenden Beispiel wird gezeigt, wie Sie das für Cloud Trace konfigurierte verteilte Tracing deaktivieren:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

Wenn Sie den Befehl ausführen, wird eine Antwort ähnlich der folgenden angezeigt:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

Trace-Einstellungen für API-Proxys überschreiben

Wenn Sie das verteilte Tracing in Ihrer Apigee-Laufzeit aktivieren, verwenden alle API-Proxys in der Laufzeit dieselbe Konfiguration für das Tracing. Sie können die Konfiguration des verteilten Tracings jedoch für einen API-Proxy oder eine Gruppe von API-Proxys überschreiben. So erhalten Sie eine genauere Kontrolle über die Tracing-Konfiguration.

Im folgenden Beispiel wird die Konfiguration des verteilten Tracings für den hello-world-API-Proxy überschrieben:

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

Sie können die Konfiguration überschreiben, um Probleme mit einem API-Proxy zu beheben, ohne die Konfiguration aller API-Proxys ändern zu müssen.

Überschreibungen von Trace-Einstellungen aktualisieren

Führen Sie folgende Schritte aus, um eine Überschreibung der Tracingkonfiguration für einen API-Proxy oder eine Gruppe von API-Proxys zu aktualisieren:

Verwenden Sie den folgenden Befehl, um vorhandene Überschreibungen der Tracingkonfiguration abzurufen:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

Dieser Befehl sollte eine Antwort ähnlich der folgenden zurückgeben, die ein Feld „Name“ enthält, das den Proxy oder die Proxys identifiziert, die von der Überschreibung gesteuert werden:

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

Verwenden Sie zum Aktualisieren des Proxys den Wert des Felds „Name”, um eine POST-Anfrage zusammen mit den aktualisierten Feldwerten an die Überschreibungskonfiguration für diesen Proxy zu senden. Beispiele:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

Trace-Einstellungsüberschreibungen löschen

So löschen Sie eine Überschreibung der Tracingkonfiguration für einen API-Proxy oder eine Gruppe von API-Proxys:

Verwenden Sie den folgenden Befehl, um vorhandene Überschreibungen der Tracingkonfiguration abzurufen:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

Dieser Befehl sollte eine Antwort ähnlich der folgenden zurückgeben, die ein Feld „Name“ enthält, das den Proxy oder die Proxys identifiziert, die von der Überschreibung gesteuert werden:

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

Verwenden Sie zum Löschen des Proxys den Wert des Felds „Name”, um eine DELETE-Anfrage an die Überschreibungskonfiguration für diesen Proxy zusammen mit den aktualisierten Feldwerten zu senden. Beispiele:
```
curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \
```

Hinweise zur Leistung

Die Aktivierung des verteilten Tracings in einer Apigee-Laufzeitumgebung kann sich negativ auf die Leistung auswirken. Die Auswirkungen können mit einer erhöhten Speichernutzung, höheren CPU-Anforderungen und einer höheren Latenz einhergehen. Das Ausmaß der Auswirkungen hängt zum Teil von der Komplexität des API-Proxys (z. B. der Anzahl der Richtlinien) und der probabilistischen Abtastrate (als samplingRate festgelegt) ab. Je höher die Abtastrate, desto höher die Auswirkungen auf die Leistung. Die Auswirkungen auf die Leistung hängen von verschiedenen Faktoren ab. Bei Verwendung des verteilten Tracings ist jedoch mit einer Leistungsabnahme von 10 bis 20 % zu rechnen.

In Umgebungen mit hohem Traffic und niedrigen Latenzanforderungen beträgt die empfohlene probabilistische Abtastrate weniger als 10 %. Wenn Sie das verteilte Tracing zur Fehlerbehebung verwenden möchten, sollten Sie die probabilistische Abtastrate (samplingRate) nur für bestimmte API-Proxys erhöhen.