Documentação do Oracle Cloud Infrastructure

os valores de opc-request-id vistos pelo cliente, logs do Gateway de API e backend não correspondem conforme esperado

Descubra como diagnosticar e solucionar problemas de correlação e comportamento de propagação de opc-request-id ao chamar APIs, tendo criado com sucesso gateways de API e implantações de API com o serviço API Gateway.

Use valores opc-request-id para correlacionar uma solicitação de cliente com logs do Gateway de API e logs de back-end. O valor que o cliente envia pode ser diferente do valor que o cliente recebe na resposta e do valor que o serviço de back-end recebe do Gateway de API.

O API Gateway analisa o valor de entrada, mantém partes selecionadas do valor e gera um novo ID de intervalo para a solicitação. Use o comportamento de parsing neste tópico para escolher o valor correto para a correlação de logs.

Sintomas do Problema

Você pode ver um ou mais dos seguintes sintomas:

  • O cabeçalho de resposta opc-request-id retornado ao cliente não corresponde ao valor enviado pelo cliente.

  • O serviço de back-end registra um valor opc-request-id que difere do valor retornado para o cliente.

  • Os logs do Application Performance Monitoring (APM) ou de back-end mostram colisões inesperadas, valores ausentes ou truncamento quando um opc-request-id fornecido pelo cliente contém uma barra (/).

  • Não é possível encontrar a mesma solicitação na resposta do cliente, nos logs de acesso do Gateway de API, nos logs de execução do Gateway de API e nos logs de back-end usando um único valor de cabeçalho.

Possíveis Causas

Os valores podem ser diferentes pelos seguintes motivos:

  • O API Gateway não trata opc-request-id como um valor de passagem opaco.

  • O API Gateway divide o valor de entrada no caractere de barra (/) e usa apenas as partes do ID do cliente e do ID de rastreamento.

  • O API Gateway gera um novo ID de intervalo para cada solicitação.

  • O cabeçalho de resposta retornado ao cliente inclui o ID de intervalo gerado, mas o cabeçalho enviado ao serviço de back-end não inclui o ID de intervalo.

  • Qualquer terceiro segmento fornecido pelo cliente, como um ID de intervalo, é ignorado para propagação.

Entender a Análise opc-request-id

O Gateway de API divide um valor opc-request-id de entrada em caracteres de barra (/), com no máximo três partes. Ele usa as duas primeiras partes analisadas e ignora qualquer terceira parte.

O API Gateway interpreta as partes analisadas da seguinte forma:

  • Primeira parte: ID do Cliente.

  • Segunda parte: ID do Rastreamento.

  • Terceira parte: Valor ignorado.

Em seguida, o API Gateway gera um ID de intervalo para a solicitação e cria os seguintes valores:

  • O cabeçalho de resposta retornou ao cliente: customerId/traceId/spanId.

  • Cabeçalho de solicitação enviado ao serviço de back-end: customerId/traceId.

Use o valor completo do cabeçalho de resposta ao pesquisar logs do Gateway de API. Use o valor downstream de duas partes ao pesquisar logs de back-end.

Revisar Padrões de Entrada Comuns

Use esses exemplos para entender como o Serviço API Gateway altera valores comuns opc-request-id.

Nenhum Cabeçalho opc-request-id

Se o cliente não enviar um cabeçalho opc-request-id, o Serviço API Gateway gerará um ID de rastreamento e um ID de intervalo. O ID do cliente está vazio.

Os valores resultantes têm o seguinte formato:

  • Cabeçalho de resposta do cliente: /<generated-trace-id>/<generated-span-id>

  • Cabeçalho da solicitação de back-end: /<generated-trace-id>

Um Segmento: abcdef

Se o cliente enviar o seguinte cabeçalho, o Gateway de API tratará o valor como o ID do cliente:

opc-request-id: abcdef

Os valores interpretados são os seguintes:

  • ID do Cliente: abcdef.

  • ID do Rastreamento: Gerado pelo Gateway de API.

  • ID de Intervalo: Gerado pelo Serviço API Gateway.

Os valores resultantes têm o seguinte formato:

  • Cabeçalho de resposta do cliente: abcdef/<generated-trace-id>/<generated-span-id>

  • Cabeçalho da solicitação de back-end: abcdef/<generated-trace-id>

Barra inicial: /abcdef

Se o cliente enviar o seguinte cabeçalho, o API Gateway tratará o valor após a barra como o ID de rastreamento:

opc-request-id: /abcdef

Os valores interpretados são os seguintes:

  • ID do Cliente: Vazio.

  • ID do Rastreamento: abcdef.

  • ID de Intervalo: Gerado pelo Serviço API Gateway.

Os valores resultantes têm o seguinte formato:

  • Cabeçalho de resposta do cliente: /abcdef/<generated-span-id>

  • Cabeçalho da solicitação de back-end: /abcdef

Uma barra à esquerda altera o significado do valor porque a parte do ID do cliente está vazia.

Dois Segmentos: customer/trace

Se o cliente enviar o seguinte cabeçalho, o API Gateway usará as duas partes fornecidas:

opc-request-id: customer/trace

Os valores interpretados são os seguintes:

  • ID do cliente: customer

  • ID do Rastreamento: trace

  • Span ID: Gerado pelo Serviço API Gateway

Os valores resultantes têm o seguinte formato:

  • Cabeçalho de resposta do cliente: customer/trace/<generated-span-id>

  • Cabeçalho da solicitação de back-end: customer/trace

Três Segmentos: customer/trace/span

Se o cliente enviar o seguinte cabeçalho, o Gateway de API ignorará o terceiro segmento e gerará um novo ID de intervalo:

opc-request-id: customer/trace/span

Os valores interpretados são os seguintes:

  • ID do Cliente: customer.

  • ID do Rastreamento: trace.

  • Terceiro segmento: Ignorado.

  • ID de Intervalo: Gerado pelo Serviço API Gateway.

Os valores resultantes têm o seguinte formato:

  • Cabeçalho de resposta do cliente: customer/trace/<generated-span-id>

  • Cabeçalho da solicitação de backend: customer/trace.

O valor de intervalo fornecido pelo cliente não é preservado.

Mais de três segmentos: customer/trace/span/extra

Se o cliente enviar o seguinte cabeçalho, o Gateway de API ainda usará apenas os dois primeiros segmentos:

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

Os valores interpretados são os seguintes:

  • ID do cliente: customer

  • ID do Rastreamento: trace

Todo o conteúdo após a segunda barra é ignorado para propagação.

Os valores resultantes têm o seguinte formato:

  • Cabeçalho de resposta do cliente: customer/trace/<generated-span-id>

  • Cabeçalho da solicitação de back-end: customer/trace

Comparar Valores ID Solicitação

Envie solicitações de teste e compare o valor opc-request-id nos seguintes locais:

  • O valor do cabeçalho que o cliente envia.

  • O valor do cabeçalho de resposta que o Gateway de API retorna ao cliente.

  • O valor do cabeçalho da solicitação que o serviço de back-end recebe do Gateway de API.

Por exemplo, envie uma solicitação com um valor opc-request-id conhecido:

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

Teste pelo menos os seguintes valores:

  • Nenhum cabeçalho opc-request-id.

  • opc-request-id: abcdef.

  • opc-request-id: /abcdef.

  • opc-request-id: customer/trace.

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

Verificar Entradas de Log

Use o valor opc-request-id completo retornado no cabeçalho de resposta do cliente ao pesquisar logs de acesso e logs de execução do Gateway de API.

Verifique as seguintes entradas de log:

  • A entrada de log de acesso do Gateway de API para a solicitação.

  • A entrada do log de execução do Gateway de API para a solicitação.

  • A entrada de log de back-end para a solicitação encaminhada.

Não suponha que o serviço de back-end registre o mesmo valor total que o Gateway de API retorna ao cliente. O serviço de back-end recebe o formulário downstream, customerId/traceId, não o formulário visível ao cliente, customerId/traceId/spanId.

Corrigir Problemas de Correlação

Use as seguintes práticas para evitar problemas de correlação:

  • Não inicie um valor opc-request-id fornecido pelo cliente com uma barra (/), a menos que você queira um ID de cliente vazio e um ID de rastreamento explícito.

  • Não confie em um terceiro segmento fornecido pelo cliente sendo preservado.

  • Se o serviço de back-end ou a ferramenta do APM esperar uma única string de correlação opaca, use um cabeçalho de aplicativo separado para esse valor de correlação.

  • Use o valor completo do cabeçalho de resposta visível ao cliente para correlação de log do Gateway de API.

  • Use o valor de downstream de duas partes ao verificar logs de back-end.

Verificar correlação do ID da solicitação

Após atualizar o formato da solicitação ou a estratégia de correlação, verifique o resultado:

  • Envie a mesma solicitação novamente.

  • Confirme se o cabeçalho de resposta opc-request-id tem a estrutura esperada.

  • Confirme se você pode encontrar a mesma solicitação nos logs de acesso e de execução.

  • Confirme se o serviço de back-end recebe o valor opc-request-id de duas partes esperado.

  • Confirme se a ferramenta do APM ou o analisador de log de back-end não exige que o valor do cabeçalho de resposta e o valor da solicitação de downstream sejam idênticos.

Para obter mais informações

Para obter mais informações, consulte: