Cuando una operación atraviesa una petición HTTP, una cola y uno o varios servicios externos, sus registros quedan repartidos entre procesos distintos. Sin un dato común, investigar una incidencia obliga a buscar por hora, usuario o contenido, criterios que pueden ser ambiguos o sensibles. Un identificador de correlación en PHP permite agrupar los eventos relacionados con una operación y reconstruir su recorrido.
Para que funcione, el identificador debe tener un origen definido, viajar explícitamente entre límites asíncronos y aparecer en los registros de forma consistente. No es una solución de observabilidad completa ni una credencial: sirve para relacionar eventos, no para explicar por sí solo qué falló ni quién está autorizado.
Qué resuelve y qué queda fuera
Un identificador de correlación es un valor opaco asociado a una petición u operación. Al incorporarlo a los logs de la aplicación, permite localizar mensajes producidos en distintos componentes que comparten ese valor. Por ejemplo, se puede relacionar la recepción de una petición con el despacho de un trabajo, su consumo y la respuesta de una API externa.
Esto mejora el diagnóstico cuando los logs están centralizados y son consultables por campos. No garantiza, sin embargo, que todos los componentes hayan registrado correctamente el identificador, ni mide duración, volumen o errores agregados. Las métricas sirven para tendencias y alertas; las trazas distribuidas muestran relaciones y tiempos entre componentes; los logs aportan eventos y contexto. Son señales complementarias.
Tampoco debe confundirse correlación con autenticación, autorización o identidad del usuario. Conocer un identificador no debería dar acceso a datos ni permitir ejecutar una operación. Si el valor se expone en una URL o un sistema de terceros, puede ser visible para más personas de las previstas.
Definir dónde se genera y cómo se valida
En una aplicación, el punto habitual para iniciar el contexto es el middleware HTTP que recibe la petición. Puede aceptar un identificador entrante para mantener continuidad con un proxy o servicio anterior, o generar uno nuevo cuando no existe. La política debe ser explícita: confiar en todos los valores externos puede permitir entradas malformadas, de longitud excesiva o preparadas para contaminar logs.
Para tráfico público, una opción segura es generar siempre un identificador interno y, si se necesita preservar el valor entrante, tratarlo como dato no confiable y validarlo de forma estricta. Otra alternativa es aceptar el valor del encabezado únicamente desde componentes de confianza, con reglas configuradas en el perímetro. La elección depende de la arquitectura y de quién puede llamar al servicio.
El formato debe ser sencillo de validar y compatible con los sistemas que lo transportan. Puede emplearse un valor aleatorio generado con una fuente criptográfica del sistema, como random_bytes(), codificado en un alfabeto acotado. No conviene construirlo con marcas de tiempo, direcciones IP o datos personales. Un identificador único no necesita revelar información de negocio.
$correlationId = bin2hex(random_bytes(16));
Este ejemplo genera un valor aleatorio hexadecimal; no prescribe un formato universal. Define una longitud máxima, caracteres permitidos y el encabezado que usarán los componentes, por ejemplo X-Correlation-ID. Si la plataforma ya adopta un estándar de trazas, evita crear un mecanismo paralelo sin necesidad: la correlación de logs y el contexto de traza pueden coexistir, pero no son conceptos idénticos.
Propagar el contexto por cada límite
En el middleware, valida o crea el identificador al comienzo de la petición y añádelo al contexto de logging. Si se devuelve al cliente en una respuesta, asegúrate de que no se expone información adicional y de que la política de confianza está clara. El resto de la aplicación debería recibir el contexto mediante una dependencia explícita, no depender de variables globales difíciles de probar.
Dentro del proceso PHP, pasa el identificador a los servicios que registran eventos relevantes. Para los trabajos asíncronos, inclúyelo en los metadatos del mensaje o en un campo dedicado del payload, según las convenciones del sistema de colas. Al consumir el mensaje, restaura el contexto antes de ejecutar el trabajo y límpialo al terminar. Esto importa especialmente en procesos de larga duración, donde el mismo worker atiende mensajes sucesivos: un contexto no limpiado puede filtrarse a otra operación.
Al llamar a una API externa, transmite el valor en un encabezado acordado solo si el proveedor lo admite y si compartirlo es apropiado. No envíes datos internos innecesarios. Para integraciones que no conservan encabezados, registra el identificador junto con el resultado local de la llamada; no des por hecho que el sistema remoto lo devolverá en sus propios logs.
Si la petición produce varios trabajos independientes, cada uno puede conservar el identificador de la operación de origen. Si, en cambio, se necesita distinguir suboperaciones, añade un identificador propio para cada una y mantén la relación mediante el contexto de traza o campos de negocio no sensibles. Evita reutilizar el mismo valor con semánticas distintas sin documentarlo.
Usarlo en logs estructurados, no como sustituto de la observabilidad
Registra el identificador como un campo estructurado, por ejemplo correlation_id, en vez de incorporarlo solo a una frase de texto. Así, una plataforma de logs puede filtrar y agrupar eventos sin depender de búsquedas aproximadas. Mantén una convención uniforme entre aplicación, workers e integraciones, y verifica que el serializador no lo omita.
Inclúyelo en eventos útiles para el diagnóstico: recepción de petición, creación del mensaje, inicio y final del trabajo, y resultado de una llamada externa. No es necesario repetirlo en cada línea si el sistema ofrece contexto persistente por operación. En ese caso, comprueba que el contexto se restablece entre peticiones y que los registros siguen siendo interpretables si un componente no lo admite.
No uses el identificador como etiqueta de métricas con alta cardinalidad. Crear una serie temporal por cada petición puede elevar el coste y volver las métricas poco útiles. Tampoco registres junto a él tokens, contraseñas, datos de pago, contenido completo de mensajes ni información personal que no sea necesaria. Aplica las reglas de minimización, acceso y retención de logs de la organización.
Reintentos, ejecuciones diferidas y fallos
Un reintento del mismo trabajo suele conservar el identificador de correlación original: sigue siendo parte de la misma operación lógica. Para distinguir intentos, registra un número de intento o un identificador específico del intento, sin reemplazar el contexto original. De este modo se puede investigar tanto el recorrido completo como la causa de cada ejecución.
Si un trabajo se programa para ejecutarse mucho más tarde, conserva el identificador como metadato persistente; no dependas de memoria del proceso ni de una sesión HTTP que ya terminó. Si el trabajo inicia una operación nueva y autónoma, define si hereda el contexto de origen o recibe uno nuevo, y registra la relación entre ambos. Esta decisión evita que una correlación demasiado amplia mezcle tareas no relacionadas.
Cuando la cola o un servicio externo descarta metadatos, documenta el límite y conserva el contexto en el componente que sí controlas. La aplicación debe seguir siendo operable si falta el identificador: genera uno al entrar en el proceso o registra claramente que el contexto no estaba disponible.
Pruebas y comprobaciones operativas
- Prueba el middleware con identificador ausente, válido y malformado; confirma que aplica la política definida y que el valor no excede los límites.
- Verifica que el identificador de la petición aparece en los logs de los servicios internos y en los metadatos del mensaje enviado a la cola.
- Ejecuta un mensaje en un worker y comprueba que el contexto se incorpora a los logs y se limpia antes del siguiente mensaje.
- Simula un reintento y confirma que se conserva la correlación original y que el intento puede diferenciarse.
- Comprueba la salida de la llamada externa y el tratamiento de errores, sin exponer secretos ni cuerpos sensibles en los registros.
- Revisa que los dashboards y alertas no dependan de buscar identificadores individuales en métricas.
Una comprobación de extremo a extremo debe seguir una operación de prueba desde la entrada HTTP hasta el trabajo y su integración, consultando los logs por el mismo campo. Si falta en un tramo, identifica el límite exacto: middleware, serialización del mensaje, consumidor, cliente HTTP o configuración del logger. Esa observación señala dónde corregir la propagación, en lugar de añadir registros indiscriminadamente.
La decisión práctica es mantener un contexto pequeño, explícito y no sensible, con reglas claras de confianza y ciclo de vida. Así, el identificador de correlación en PHP reduce el tiempo de búsqueda durante una incidencia sin sustituir controles de seguridad, trazas, métricas ni un diseño cuidadoso de los logs.
