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.

Weitere Informationen zu den auf dieser Seite verwendeten Begriffen finden Sie in der Cloud Trace-Übersicht.

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, Jaeger oder einen OpenTelemetry Collector.

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:

Phase Endpunkt Flow
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-Richtlinie.

Standard-Trace-Variablen im Tracing-Bericht

Gilt für:sowohl die OpenTelemetry- als auch die OpenCensus-Konfigurationen.

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:

  • RESP_SENT: Dieser Span wird hinzugefügt, nachdem eine Antwort vom Zielserver empfangen wurde. Sie enthält die Zielattribute, die unter Variablen im RESP_SENT-Zeitraum aufgeführt sind.
  • PROXY_POST_RESP_SENT: Dieser Span wird hinzugefügt, nachdem die Proxyantwort an den Client gesendet wurde. Sie enthält die Proxy-seitigen Attribute, die unter Variablen im PROXY_POST_RESP_SENT-Bereich aufgeführt sind.
  • EVENT_FLOW_RESP und EVENT_FLOW_END: Diese Spannen werden für API-Proxys hinzugefügt, die Streaming-Antworten vom Typ „Server-Sent Events (SSE)“ verarbeiten. EVENT_FLOW_RESP markiert den SSE-Antwortfluss (wird einmal pro Antwortnachricht ausgeführt). EVENT_FLOW_END markiert das Ende des SSE-Streams. Diese Spans haben derzeit keine Standardattribute. Sie werden im Trace als benannte Spans angezeigt, um die SSE-Phasen des Proxys im Tracing-Bericht sichtbar zu machen.

Standardattribute für Ressourcen

Gilt für:Nur OpenTelemetry. Dieser Abschnitt gilt nicht für die OpenCensus-Konfiguration.

Wenn Sie OpenTelemetry mit dem OTLP-Trace-Protokoll verwenden, fügt die Apigee-Laufzeit jedem ausgegebenen Span die folgenden OpenTelemetry-Ressourcenattribute gemäß der semantischen Konvention hinzu:

Attribut Beschreibung
service.name Fester Wert: apigee.googleapis.com.
service.instance.id Kennung der Message Processor-Instanz, die den Span ausgegeben hat. Wird ausgelassen, wenn die Identität des Laufzeit-Pods nicht verfügbar ist.
cloud.provider Immer gcp.
cloud.platform Immer gcp_apigee.
cloud.region Die Region, in der die Apigee-Laufzeit gehostet wird. Wenn keine Region konfiguriert ist, wird global verwendet.
cloud.resource_id Voll qualifizierter Apigee-Ressourcenpfad im Format /apigee.googleapis.com/organizations/ORG/environments/ENV.
gcp.apigee.organization Der Name der Apigee-Organisation.
gcp.apigee.environment Der Name der Apigee-Umgebung.
gcp.project_id Die Google Cloud Projekt-ID. Wird nur ausgegeben, wenn der Exporteur OPEN_TELEMETRY_CLOUD_TRACE ist.

Span-Arten

Gilt für:sowohl die OpenTelemetry- als auch die OpenCensus-Konfigurationen.

Apigee gibt Spans mit den folgenden SpanKind-Werten aus:

SpanKind Spans, die mit dieser Art ausgegeben werden
SERVER Der Stamm-Proxy-Span (einer pro Proxy-Aufruf), der die eingehende Anfrage darstellt, die von der Apigee-Laufzeit empfangen wurde.
INTERNAL Alle anderen Spannen, einschließlich Flussspannen (z. B. RESP_SENT und PROXY_POST_RESP_SENT) und jeder Richtlinien-Schrittspanne (z. B. AssignMessage, VerifyAPIKey, ServiceCallout, JavaScript, KeyValueMapOperations).

Apigee gibt keine Spans für CLIENT, PRODUCER oder CONSUMER aus. Insbesondere werden ausgehende Aufrufe von Apigee an das Ziel-Backend nicht als separate CLIENT-Spans ausgegeben. Der ausgehende Aufruf wird in den vorhandenen INTERNAL-Ablaufspans dargestellt und der traceparent-Header wird an das Ziel weitergegeben, sodass der Zieldienst eine eigene SERVER-Span ausgeben und dem selben Trace beitreten kann.

Variablen im Span RESP_SENT

Die folgenden Variablen sind im Span RESP_SENT sichtbar. In der Spalte OTEL semantic variable (OTEL-semantische Variable) sehen Sie den Namen der OpenTelemetry-Konvention, der verwendet wird, wenn spanSemantics auf OTEL festgelegt ist. In der Spalte Attribute (Attribut) sehen Sie den alten Attributnamen.

Legacy-Variable OTEL-Semantikvariable Attribut Beschreibung
REQUEST_URL url.full request.url Vollständige URL der eingehenden Clientanfrage, die vom Proxy empfangen wurde.
REQUEST_VERB http.request.method request.verb HTTP-Verb der eingehenden Clientanfrage (z. B. GET oder POST).
RESPONSE_STATUS_CODE http.response.status_code response.status.code Der vom Zielserver zurückgegebene Antwortstatuscode.
ROUTE_NAME gcp.apigee.route.name route.name Der Name der Routingregel, mit der das Ziel für diese Anfrage ausgewählt wurde.
ROUTE_TARGET gcp.apigee.route.target route.target Der Name des Zielendpunkts, der von der Routenregel ausgewählt wurde.
TARGET_BASE_PATH gcp.apigee.target.basepath target.basepath Basispfadteil der Ziel-URL.
TARGET_HOST server.address target.host Hostname des Zielservers, der vom Proxy kontaktiert wird.
TARGET_IP server.address target.ip Die aufgelöste IP-Adresse des Zielservers.
TARGET_NAME gcp.apigee.target.name target.name Name des im API-Proxy definierten TargetEndpoint.
TARGET_PORT server.port target.port Der TCP-Port, der für die Verbindung mit dem Zielserver verwendet wird.
TARGET_RECEIVED_END_TIMESTAMP gcp.apigee.target.received_end_timestamp target.received.end.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy den Empfang der Antwort vom Zielserver abgeschlossen hat.
TARGET_RECEIVED_START_TIMESTAMP gcp.apigee.target.received_start_timestamp target.received.start.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy den Empfang der Antwort vom Zielserver begonnen hat.
TARGET_SENT_END_TIMESTAMP gcp.apigee.target.sent_end_timestamp target.sent.end.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy den Versand der Anfrage an den Zielserver abgeschlossen hat.
TARGET_SENT_START_TIMESTAMP gcp.apigee.target.sent_start_timestamp target.sent.start.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy begonnen hat, die Anfrage an den Zielserver zu senden.
TARGET_SSL_ENABLED gcp.apigee.target.ssl_enabled target.ssl.enabled Boolescher Wert, der angibt, ob für die Verbindung zum Zielserver TLS verwendet wurde.
TARGET_URL url.full target.url Vollständige URL des Zielservers, der vom Proxy kontaktiert wird.

Variablen im Span PROXY_POST_RESP_SENT

Die folgenden Variablen sind im Span PROXY_POST_RESP_SENT sichtbar. In der Spalte Semantische OTEL-Variable wird der Name der semantischen OpenTelemetry-Konvention angezeigt, der verwendet wird, wenn spanSemantics auf OTEL festgelegt ist. In der Spalte Attribut wird der Name des alten Attributs angezeigt.

Legacy-Variable OTEL-Semantikvariable Attribut Beschreibung
API_PROXY_REVISION gcp.apigee.proxy.revision apiproxy.revision Die Revisionsnummer des API-Proxy, der die Anfrage verarbeitet hat.
APIPROXY_NAME gcp.apigee.proxy.name apiproxy.name Name des API-Proxy, der die Anfrage verarbeitet hat.
CLIENT_RECEIVED_END_TIMESTAMP gcp.apigee.client.received_end_timestamp client.received.end.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy den Empfang der Anfrage vom Client abgeschlossen hat.
CLIENT_RECEIVED_START_TIMESTAMP gcp.apigee.client.received_start_timestamp client.received.start.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy die Anfrage vom Client empfangen hat.
CLIENT_SENT_END_TIMESTAMP gcp.apigee.client.sent_end_timestamp client.sent.end.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy das Senden der Antwort an den Client abgeschlossen hat.
CLIENT_SENT_START_TIMESTAMP gcp.apigee.client.sent_start_timestamp client.sent.start.timestamp Zeitstempel (Epochen-Millisekunden), zu dem der Proxy begonnen hat, die Antwort an den Client zu senden.
ENVIRONMENT_NAME gcp.apigee.environment environment.name Name der Apigee-Umgebung, in der der Proxy ausgeführt wurde.
FAULT_SOURCE gcp.apigee.fault_source message.header.X-Apigee-fault-source Quelle des Fehlers, wenn bei der Proxy-Ausführung ein Fehler auftritt. Wird nur bei Fehlerabläufen ausgefüllt.
IS_ERROR gcp.apigee.is_error is.error Boolescher Wert, der angibt, ob die Proxy-Ausführung in einem Fehlerablauf geendet hat.
MESSAGE_ID gcp.apigee.message.id message.id Eindeutige Kennung, die der Anfrage von Apigee zugewiesen wird. Sie ist nützlich, um Logs und Trace-Spans zu korrelieren.
MESSAGE_STATUS_CODE http.response.status_code message.status.code Statuscode der endgültigen Antwort, auch für Aufrufe ohne Ziele und für Fehlerabläufe.
PROXY_BASE_PATH http.route proxy.basepath Basispfad des API-Proxy, der der eingehenden Anfrage entspricht.
PROXY_CLIENT_IP client.address proxy.client.ip IP-Adresse des Clients, der die Anfrage an den Proxy gesendet hat.
PROXY_NAME gcp.apigee.proxy.name proxy.name Name des ProxyEndpoints im API-Proxy, der die Anfrage verarbeitet hat.
PROXY_PATH_SUFFIX url.path proxy.pathsuffix Der Teil des Anfrage-URL-Pfads, der auf den Proxy-Basispfad folgt.
PROXY_URL url.full proxy.url Vollständige URL des Proxy-Endpunkts, wie vom Client empfangen.

Unterstützte Systeme für verteiltes Tracing

Sie können Ihre Apigee-Laufzeit so konfigurieren, dass Trace-Daten an die folgenden Systeme für verteiltes Tracing gesendet werden:

Systeme für verteiltes Tracing Beschreibung
Cloud Trace mit OpenTelemetry

Ideal für Nutzer, die eine einfache Einrichtung mit OpenTelemetry wünschen und deren primäres oder einziges Tracing-Backend Cloud Trace ist.

So senden Sie Trace-Daten mit OpenTelemetry an Cloud Trace:

  1. Apigee-Laufzeit für Cloud Trace konfigurieren
  2. Verteiltes Tracing für Cloud Trace mit OpenTelemetry aktivieren
OpenTelemetry Collector

Sie können Ihren eigenen OpenTelemetry Collector verwalten, um die Erfassung und Verarbeitung von Tracedaten zu steuern. Diese Option ist ideal, wenn Sie Daten an mehrere Systeme (auch Nicht-Google-Systeme) senden oder die Verarbeitung, Gruppierung oder Optimierung von Daten anpassen müssen.

So senden Sie Tracedaten an einen OpenTelemetry Collector:

  1. Stellen Sie einen OpenTelemetry Collector bereit und verwalten Sie ihn, wie unter OpenTelemetry Collector beschrieben.
  2. Verteiltes Tracing für einen OpenTelemetry Collector aktivieren

Unter Überlegungen zur Verwendung eines OpenTelemetry Collectors finden Sie Informationen zu den Anforderungen an die Netzwerkerreichbarkeit, TLS und den Transport, die Sie erfüllen müssen, bevor Sie diese Option aktivieren.
Cloud Trace mit OpenCensus

So senden Sie Tracedaten mit OpenCensus an Cloud Trace:

  1. Apigee-Laufzeit für Cloud Trace (OpenCensus) konfigurieren
  2. Verteiltes Tracing für Cloud Trace mit OpenCensus aktivieren
Jaeger mit OpenCensus

Wenn Sie Trace-Daten mit OpenCensus an Jaeger senden möchten, aktivieren Sie das verteilte Tracing für Jaeger.

Umgebungsvariablen

In den Verfahren auf dieser Seite werden die folgenden Umgebungsvariablen verwendet. Wir empfehlen, sie vorab in Ihrer Umgebung festzulegen.

TOKEN="Authorization: Bearer $(gcloud auth application-default 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.

Apigee-Laufzeit für OpenTelemetry oder OpenCensus konfigurieren

Die Apigee-Laufzeit unterstützt zwei Tracing-Standards: OpenTelemetry (für neue Bereitstellungen empfohlen) und OpenCensus. Wählen Sie den Tracing-Standard aus, der für Ihre Umgebung geeignet ist, und folgen Sie dann der entsprechenden Einrichtungsanleitung im Abschnitt unten.

Für OpenTelemetry erkennt die Apigee-Laufzeit das Headerformat für den W3C-Trace-Kontext, einschließlich der Header traceparent, tracestate und baggage.

Voraussetzungen für Cloud Trace (OpenTelemetry) konfigurieren

Die Apigee-Laufzeit (ApigeeX) unterstützt verteiltes Tracing mit Cloud Trace und OpenTelemetry. Wenn Sie einen vom Kunden verwalteten OpenTelemetry Collector verwenden, können Sie diesen Abschnitt überspringen und mit Verteiltes Tracing für einen OpenTelemetry Collector aktivieren fortfahren.

ApigeeX-Laufzeit für Cloud Trace konfigurieren

Wenn Sie Ihre Apigee-Laufzeit für Cloud Trace konfigurieren möchten, müssen in Ihrem Google Cloud Projekt die folgenden APIs aktiviert sein:

Wenn Sie diese APIs aktivieren, kann Ihr Google Cloud -Projekt Trace-Daten über OpenTelemetry von authentifizierten Quellen empfangen.

So aktivieren Sie die APIs:

  1. Rufen Sie in der Google Cloud Console APIs und Dienste auf:

    Zu "APIs und Dienste"

  2. Klicken Sie auf APIs und Dienste aktivieren, um die API-Bibliothek zu öffnen.
  3. Aktivieren Sie in der API-Bibliothek die Cloud Trace API, die Telemetry API und die Service Usage API. Sie können jede API finden, indem Sie in der Suchleiste der API-Bibliothek nach dem Namen suchen (z. B. Telemetry API).

Zusätzlich zum Aktivieren der APIs müssen Sie dem Dienstkonto des Dienst-Agents die folgenden Rollen zuweisen:

  • roles/telemetry.tracesWriter
  • roles/serviceusage.serviceUsageConsumer

Das spezifische Dienstkonto hängt von Ihrer Apigee-Umgebung ab:

  • ApigeeX (nicht hybrid): Weisen Sie die Rollen dem Apigee-Dienst-Agent zu, einem von Google verwalteten P4SA (Per-Project-Per-Product Service Account), der von Apigee automatisch für das Projekt bereitgestellt wird. Das Dienst-Agent-Konto hat das Format service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com.

Weitere Informationen finden Sie unter IAM-Rolle über die Google Cloud -Console zuweisen.

Verteiltes Tracing (OpenTelemetry) aktivieren

Erstellen Sie vor dem Aktivieren des verteilten Tracings die erforderlichen Umgebungsvariablen.

Verteiltes Tracing für Cloud Trace aktivieren

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

  1. 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":"OPEN_TELEMETRY_CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

    Der Beispielanfragetext besteht aus folgenden Elementen:

    • Zur Unterstützung von Cloud Trace mit OpenTelemetry wird der Parameter exporter auf OPEN_TELEMETRY_CLOUD_TRACE und der Parameter traceProtocol auf OTLP festgelegt.
    • samplingRate ist auf 0,05 festgelegt. Dies bedeutet, dass ungefähr 5% der API-Aufrufe an das verteilte Tracing gesendet werden. Für OpenTelemetry können Sie eine Samplingrate von bis zu 1.0 (100%) angeben. Weitere Informationen finden Sie unter Überlegungen zur Leistung.
    • Der Parameter endpoint ist auf die Google Cloud Projekt-ID des Projekts festgelegt, das die Trace-Daten empfangen soll (ein einfacher Projekt-ID-String, keine URL).
    • Der Parameter spanSemantics ist optional und steuert die Attribut- und Spannenbenennung, die für ausgegebene Spannen verwendet wird. Unterstützte Werte:
      • LEGACY (Standard): Verwenden Sie die historischen Apigee-Attribut- und Spannenamen, die in der Spalte Attribut der Variablentabellen aufgeführt sind.
      • OTEL: Verwenden Sie die Namen der semantischen OpenTelemetry-Konventionen, die in der Spalte OTEL semantic variable (Semantische OTEL-Variable) angezeigt werden. Erfordert, dass traceProtocol OTLP ist.

    Eine erfolgreiche Antwort sieht in etwa so aus:

    {
  "exporter": "OPEN_TELEMETRY_CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}

Verteiltes Tracing für einen OpenTelemetry Collector aktivieren

Führen Sie diesen Apigee API-Aufruf aus, um das verteilte Tracing für einen vom Kunden verwalteten OpenTelemetry Collector zu aktivieren:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

Der Beispielanfragetext besteht aus folgenden Elementen:

  • Zur Unterstützung eines vom Kunden verwalteten OpenTelemetry Collectors wird der Parameter exporter auf OPEN_TELEMETRY_COLLECTOR und der Parameter traceProtocol auf OTLP festgelegt.
  • Der Parameter endpoint wird auf die vollständige HTTP-/HTTPS-URL des OTLP-Aufnahmepunkts Ihres OpenTelemetry Collectors festgelegt, z. B. http://my-otel-collector.example.com:4318/v1/traces. Im Gegensatz zum Cloud Trace-Exporter, der eine einfache Google Cloud Projekt-ID verwendet, erfordert der OPEN_TELEMETRY_COLLECTOR-Exporter eine vollständige URL, die Schema, Host, Port und Pfad enthält. Im Gegensatz zum Cloud Trace-Endpunkt ist der OpenTelemetry Collector endpoint veränderlich: Sie können ihn später mit einem anderen PATCH neu konfigurieren, um traceConfig.
  • samplingRate ist auf 0,05 festgelegt. Dies bedeutet, dass ungefähr 5% der API-Aufrufe an das verteilte Tracing gesendet werden. Weitere Informationen finden Sie unter Überlegungen zur Leistung.
  • Der Parameter otelCollectorSecurityScheme ist optional und hat standardmäßig den Wert NONE. Legen Sie den Wert auf MTLS fest, um die gegenseitige TLS zwischen Apigee und dem Collector zu aktivieren. Informationen zu den erforderlichen mtlsConfig-Feldern und dem vollständigen API-Anfragetext finden Sie unter mTLS für einen OpenTelemetry Collector konfigurieren.

Eine erfolgreiche Antwort sieht in etwa so aus:

{
  "exporter": "OPEN_TELEMETRY_COLLECTOR",
  "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}

Überlegungen bei der Verwendung eines OpenTelemetry Collectors

Bevor Sie Distributed Tracing für einen vom Kunden verwalteten OpenTelemetry Collector aktivieren, sollten Sie die folgenden Anforderungen prüfen.

Netzwerkerreichbarkeit

  • Sorgen Sie dafür, dass Apigee den OpenTelemetry Collector erreichen kann.
  • Wenn Sie einen Collector erreichen möchten, der nicht im öffentlichen Internet verfügbar ist, verwenden Sie Private Service Connect (PSC).
  • Wenn in Ihrer Einrichtung ein Forward-Proxy vorhanden ist, konfigurieren Sie ihn im OpenTelemetry Collector. Verbindungen vom Nachrichtenprozessor zum OpenTelemetry Collector sind immer direkt.

Transportprotokoll

Für OpenTelemetry Collectors wird nur der OTLP/HTTP-Transport unterstützt (Port 4318 und Pfad /v1/traces gemäß OTLP-Konvention). OTLP/gRPC (Port 4317) wird nicht unterstützt.

TLS und mTLS

Apigee unterstützt zwei Sicherheitsschemas für die Verbindung zu einem OpenTelemetry Collector, die über otelCollectorSecurityScheme in traceConfig festgelegt werden:

  • Keine Sicherheit (HTTP) (NONE, Standard): Apigee stellt über HTTP ohne gegenseitiges TLS eine Verbindung zum Collector her.
  • mTLS (MTLS): Gegenseitiges TLS, damit der Collector Apigee auch als Client authentifizieren kann. Um mTLS zu aktivieren, setzen Sie otelCollectorSecurityScheme auf MTLS für traceConfig und geben Sie ein mtlsConfig an, das auf von Apigee verwaltete Schlüsselspeicher und Truststores verweist. Eine End-to-End-Einrichtung finden Sie unter mTLS für einen OpenTelemetry Collector konfigurieren.

mTLS für einen OpenTelemetry Collector konfigurieren

Mit gegenseitigem TLS (mTLS) kann Ihr OpenTelemetry Collector die Apigee-Laufzeit als Client authentifizieren. Außerdem validiert Apigee das Serverzertifikat des Collectors.

Prüfen Sie vor der Konfiguration von mTLS die folgenden Voraussetzungen:

  • Ihr Collector ist so konfiguriert, dass eine Clientzertifikatsauthentifizierung erforderlich ist (z. B. die Einstellung tls.client_ca_file des OpenTelemetry Collectors), und wird mit einer Zertifizierungsstellendatei bereitgestellt, die die Zertifikatskette enthält, die Sie in Schritt 1 der Einrichtung hochladen.
  • Für endpoint wird das Schema https:// verwendet.
  • Der exporter ist OPEN_TELEMETRY_COLLECTOR und der traceProtocol ist OTLP. mTLS wird nicht auf den OPEN_TELEMETRY_CLOUD_TRACE-Exporter angewendet, der sich stattdessen mit Google Cloud OAuth authentifiziert.

Schritt 1: Clientschlüssel und ‑zertifikat hochladen

Erstellen Sie einen Schlüsselspeicher für das Apigee-Clientzertifikat, mit dem sich der Collector authentifiziert, und laden Sie dann den Schlüssel und das Zertifikat als Alias hoch:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases?alias=mp-client&format=keycertfile" \
    -X POST \
    -F "keyFile=@client.key" \
    -F "certFile=@client.crt"

Die client.crt-Datei muss von einer Zertifizierungsstelle signiert sein, der die tls.client_ca_file des Collectors vertraut. Bei einer selbstsignierten Einrichtung kann client.crt dieselbe Datei sein, die der Collector als client_ca_file verwendet.

Schritt 2: Serverzertifikat des Collectors hochladen

Erstellen Sie einen Truststore, mit dem die Apigee-Laufzeit das Serverzertifikat des Collectors validiert, und laden Sie dann das CA-Zertifikat des Collectors als CERT-Alias hoch:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls-truststore" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls-truststore/aliases?alias=server-ca&format=keycertfile" \
    -X POST \
    -F "certFile=@server-ca.pem"

Schritt 3: mTLS für traceConfig aktivieren

Führen Sie einen PATCH-Vorgang für traceConfig aus, um das Sicherheitsschema auf MTLS festzulegen und auf den gerade erstellten Schlüsselspeicher und Truststore zu verweisen:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter": "OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL",
          "otelCollectorSecurityScheme": "MTLS",
          "mtlsConfig": {
            "keyStore":   "otel-mtls",
            "keyAlias":   "mp-client",
            "trustStore": "otel-mtls-truststore"
          }
        }'

Das mtlsConfig-Objekt hat drei erforderliche Felder:

  • keyStore: Der Name des Keystores, der den Apigee-Clientschlüssel und das Zertifikat aus Schritt 1 enthält (z. B. otel-mtls). Wenn Sie stattdessen eine Apigee-Referenz verwenden möchten, geben Sie ref://REFERENCE_NAME an.
  • keyAlias: Der Name des KEY_CERT-Alias in keyStore (z. B. mp-client).
  • trustStore: Der Name des Keystores, der das Server-CA-Zertifikat des Collectors aus Schritt 2 enthält (z. B. otel-mtls-truststore). Wenn Sie stattdessen eine Apigee-Referenz verwenden möchten, geben Sie ref://REFERENCE_NAME an.

Apigee erzwingt die folgende Validierung für traceConfig, wenn otelCollectorSecurityScheme gleich MTLS ist:

  • exporter muss OPEN_TELEMETRY_COLLECTOR lauten.
  • traceProtocol muss OTLP lauten.
  • endpoint muss das Schema https:// verwenden.
  • Alle drei mtlsConfig-Felder müssen ausgefüllt sein. Wenn ein Feld fehlt, wird der HTTP-Fehler 400 zurückgegeben.
  • Die referenzierten Schlüsselspeicher, Aliase und alle Referenzen müssen bereits vorhanden sein. Fehlende Ressourcen geben HTTP 400 zurück.

Clientschlüssel oder ‑zertifikat rotieren

Wenn Sie den Clientschlüssel oder das Clientzertifikat ohne traceConfig-Änderung rotieren möchten, laden Sie neues Schlüsselmaterial mit einem PUT in den vorhandenen mp-client-Alias hoch:

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases/mp-client" \
    -X PUT \
    -F "keyFile=@client-v2.key" \
    -F "certFile=@client-v2.crt"

Die Apigee-Laufzeit erkennt die Änderung der Alias-Revision beim nächsten Konfigurationsabgleich und erstellt den mTLS-OTLP-Exporter mit den neuen Anmeldedaten neu. Es ist kein Neustart des Pods erforderlich und es werden keine Inflight-Anfragen verworfen.

Kriterien für die Stichprobenerhebung

Die Apigee-Laufzeit entscheidet, ob für jede Anfrage ein Trace aufgezeichnet wird. Dazu werden die eingehenden Anfrageheader mit der Trace-Konfiguration der Umgebung kombiniert.

W3C-Trace-Kontext-Header

In der OpenTelemetry-Konfiguration wird vom Laufzeitprozess der W3C-Trace-Kontext-Header traceparent berücksichtigt. Das letzte Byte von traceparent (das Byte trace-flags) enthält das Flag sampled: Der Wert 01 gibt an, dass der Aufrufer bereits entschieden hat, den Trace aufzuzeichnen, und 00, dass dies nicht der Fall ist.

Die Empfehlungen für das Flag „sampled“ in der W3C Trace Context-Spezifikation raten, dass eine Komponente das eingehende Flag „sampled“ bei der Entscheidung über die Aufzeichnung berücksichtigt und eine endgültige Entscheidung über die Aufzeichnung im Flag widerspiegelt. Apigee folgt diesen Empfehlungen: Das eingehende „sampled“-Flag wird berücksichtigt, wenn entschieden wird, ob ein Trace aufgezeichnet werden soll (siehe Header-Vorrang vor lokaler Konfiguration). Außerdem wird das „sampled“-Flag im traceparent-Header, der an Downstream-Dienste weitergegeben wird, so festgelegt, dass es widerspiegelt, ob die Anfrage aufgezeichnet wird. Als Sicherheitsmaßnahme gegen unerwünschtes Tracing, das durch das eingehende Flag ausgelöst wird, setzen Sie sampler auf OFF (siehe Konfiguration für verteiltes Tracing deaktivieren). Dadurch wird das Tracing auch für Anfragen deaktiviert, für die das Flag „sampled“ für traceparent festgelegt ist.

Header haben Vorrang vor der lokalen Konfiguration

Wenn eine eingehende Anfrage einen traceparent-Header enthält, verwendet die Apigee-Laufzeit das darin enthaltene Flag „sampled“ anstelle des lokalen samplingConfig. Eine Anfrage mit dem Flag „sampled“ auf 01 wird immer verfolgt, eine Anfrage mit dem Flag auf 00 nicht. Die samplingConfig-Einstellung auf Umgebungsebene gilt nur für Anfragen, die ohne traceparent-Header eingehen.

Trace deaktivieren

Wenn Sie das Tracing für jeden Proxy in einer Umgebung deaktivieren möchten (ohne Proxy-Überschreibungen), legen Sie sampler in der Umgebung traceConfig auf OFF fest. Weitere Informationen finden Sie unter Konfiguration des verteilten Tracings deaktivieren.

Überschreibungen pro Proxy

Wenn Sie das Tracing nur für eine Teilmenge von Proxys in einer Umgebung aktivieren möchten, lassen Sie die Umgebungsvariable samplingConfig mit sampler auf OFF festgelegt und erstellen Sie für jeden Proxy, den Sie verfolgen möchten, eine Proxy-spezifische Überschreibung (mit sampler auf PROBABILITY festgelegt und einem Wert ungleich null für samplingRate). Weitere Informationen finden Sie unter Trace-Einstellungen für API-Proxys überschreiben.

Auswirkungen der Stichprobenrate auf die Leistung

Die von Ihnen konfigurierte samplingRate wirkt sich direkt auf die Laufzeitleistung aus. Für jede Stichprobenanfrage fällt zusätzliche CPU-Arbeit auf dem Nachrichtenprozessor an (Spangenerierung und -export), was zu einer zusätzlichen Latenz im Anfragepfad führt. Mit zunehmender Samplingrate steigt auch das Volumen des getrackten Traffics pro MP, was den Durchsatz verringern und die Tail-Latenz (P95, P99) erhöhen kann. Die Auswirkungen nehmen mit dem Trafficvolumen zu: Bei niedrigen Anforderungsraten ist der Overhead in der Regel vernachlässigbar, bei hohen Anforderungsraten kann eine hohe Sampling-Rate den nachhaltigen Durchsatz erheblich verringern und zusätzliche MP-Kapazität erfordern. Bei internen Benchmarks, die bei samplingRate=1.0 (100% Sampling) unter anhaltend hohem Verkehrsaufkommen ausgeführt wurden, wurde der Durchsatz im Vergleich zur Ausführung mit deaktiviertem Tracing um bis zu etwa 15 % reduziert.

Als allgemeine Richtlinie gilt, dass Sie samplingRate in der Produktion niedrig halten sollten (z. B. 0.1 oder niedriger). Erhöhen Sie den Wert nur für bestimmte Proxys über Proxy-Überschreibungen, wenn Sie eine detailliertere Ansicht benötigen. Eine detaillierte Aufschlüsselung der erwarteten Auswirkungen und Kapazitätsempfehlungen finden Sie unter Überlegungen zur Leistung.

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 von der Komplexität des API-Proxy (z. B. der Anzahl der Richtlinien), der probabilistischen Abtastrate (als samplingRate festgelegt) und vor allem vom verfolgten Traffic-Volumen im Verhältnis zur Exportkapazität des Spans pro Message Processor (MP) ab.

Der Apigee-MP hat eine endliche Exportrate für Spans. Mit der Standardkonfiguration kann ein einzelner MP nachhaltig etwa 820 Spans pro Sekunde exportieren. Bei der Ausführung eines typischen API-Proxy werden etwa 10 Spans ausgegeben (Proxy-Preflow, Zielablauf, Postflows, angehängte Richtlinien). Ein einzelner MP kann also nachhaltig etwa 82 Anfragen pro Sekunde bei 100% Sampling verfolgen. Durch die Skalierung der Anzahl der MP-Replikate wird die aggregierte Obergrenze linear erhöht.

In der folgenden Tabelle sind die erwarteten Auswirkungen bei samplingRate=1.0 (100% Wahrscheinlichkeit) für zwei Traffic-Regimes zusammengefasst:

Trafficregime (pro MP) Voraussichtliche Auswirkungen am samplingRate=1.0 Empfohlene Maßnahmen
Geringes Verkehrsaufkommen (weniger als etwa 82 nachverfolgte Anfragen pro Sekunde und MP) Der Durchsatz sinkt um etwa 1–2 %, die durchschnittliche Latenz steigt um etwa 1 % und die P99-Latenz steigt um etwa 15–20%. In der Praxis vernachlässigbar. Kann bei 100 % aktiviert werden.
Hohes Verkehrsaufkommen (deutlich über ca. 82 nachverfolgten Anfragen pro Sekunde pro MP) Der Durchsatz sinkt um etwa 14 %, die durchschnittliche Latenz steigt um etwa 24 %, die Latenz des 75. Perzentils steigt um etwa 52 % und die Fehlerrate steigt um etwa 1 Prozentpunkt. Entweder senken Sie samplingRate (z. B. auf 0.1 oder 0.05) oder Sie erhöhen die Anzahl der MP-Replikate, damit jeder MP weniger verfolgte Anfragen pro Sekunde verarbeitet.

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 über Proxy-Überschreibungen erhöhen.

Apigee-Laufzeiten für Cloud Trace (OpenCensus) konfigurieren

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

Apigee-Laufzeit für Cloud Trace konfigurieren

Damit Sie Ihre Apigee-Laufzeit für Cloud Trace konfigurieren können, muss in Ihrem Google Cloud Projekt die Cloud Trace API aktiviert sein.

So aktivieren Sie die API:

  1. Rufen Sie in der Google Cloud Console APIs und Dienste auf:

    Zu "APIs und Dienste"

  2. Klicken Sie auf APIs und Dienste aktivieren.
  3. Aktivieren Sie die Cloud Trace API.

Apigee Hybrid-Laufzeit für Cloud Trace konfigurieren

Aktivieren Sie die Cloud Trace API, um die Apigee Hybrid-Laufzeit für Cloud Trace zu konfigurieren.

Zusätzlich zur Aktivierung der 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 der erforderlichen Rolle roles/cloudtrace.agent und den Schlüsseln hinzuzufügen:

  1. Erstellen Sie ein neues Dienstkonto. 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. 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
  3. Erstellen Sie einen Dienstkontoschlüssel und aktualisieren Sie overrides.yaml wie in den folgenden Schritten beschrieben.
  4. Erstellen Sie einen Dienstkontoschlüssel: 
    gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
  5. 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
  6. Wenden Sie die Änderungen mit Helm auf die Laufzeit an: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Verteiltes Tracing aktivieren (OpenCensus)

Erstellen Sie vor dem Aktivieren des verteilten Tracings die erforderlichen Umgebungsvariablen.

Verteiltes Tracing für Cloud Trace mit OpenCensus aktivieren

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

  1. 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:

    • Zur Unterstützung von Cloud Trace ist der Parameter exporter auf CLOUD_TRACE festgelegt. Der Parameter traceProtocol, der nicht angegeben ist, wird standardmäßig auf OpenCensus gesetzt.
    • Der Parameter endpoint wird auf das Google Cloud -Projekt festgelegt, an das der Trace gesendet werden soll.
    • Die samplingRate ist auf 0.1 festgelegt. Dies bedeutet, dass ungefähr 10 % der API-Aufrufe an das verteilte Tracing gesendet werden. Für OpenCensus ist die maximal konfigurierbare Abtastrate 0.5.

    Eine erfolgreiche Antwort sieht in etwa so aus:

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

Verteiltes Tracing für Jaeger mit OpenCensus 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 Fall gilt Folgendes:

  • Zur Unterstützung von Jaeger wird der Parameter exporter auf JAEGER gesetzt. Der Parameter traceProtocol, der nicht angegeben ist, wird standardmäßig auf OpenCensus gesetzt.
  • Der Parameter endpoint wird auf den Ort gesetzt, an dem Jaeger installiert und konfiguriert ist.
  • samplingRate ist auf 0,4 festgelegt. Dies bedeutet, dass ungefähr 40 % der API-Aufrufe an das verteilte Tracing gesendet werden.

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.

Weitere Informationen finden Sie unter Überlegungen zur Leistung.

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": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  },
  "revisionId": "7",
  "updateTime": "2026-06-08T14:25:13.512000Z"
}

Der revisionId wird mit jeder erfolgreichen Aktualisierung erhöht und der updateTime gibt den Serverzeitstempel der letzten Änderung an. Anhand dieser beiden Felder können Sie bestätigen, dass die Steuerungsebene eine Konfigurationsaktualisierung akzeptiert hat. Beide werden auch von der PATCH .../traceConfig-Antwort zurückgegeben.

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 -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.6}
        }'

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

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}
 In diesem Beispiel wird die Abtastrate auf 0.6 aktualisiert.

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 '{
          "samplingConfig": {"sampler": "OFF"}
        }'

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

{
  "samplingConfig": {
    "sampler": "OFF"
  },
  "traceProtocol": "OTLP"
}

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:

  1. 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
      }
    }
  ]
}
  2. 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:

  1. 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
      }
    }
  ]
}
  2. 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. Beispiel: 
    curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1 \
    -X DELETE \

Fehlerbehebung beim verteilten Tracing

So beheben Sie Fehler beim verteilten Tracing:

  • Prüfen Sie die Konfiguration für das verteilte Tracing mit der traceConfig API, um sicherzustellen, dass sie Ihren Anforderungen entspricht.
  • Prüfen Sie, ob das Dienstkonto die richtigen IAM-Berechtigungen (Rollen) im Zielprojekt hat.
  • Wenn Sie Cloud Trace mit OpenTelemetry verwenden, prüfen Sie, ob eingehende Spans vorhanden sind und ob API-Aktivierungs- oder Kontingentfehler auftreten.
  • Wenn Sie einen vom Kunden verwalteten OpenTelemetry Collector verwenden, gehen Sie so vor:
    • Prüfen Sie, ob Apigee den Collector-Endpunkt erreichen kann. Prüfen Sie Ihre Private Service Connect-Einrichtung (PSC), falls sie verwendet wird.
    • Prüfen Sie die OpenTelemetry Collector-Logs auf Daten- oder Verbindungsprobleme.
    • Prüfen Sie, ob das TLS-Zertifikat des Collectors gültig ist.
  • Prüfen Sie die Apigee-Laufzeitlogs auf Fehler beim Exportieren von Traces.