OpenTelemetry en Kubernetes: diagnosticar por qué no llegan las trazas

Sigue el recorrido antes de cambiar la configuración

Una traza pasa por varias etapas: la aplicación crea spans, su SDK los exporta, un Collector puede recibirlos y procesarlos, y un exporter los envía al backend de observabilidad. El Collector es opcional en algunas arquitecturas. Primero dibuja el camino que usa tu plataforma y marca cada salto; así evitas cambiar puertos o políticas en un componente que no está perdiendo los datos.

Antes de editar recursos, registra el namespace, las versiones de la aplicación y del Collector, el método de instalación y el destino esperado. Reproduce una solicitud de prueba identificable y anota su hora. No publiques manifests completos, tokens, certificados ni datos de clientes al pedir ayuda.

1. Confirma que la aplicación crea y exporta spans

Una aplicación puede responder correctamente y no generar trazas si la instrumentación no está activa, el SDK está en modo no-op, el muestreo descarta esa solicitud o la exportación apunta a otro destino. Comprueba en la configuración efectiva —no solo en el manifiesto fuente— el lenguaje, la librería o agente de instrumentación, el endpoint OTLP, el protocolo y el método de autenticación.

• Identidad: confirma que el recurso define un service.name estable. Sin él, las trazas pueden aparecer bajo un nombre inesperado o mezclarse con otros servicios.
• Destino: verifica host, puerto, TLS y credenciales desde el Pod de la aplicación. Un endpoint válido en una laptop puede no ser resoluble desde el namespace o la red del clúster.
• Instrumentación: genera una solicitud nueva después de revisar la configuración. Una traza antigua o una ruta no instrumentada no sirve para probar ese cambio.
• Exportación: busca errores de DNS, conexión, certificado, autorización, protocolo o timeout en los logs de la aplicación.

Las variables de entorno y los nombres de propiedades cambian por lenguaje, SDK y versión. Usa la guía oficial de tu instrumentación y compara el endpoint con el servicio real del Collector, incluyendo si la aplicación espera OTLP sobre gRPC o HTTP.

2. Revisa recepción, procesamiento y exportación del Collector

Declarar un receiver en el archivo no basta: debe estar conectado a un pipeline de trazas activo. El pipeline también necesita un exporter que apunte al destino correcto. La configuración debe incluir componentes que estén presentes en la distribución instalada; las imágenes contrib y core pueden ofrecer conjuntos distintos.

Inspecciona primero el estado y los logs sin reiniciar el workload:

kubectl get pods,services,endpointslices -n <namespace>
kubectl describe pod <collector-pod> -n <namespace>
kubectl logs <collector-pod> -n <namespace> --since=20m
kubectl logs <collector-pod> -n <namespace> --previous

Revisa especialmente errores de carga de configuración, conexiones rechazadas, exportación fallida, resolución DNS y recursos insuficientes. Comprueba que los endpoints del Service apuntan a Pods listos y que las etiquetas seleccionan la carga correcta. Si el Collector reinicia, compara eventos, límites de memoria y tasa de datos con la configuración del procesador memory_limiter y las colas del exporter.

Consulta las métricas internas y los logs del Collector. La guía oficial de solución de problemas recomienda seguir cada salto: qué recibe, qué modifica, qué exporta y qué restricciones de red afectan la siguiente conexión. También advierte que un receiver definido pero ausente de los pipelines no recibe datos.

3. Separa un problema de red de uno de configuración

Desde el namespace de origen, valida que el nombre del Service resuelva y que el puerto esperado sea accesible. Contrasta ese resultado con NetworkPolicies, reglas de firewall, DNS, proxy y configuración TLS. Un test TCP exitoso solo prueba conectividad al puerto; no valida que cliente y servidor compartan protocolo, certificado, credenciales o formato OTLP.

Compara configuración efectiva de ambos extremos: receptor del Collector, endpoint y protocolo del SDK, exporter de salida, autenticación y URL del backend. Si las trazas entran al Collector pero no aparecen en el backend, enfoca la investigación en el exporter, sus logs, DNS, política de salida y respuesta del destino. Si no entran, empieza por instrumentación, receiver, Service y conectividad de entrada.

4. Prueba el pipeline sin exponer datos

Para aislar recepción y procesamiento, puedes habilitar temporalmente un exporter local de depuración en un entorno controlado. Envía una traza de prueba y verifica si el Collector registra spans. La documentación de OpenTelemetry señala que este método ayuda a confirmar si los datos se reciben, procesan y exportan.

Limita la prueba a datos sintéticos, acceso restringido y una ventana breve. La salida detallada puede imprimir atributos completos. No la actives en una ruta pública ni captures cabeceras de autorización, cookies, direcciones, correos o contenido de solicitudes. Deshabilita el exporter de depuración al terminar y verifica que no quede habilitado en el despliegue normal.

Revisa los atributos que la aplicación y el Collector adjuntan a cada span. Aplica filtrado o redacción antes de exportar datos que puedan identificar personas, revelar secretos o incluir información regulada. La política debe considerar también etiquetas de URL, consultas y errores, que a veces contienen datos ingresados por usuarios.

5. Elige el modelo de Collector que corresponde al flujo

En Kubernetes, un DaemonSet, un Deployment o una instancia gateway resuelven necesidades diferentes. La ubicación de los Pods, la carga, la tolerancia a fallos, el tráfico entre namespaces y las señales recolectadas determinan cuál conviene. No copies un manifiesto de ejemplo a producción sin revisar puertos, permisos, persistencia de colas, afinidad, recursos y límites de red.

Las guías oficiales ofrecen instalaciones de inicio y charts Helm, pero la configuración final depende de tu distribución del Collector, versión de Kubernetes, backend y requisitos de seguridad. Valida el archivo con la herramienta y versión de Collector que realmente vas a ejecutar; después confirma el resultado con una traza de prueba y métricas del pipeline.

Lista breve de diagnóstico

1. Genera una solicitud nueva y confirma que la aplicación está instrumentada.
2. Verifica service.name, endpoint OTLP, protocolo y muestreo.
3. Comprueba que el receiver está en un pipeline de trazas activo.
4. Valida Service, endpoints, DNS, TLS, credenciales y políticas de red.
5. Lee logs y métricas del Collector para localizar el último salto exitoso.
6. Prueba con datos sintéticos; elimina depuración y protege atributos sensibles.
7. Confirma que la traza aparece en el backend con el servicio y tiempo esperados.

Si necesitas soporte, comparte versiones, arquitectura resumida, errores redactados y el resultado de cada salto. Mantén fuera de la conversación kubeconfigs, tokens, certificados, nombres de clientes y trazas con contenido sensible. Un diagnóstico útil explica dónde se corta el flujo y qué evidencia justifica el siguiente cambio.