Oracle Cloud Infrastructure - Dokumentation

opc-request-id-Werte für Client, API-Gateway-Logs und Backend stimmen nicht wie erwartet überein

Erfahren Sie, wie Sie die Korrelation und das Propagierungsverhalten von opc-request-id beim Aufruf von APIs beheben, nachdem API-Gateways und API-Deployments erfolgreich mit dem API-Gateway-Service erstellt wurden.

Verwenden Sie opc-request-id-Werte, um eine Clientanforderung mit API-Gateway-Logs und Backend-Logs zu korrelieren. Der Wert, den der Client sendet, kann sich von dem Wert unterscheiden, den der Client in der Antwort erhält, und vom Wert, den der Backend-Service vom API-Gateway empfängt.

API Gateway parst den eingehenden Wert, behält ausgewählte Teile des Wertes bei und generiert eine neue Span-ID für die Anforderung. Verwenden Sie das Parsingverhalten in diesem Thema, um den richtigen Wert für die Logkorrelation auszuwählen.

Problemsymptome

Möglicherweise sehen Sie eines oder mehrere der folgenden Symptome:

  • Der an den Client zurückgegebene opc-request-id-Antwortheader stimmt nicht mit dem Wert überein, den der Client gesendet hat.

  • Der Backend-Service protokolliert einen opc-request-id-Wert, der sich von dem an den Client zurückgegebenen Wert unterscheidet.

  • Application Performance Monitoring-(APM-) oder Backend-Logs zeigen unerwartete Konflikte, fehlende Werte oder Truncation an, wenn ein vom Client bereitgestelltes opc-request-id einen Schrägstrich (/) enthält.

  • Sie können dieselbe Anforderung nicht über die Clientantwort, API-Gateway-Zugriffslogs, API-Gateway-Ausführungslogs und Backend-Logs hinweg mit einem einzelnen Headerwert finden.

Mögliche Gründe

Die Werte können aus folgenden Gründen abweichen:

  • API-Gateway behandelt opc-request-id nicht als undurchsichtigen Passthrough-Wert.

  • API Gateway teilt den eingehenden Wert auf den Schrägstrich (/) auf und verwendet nur die Kunden-ID und die Trace-ID-Teile.

  • API Gateway generiert eine neue Span-ID für jede Anforderung.

  • Der an den Client zurückgegebene Antwortheader enthält die generierte Span-ID, der an den Backend-Service gesendete Header enthält jedoch nicht die Span-ID.

  • Jedes vom Client bereitgestellte dritte Segment, z.B. eine Span-ID, wird bei der Propagierung ignoriert.

opc-request-id-Parsing verstehen

API Gateway teilt einen eingehenden opc-request-id-Wert mit Schrägstrich (/) auf, wobei maximal drei Teile enthalten sind. Es verwendet die ersten beiden geparsten Teile und ignoriert jeden dritten Teil.

API Gateway interpretiert die geparsten Teile wie folgt:

  • Erster Teil: Kunden-ID.

  • Zweiter Teil: Trace-ID.

  • Dritter Teil: Wert ignoriert.

API Gateway generiert dann eine Span-ID für die Anforderung und erstellt die folgenden Werte:

  • Antwortheader an den Client zurückgegeben: customerId/traceId/spanId.

  • An den Backend-Service gesendeter Anforderungsheader: customerId/traceId.

Verwenden Sie den vollständigen Antwortheaderwert, wenn Sie API-Gateway-Logs durchsuchen. Verwenden Sie den zweiteiligen nachgelagerten Wert, wenn Sie Backend-Logs durchsuchen.

Gemeinsame Eingabemuster prüfen

Anhand dieser Beispiele erfahren Sie, wie das API-Gateway allgemeine opc-request-id-Werte ändert.

Kein opc-request-id-Header

Wenn der Client keinen opc-request-id-Header sendet, generiert das API-Gateway eine Trace-ID und eine Span-ID. Die Kunden-ID ist leer.

Die resultierenden Werte haben das folgende Format:

  • Clientantwortheader: /<generated-trace-id>/<generated-span-id>

  • Backend-Anforderungsheader: /<generated-trace-id>

Ein Segment: abcdef

Wenn der Client den folgenden Header sendet, behandelt API Gateway den Wert als Kunden-ID:

opc-request-id: abcdef

Die interpretierten Werte lauten wie folgt:

  • Kunden-ID: abcdef.

  • Trace-ID: Wird vom API-Gateway generiert.

  • Span-ID: Wird vom API-Gateway generiert.

Die resultierenden Werte haben das folgende Format:

  • Clientantwortheader: abcdef/<generated-trace-id>/<generated-span-id>

  • Backend-Anforderungsheader: abcdef/<generated-trace-id>

Führender Schrägstrich: /abcdef

Wenn der Client den folgenden Header sendet, behandelt API Gateway den Wert nach dem Schrägstrich als Trace-ID:

opc-request-id: /abcdef

Die interpretierten Werte lauten wie folgt:

  • Kunden-ID: Leer.

  • Trace-ID: abcdef.

  • Span-ID: Wird vom API-Gateway generiert.

Die resultierenden Werte haben das folgende Format:

  • Clientantwortheader: /abcdef/<generated-span-id>

  • Backend-Anforderungsheader: /abcdef

Ein vorangestellter Schrägstrich ändert die Bedeutung des Werts, da der Kunden-ID-Teil leer ist.

Zwei Segmente: customer/trace

Wenn der Client den folgenden Header sendet, verwendet API Gateway beide bereitgestellten Teile:

opc-request-id: customer/trace

Die interpretierten Werte lauten wie folgt:

  • Kunden-ID: customer

  • Trace-ID: trace

  • Span-ID: Wird von API Gateway generiert

Die resultierenden Werte haben das folgende Format:

  • Clientantwortheader: customer/trace/<generated-span-id>

  • Backend-Anforderungsheader: customer/trace

Drei Segmente: customer/trace/span

Wenn der Client den folgenden Header sendet, ignoriert API Gateway das dritte Segment und generiert eine neue Span-ID:

opc-request-id: customer/trace/span

Die interpretierten Werte lauten wie folgt:

  • Kunden-ID: customer.

  • Trace-ID: trace.

  • Drittes Segment: Wird ignoriert.

  • Span-ID: Wird vom API-Gateway generiert.

Die resultierenden Werte haben das folgende Format:

  • Clientantwortheader: customer/trace/<generated-span-id>

  • Backend-Anforderungsheader: customer/trace.

Der vom Client angegebene Span-Wert wird nicht beibehalten.

Mehr als drei Segmente: customer/trace/span/extra

Wenn der Client den folgenden Header sendet, verwendet API Gateway immer noch nur die ersten beiden Segmente:

opc-request-id: customer/trace/span/extra

Die interpretierten Werte lauten wie folgt:

  • Kunden-ID: customer

  • Trace-ID: trace

Der gesamte Inhalt nach dem zweiten Schrägstrich wird zur Propagierung ignoriert.

Die resultierenden Werte haben das folgende Format:

  • Clientantwortheader: customer/trace/<generated-span-id>

  • Backend-Anforderungsheader: customer/trace

Prozess-ID-Werte vergleichen

Senden Sie Testanforderungen, und vergleichen Sie den Wert opc-request-id an den folgenden Stellen:

  • Der Headerwert, den der Client sendet.

  • Der Antwortheaderwert, den das API-Gateway an den Client zurückgibt.

  • Der Anforderungsheaderwert, den der Backend-Service vom API-Gateway empfängt.

Beispiel: Senden Sie eine Anforderung mit einem bekannten opc-request-id-Wert:

curl -i https://<gateway-hostname>/<deployment-path-prefix>/<api-route-path> \
-H "opc-request-id: <your-request-id>"

Testen Sie mindestens die folgenden Werte:

  • Kein opc-request-id-Header.

  • opc-request-id: abcdef.

  • opc-request-id: /abcdef.

  • opc-request-id: customer/trace.

  • opc-request-id: customer/trace/span.

Logeinträge prüfen

Verwenden Sie den vollständigen opc-request-id-Wert, der im Clientantwortheader zurückgegeben wird, wenn Sie API-Gateway-Zugriffslogs und Ausführungslogs durchsuchen.

Prüfen Sie die folgenden Logeinträge:

  • Der API Gateway-Zugriffslogeintrag für die Anforderung.

  • Der API-Gateway-Ausführungslogeintrag für die Anforderung.

  • Der Backend-Logeintrag für die weitergeleitete Anforderung.

Gehen Sie nicht davon aus, dass der Backend-Service denselben vollständigen Wert protokolliert, den API Gateway an den Client zurückgibt. Der Backend-Service empfängt das Downstream-Formular customerId/traceId, nicht das vom Client sichtbare Formular customerId/traceId/spanId.

Korrelationsprobleme beheben

Verwenden Sie die folgenden Vorgehensweisen, um Korrelationsprobleme zu vermeiden:

  • Starten Sie keinen vom Client bereitgestellten opc-request-id-Wert mit einem Schrägstrich (/), es sei denn, Sie möchten eine leere Kunden-ID und eine explizite Trace-ID.

  • Verlassen Sie sich nicht darauf, dass ein vom Kunden bereitgestelltes drittes Segment beibehalten wird.

  • Wenn Ihr Backend-Service oder APM-Tool eine einzelne undurchsichtige Korrelationszeichenfolge erwartet, verwenden Sie einen separaten Anwendungsheader für diesen Korrelationswert.

  • Verwenden Sie den vollständigen Client-sichtbaren Antwortheaderwert für die API Gateway-Logkorrelation.

  • Verwenden Sie den zweiteiligen Downstream-Wert, wenn Sie Backend-Logs prüfen.

Korrelation der Anfragekennung überprüfen

Nachdem Sie das Anforderungsformat oder die Korrelationsstrategie aktualisiert haben, prüfen Sie das Ergebnis:

  • Senden Sie dieselbe Anforderung erneut.

  • Stellen Sie sicher, dass der opc-request-id-Antwortheader die erwartete Struktur aufweist.

  • Stellen Sie sicher, dass Sie dieselbe Anforderung in den Zugriffslogs und Ausführungslogs finden.

  • Vergewissern Sie sich, dass der Backend-Service den erwarteten zweiteiligen opc-request-id-Wert empfängt.

  • Stellen Sie sicher, dass für das APM-Tool oder den Backend-Logparser nicht der Antwortheaderwert und der Downstream-Anforderungswert identisch sein müssen.

Weitere Informationen

Weitere Informationen finden Sie unter: