Documentazione dell'infrastruttura Oracle Cloud

I valori opc-request-id visualizzati dal client, dai log del gateway API e dal backend non corrispondono a quelli previsti

Scopri come risolvere i problemi relativi alla correlazione opc-request-id e al funzionamento della propagazione durante la chiamata delle API, dopo aver creato correttamente gateway API e distribuzioni API con il servizio Gateway API.

Utilizzare i valori opc-request-id per correlare una richiesta client con i log del gateway API e i log backend. Il valore inviato dal client potrebbe essere diverso dal valore ricevuto dal client nella risposta e dal valore ricevuto dal gateway API.

Il gateway API analizza il valore in entrata, mantiene le parti selezionate del valore e genera un nuovo ID intervallo per la richiesta. Utilizzare il funzionamento dell'analisi in questo argomento per scegliere il valore corretto per la correlazione del log.

Sintomi problema

Potresti vedere uno o più dei seguenti sintomi:

  • L'intestazione della risposta opc-request-id restituita al client non corrisponde al valore inviato dal client.

  • Il servizio backend registra un valore opc-request-id diverso dal valore restituito al client.

  • I log APM (Application Performance Monitoring) o backend mostrano collisioni impreviste, valori mancanti o troncamenti quando un file opc-request-id fornito dal client contiene una barra (/).

  • Non è possibile trovare la stessa richiesta tra la risposta client, i log di accesso al gateway API, i log di esecuzione del gateway API e i log backend utilizzando un singolo valore di intestazione.

Cause possibili

I valori possono essere diversi per i seguenti motivi:

  • API Gateway non considera opc-request-id come un valore pass-through opaco.

  • Il gateway API divide il valore in entrata nel carattere barra (/) e utilizza solo l'ID cliente e le parti ID traccia.

  • Il gateway API genera un nuovo ID intervallo per ogni richiesta.

  • L'intestazione della risposta restituita al client include l'ID intervallo generato, ma l'intestazione inviata al servizio backend non include l'ID intervallo.

  • Qualsiasi terzo segmento fornito dal client, ad esempio un ID intervallo, viene ignorato per la propagazione.

Informazioni sull'analisi opc-request-id

Il gateway API divide un valore opc-request-id in entrata in caratteri barra (/), con un massimo di tre parti. Utilizza le prime due parti analizzate e ignora qualsiasi terza parte.

API Gateway interpreta le parti analizzate come segue:

  • Prima parte: ID cliente.

  • Seconda parte: ID traccia.

  • Terza parte: valore ignorato.

Il gateway API genera quindi un ID intervallo per la richiesta e genera i valori seguenti:

  • Intestazione di risposta restituita al client: customerId/traceId/spanId.

  • Intestazione della richiesta inviata al servizio backend: customerId/traceId.

Utilizzare il valore dell'intestazione risposta completa quando si esegue una ricerca nei log del gateway API. Utilizzare il valore a valle in due parti quando si cercano i log backend.

Rivedi pattern di input comuni

Utilizzare questi esempi per capire in che modo il gateway API modifica i valori opc-request-id comuni.

Nessuna intestazione opc-request-id

Se il client non invia un'intestazione opc-request-id, API Gateway genera un ID trace e un ID intervallo. L'ID cliente è vuoto.

I valori risultanti hanno il seguente formato:

  • Intestazione risposta client: /<generated-trace-id>/<generated-span-id>

  • Intestazione della richiesta backend: /<generated-trace-id>

Un segmento: abcdef

Se il client invia l'intestazione seguente, il gateway API considera il valore come ID cliente:

opc-request-id: abcdef

I valori interpretati sono i seguenti:

  • ID cliente: abcdef.

  • ID traccia: generato dal gateway API.

  • ID intervallo: generato dal gateway API.

I valori risultanti hanno il seguente formato:

  • Intestazione risposta client: abcdef/<generated-trace-id>/<generated-span-id>

  • Intestazione della richiesta backend: abcdef/<generated-trace-id>

Slash iniziale: /abcdef

Se il client invia l'intestazione seguente, il gateway API considera il valore dopo la barra come ID traccia:

opc-request-id: /abcdef

I valori interpretati sono i seguenti:

  • ID cliente: vuoto.

  • ID traccia: abcdef.

  • ID intervallo: generato dal gateway API.

I valori risultanti hanno il seguente formato:

  • Intestazione risposta client: /abcdef/<generated-span-id>

  • Intestazione della richiesta backend: /abcdef

Una barra iniziale modifica il significato del valore perché la parte ID cliente è vuota.

Due Segmenti: customer/trace

Se il client invia l'intestazione seguente, API Gateway utilizza entrambe le parti fornite:

opc-request-id: customer/trace

I valori interpretati sono i seguenti:

  • ID cliente: customer

  • ID traccia: trace

  • ID intervallo: generato dal gateway API

I valori risultanti hanno il seguente formato:

  • Intestazione risposta client: customer/trace/<generated-span-id>

  • Intestazione della richiesta backend: customer/trace

Tre segmenti: customer/trace/span

Se il client invia l'intestazione seguente, API Gateway ignora il terzo segmento e genera un nuovo ID intervallo:

opc-request-id: customer/trace/span

I valori interpretati sono i seguenti:

  • ID cliente: customer.

  • ID traccia: trace.

  • Terzo segmento: ignorato.

  • ID intervallo: generato dal gateway API.

I valori risultanti hanno il seguente formato:

  • Intestazione risposta client: customer/trace/<generated-span-id>

  • Intestazione della richiesta backend: customer/trace.

Il valore di intervallo fornito dal client non viene conservato.

Più di tre segmenti: customer/trace/span/extra

Se il client invia l'intestazione seguente, API Gateway utilizza ancora solo i primi due segmenti:

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

I valori interpretati sono i seguenti:

  • ID cliente: customer

  • ID traccia: trace

Tutti i contenuti dopo la seconda barra vengono ignorati per la propagazione.

I valori risultanti hanno il seguente formato:

  • Intestazione risposta client: customer/trace/<generated-span-id>

  • Intestazione della richiesta backend: customer/trace

Confronta valori ID richiesta

Inviare richieste di test e confrontare il valore opc-request-id nelle seguenti posizioni:

  • Il valore di intestazione inviato dal client.

  • Valore dell'intestazione della risposta che il gateway API restituisce al client.

  • Valore dell'intestazione della richiesta che il servizio backend riceve dal gateway API.

Ad esempio, inviare una richiesta con un valore opc-request-id noto:

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

Verificare almeno i seguenti valori:

  • Nessuna intestazione opc-request-id.

  • opc-request-id: abcdef.

  • opc-request-id: /abcdef.

  • opc-request-id: customer/trace.

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

Rivedi voci log

Utilizzare il valore opc-request-id completo restituito nell'intestazione della risposta client quando si esegue una ricerca nei log di accesso e nei log di esecuzione del gateway API.

Controllare le seguenti voci di log:

  • Voce del log di accesso del gateway API per la richiesta.

  • Voce del log di esecuzione del gateway API per la richiesta.

  • Voce di log backend per la richiesta inoltrata.

Non presumere che il servizio backend registri lo stesso valore completo che il gateway API restituisce al client. Il servizio back-end riceve il modulo a valle, customerId/traceId, non il modulo visibile al client, customerId/traceId/spanId.

Correggi problemi di correlazione

Per evitare problemi di correlazione, attenersi alle procedure riportate di seguito.

  • Non avviare un valore opc-request-id fornito dal client con una barra (/) a meno che non si desideri un ID cliente vuoto e un ID traccia esplicito.

  • Non fare affidamento sulla conservazione di un terzo segmento fornito dal client.

  • Se il servizio backend o lo strumento APM prevede una singola stringa di correlazione opaca, utilizzare un'intestazione di applicazione separata per tale valore di correlazione.

  • Utilizzare il valore completo dell'intestazione della risposta visibile al client per la correlazione del log del gateway API.

  • Utilizzare il valore a valle in due parti quando si controllano i log backend.

Verifica correlazione ID richiesta

Dopo aver aggiornato il formato della richiesta o la strategia di correlazione, verificare il risultato:

  • Inviare di nuovo la stessa richiesta.

  • Verificare che l'intestazione della risposta opc-request-id abbia la struttura prevista.

  • Confermare che è possibile trovare la stessa richiesta nei log degli accessi e nei log di esecuzione.

  • Verificare che il servizio backend riceva il valore opc-request-id in due parti previsto.

  • Verificare che lo strumento APM o il parser di log backend non richiedano che il valore dell'intestazione della risposta e il valore della richiesta a valle siano identici.

Per ulteriori informazioni

Per ulteriori informazioni, fare riferimento agli argomenti sotto riportati.