Documentación de Oracle Cloud Infrastructure

Los valores de opc-request-id vistos por el cliente, los logs de API Gateway y el backend no coinciden según lo esperado

Descubra cómo solucionar problemas de correlación y comportamiento de propagación de opc-request-id al llamar a las API, después de haber creado correctamente gateways y despliegues de API con el servicio API Gateway.

Utilice los valores opc-request-id para correlacionar una solicitud de cliente con logs de gateway de API y logs de backend. El valor que envía el cliente puede diferir del valor que recibe el cliente en la respuesta y del valor que recibe el servicio backend de API Gateway.

API Gateway analiza el valor entrante, mantiene las partes seleccionadas del valor y genera un nuevo ID de período para la solicitud. Utilice el comportamiento de análisis de este tema para seleccionar el valor correcto para la correlación de logs.

Emitir síntomas

Es posible que vea uno o más de los siguientes síntomas:

  • La cabecera de respuesta opc-request-id devuelta al cliente no coincide con el valor que ha enviado el cliente.

  • El servicio de backend registra un valor opc-request-id que difiere del valor devuelto al cliente.

  • Los logs de Application Performance Monitoring (APM) o de backend muestran colisiones inesperadas, valores que faltan o truncamiento cuando un opc-request-id proporcionado por el cliente contiene una barra diagonal (/).

  • No puede encontrar la misma solicitud en la respuesta del cliente, los logs de acceso de API Gateway, los logs de ejecución de API Gateway y los logs de backend mediante un único valor de cabecera.

Causas posibles

Los valores pueden diferir por los siguientes motivos:

  • API Gateway no trata opc-request-id como un valor de transferencia opaco.

  • API Gateway divide el valor entrante en el carácter de barra inclinada (/) y utiliza solo las partes de ID de cliente e ID de rastreo.

  • API Gateway genera un nuevo ID de período para cada solicitud.

  • El encabezado de respuesta devuelto al cliente incluye el ID de período generado, pero el encabezado enviado al servicio de backend no incluye el ID de período.

  • Cualquier tercer segmento proporcionado por el cliente, como un ID de período, se ignora para la propagación.

Descripción del análisis de opc-request-id

El gateway de API divide un valor opc-request-id entrante en una barra inclinada (/) con un máximo de tres partes. Utiliza las dos primeras partes analizadas e ignora cualquier tercera parte.

API Gateway interpreta las partes analizadas de la siguiente manera:

  • Primera parte: ID de cliente.

  • Segunda parte: ID de rastreo.

  • Tercera parte: valor ignorado.

A continuación, API Gateway genera un ID de período para la solicitud y crea los siguientes valores:

  • Cabecera de respuesta devuelta al cliente: customerId/traceId/spanId.

  • Cabecera de solicitud enviada al servicio de backend: customerId/traceId.

Utilice el valor de cabecera de respuesta completa al buscar logs de API Gateway. Utilice el valor descendente de dos partes al buscar logs de backend.

Revisar patrones de entrada comunes

Utilice estos ejemplos para comprender cómo API Gateway cambia los valores comunes de opc-request-id.

Sin cabecera opc-request-id

Si el cliente no envía una cabecera opc-request-id, API Gateway genera un ID de rastreo y un ID de período. El ID de cliente está vacío.

Los valores resultantes tienen el siguiente formato:

  • Cabecera de respuesta de cliente: /<generated-trace-id>/<generated-span-id>

  • Cabecera de solicitud de backend: /<generated-trace-id>

Un segmento: abcdef

Si el cliente envía la siguiente cabecera, API Gateway trata el valor como el ID de cliente:

opc-request-id: abcdef

Los valores interpretados son los siguientes:

  • ID de cliente: abcdef.

  • ID de rastreo: generado por el gateway de API.

  • ID de intervalo: generado por API Gateway.

Los valores resultantes tienen el siguiente formato:

  • Cabecera de respuesta de cliente: abcdef/<generated-trace-id>/<generated-span-id>

  • Cabecera de solicitud de backend: abcdef/<generated-trace-id>

Barra inicial: /abcdef

Si el cliente envía la siguiente cabecera, API Gateway trata el valor después de la barra como el ID de rastreo:

opc-request-id: /abcdef

Los valores interpretados son los siguientes:

  • ID de cliente: vacío.

  • ID de rastreo: abcdef.

  • ID de intervalo: generado por API Gateway.

Los valores resultantes tienen el siguiente formato:

  • Cabecera de respuesta de cliente: /abcdef/<generated-span-id>

  • Cabecera de solicitud de backend: /abcdef

Una barra inclinada al principio cambia el significado del valor porque la parte de ID de cliente está vacía.

Dos segmentos: customer/trace

Si el cliente envía la siguiente cabecera, API Gateway utiliza ambas partes proporcionadas:

opc-request-id: customer/trace

Los valores interpretados son los siguientes:

  • ID de cliente: customer

  • ID de rastreo: trace

  • ID de intervalo: generado por API Gateway

Los valores resultantes tienen el siguiente formato:

  • Cabecera de respuesta de cliente: customer/trace/<generated-span-id>

  • Cabecera de solicitud de backend: customer/trace

Tres segmentos: customer/trace/span

Si el cliente envía la siguiente cabecera, API Gateway ignora el tercer segmento y genera un nuevo ID de período:

opc-request-id: customer/trace/span

Los valores interpretados son los siguientes:

  • ID de cliente: customer.

  • ID de rastreo: trace.

  • Tercer segmento: ignorado.

  • ID de intervalo: generado por API Gateway.

Los valores resultantes tienen el siguiente formato:

  • Cabecera de respuesta de cliente: customer/trace/<generated-span-id>

  • Cabecera de solicitud de backend: customer/trace.

El valor de intervalo proporcionado por el cliente no se conserva.

Más de tres segmentos: customer/trace/span/extra

Si el cliente envía la siguiente cabecera, API Gateway sigue utilizando solo los dos primeros segmentos:

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

Los valores interpretados son los siguientes:

  • ID de cliente: customer

  • ID de rastreo: trace

Todo el contenido después de la segunda barra inclinada se ignora para la propagación.

Los valores resultantes tienen el siguiente formato:

  • Cabecera de respuesta de cliente: customer/trace/<generated-span-id>

  • Cabecera de solicitud de backend: customer/trace

Comparar valores de ID de solicitud

Envíe solicitudes de prueba y compare el valor opc-request-id en las siguientes ubicaciones:

  • Valor de cabecera que envía el cliente.

  • Valor de cabecera de respuesta que API Gateway devuelve al cliente.

  • Valor de cabecera de solicitud que recibe el servicio backend de API Gateway.

Por ejemplo, envíe una solicitud con un valor opc-request-id conocido:

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

Pruebe al menos los siguientes valores:

  • Sin cabecera opc-request-id.

  • opc-request-id: abcdef.

  • opc-request-id: /abcdef.

  • opc-request-id: customer/trace.

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

Revisar entradas de log

Utilice el valor opc-request-id completo devuelto en la cabecera de respuesta del cliente al buscar logs de acceso y logs de ejecución de API Gateway.

Consulte las siguientes entradas de log:

  • Entrada del log de acceso de API Gateway para la solicitud.

  • Entrada del log de ejecución de API Gateway para la solicitud.

  • Entrada de log de backend para la solicitud reenviada.

No suponga que el servicio backend registra el mismo valor completo que el gateway de API devuelve al cliente. El servicio backend recibe el formulario descendente, customerId/traceId, no el formulario visible para el cliente, customerId/traceId/spanId.

Corregir problemas de correlación

Utilice las siguientes prácticas para evitar problemas de correlación:

  • No inicie un valor opc-request-id proporcionado por el cliente con una barra diagonal (/) a menos que desee un ID de cliente vacío y un ID de rastreo explícito.

  • No confíe en que se conserve un tercer segmento proporcionado por el cliente.

  • Si el servicio de backend o la herramienta APM espera una única cadena de correlación opaca, utilice una cabecera de aplicación independiente para ese valor de correlación.

  • Utilice el valor completo de cabecera de respuesta visible para el cliente para la correlación de logs de API Gateway.

  • Utilice el valor descendente de dos partes al comprobar los logs de backend.

Verificar correlación de ID de solicitud

Después de actualizar el formato de solicitud o la estrategia de correlación, verifique el resultado:

  • Vuelva a enviar la misma solicitud.

  • Confirme que la cabecera de respuesta opc-request-id tiene la estructura esperada.

  • Confirme que puede encontrar la misma solicitud en los logs de acceso y los logs de ejecución.

  • Confirme que el servicio de backend recibe el valor opc-request-id de dos partes esperado.

  • Confirme que la herramienta de APM o el analizador de logs de backend no necesitan que el valor de cabecera de respuesta y el valor de solicitud descendente sean idénticos.

Para obtener más información

Para obtener más información, consulte: