Diagrama de arquitectura de observabilidad: logs, métricas y trazas con OpenTelemetry

La mayoría de los diagramas de arquitectura terminan en los servicios. El camino de la telemetría se dibuja después, durante un incidente, a cargo de quien intenta averiguar por qué falta la mitad de las trazas o por qué se ha duplicado la factura de logs. Para entonces, la respuesta depende de detalles que nadie escribió: qué componente hace muestreo, cuál añade el nombre del pod y qué pasa cuando un backend va lento.

Un diagrama de arquitectura de observabilidad muestra cómo salen los logs, las métricas y las trazas de cada servicio, dónde se enriquecen, se muestrean y se filtran, y dónde terminan. Este artículo construye uno en torno a OpenTelemetry sobre Kubernetes, explica los patrones de agente y gateway que hay detrás y enumera qué etiquetar para que el diagrama siga sirviendo en la próxima caída.

Tres señales, tres preguntas

Las tres solo sirven juntas si comparten contexto. Un trace ID en la línea de log, y el mismo service.name y nombre de pod en todas las señales, te permiten saltar de una alerta al span lento y de ahí a la línea de log que lo explica. La arquitectura tiene que conservar ese contexto.

Las piezas

OTLP es el protocolo de OpenTelemetry para las tres señales. La especificación fija los puertos por defecto: 4317 para OTLP sobre gRPC y 4318 para OTLP sobre HTTP.

Los SDK y la instrumentación automática se ejecutan dentro de cada servicio y exportan OTLP. Apúntalos a un Collector local en vez de a un proveedor, para que los cambios de enrutamiento no exijan un nuevo despliegue.

El Collector es un único binario con pipelines por señal: los receivers reciben los datos, los processors los modifican y los exporters los envían. La documentación de despliegue describe dos formas principales de ejecutarlo:

• Agente. Un Collector se ejecuta junto a la aplicación, como sidecar o como DaemonSet con un pod por nodo. En Kubernetes, el agente es también donde trabajan los componentes de Kubernetes: el Kubernetes Attributes Processor añade los nombres de pod, namespace y deployment, el Filelog Receiver sigue el stdout y el stderr de los contenedores y el Kubeletstats Receiver obtiene métricas de nodos y pods.
• Gateway. Uno o varios Collectors se ejecutan como un servicio independiente, normalmente un punto de conexión por clúster, centro de datos o región. La gateway es el lugar para las decisiones que quieres tomar una sola vez: el muestreo, el filtrado de atributos sensibles, la custodia de las credenciales de los backends y el envío a más de un backend.

Head sampling o tail sampling

Las trazas son la señal cara, así que la mayoría de los equipos las muestrean. El head sampling decide cuando empieza la traza, por ejemplo quedarse con el 10 %. Es barato, pero no puede conservar una traza porque después haya fallado. El tail sampling decide tras ver todos o casi todos los spans de una traza, así que puede quedarse con cada error y cada petición lenta.

El tail sampling tiene un coste estructural: todos los spans de una traza tienen que llegar al mismo Collector. Detrás de un balanceador round-robin no ocurre. El patrón de gateway lo resuelve con dos niveles: el primero ejecuta el load-balancing exporter con el trace ID como clave de enrutamiento y el segundo, el tail sampling processor. Son dos cajas en el diagrama, y merece la pena mostrar ambas.

El ejemplo: una tienda en Kubernetes

La tienda ejecuta tres Deployments en un namespace shop: web, checkout-api y payments-worker, cada uno con el SDK de OpenTelemetry. El namespace observability contiene el pipeline: un DaemonSet otel-agent, un Deployment otel-lb que enruta los spans por trace ID y un Deployment otel-sampler que aplica la política de tail sampling. Métricas, trazas y logs van cada uno a su propio almacén, y las reglas de alerta se ejecutan sobre las métricas.

Cómo leerlo:

• A la izquierda, los servicios. Cada Deployment exporta trazas, métricas y logs por OTLP/gRPC en el puerto 4317 al agente de su nodo. La conexión discontinua es el stdout de los contenedores, que el agente lee del nodo en lugar de recibirlo por la red.
• En el centro, el agente. El agente añade metadatos de Kubernetes a todo y después envía métricas y logs directamente a sus almacenes, y las trazas a la gateway.
• En el centro, la gateway. otel-lb enruta cada span por trace ID, de modo que todos los spans de una traza llegan al mismo pod de otel-sampler, que conserva los errores y las trazas lentas y muestrea el resto.
• A la derecha, almacenamiento y alertas. Cada señal tiene su propio backend. Las reglas de alerta leen las métricas y avisan a quien esté de guardia.
• El bloque Markdown recoge la política de muestreo y la única regla que sigue todo pipeline: primero el memory limiter.

Qué etiquetar

• Protocolo y puerto en cada salto. OTLP/gRPC 4317 u OTLP/HTTP 4318, y el formato de exportación hacia cada backend.
• Qué señales viajan por cada conexión. Un pipeline rara vez lleva las tres de la misma manera.
• Dónde se hace el muestreo y con qué política. Escribe los números; un simple "muestreado" invita a suposiciones equivocadas.
• Dónde se enriquecen o se ocultan los datos. Metadatos de Kubernetes en el agente; eliminación de tokens y datos personales en la gateway.
• La retención de cada backend. Explica el coste y lo que todavía puede encontrar una investigación.
• El comportamiento ante fallos. Colas, reintentos y qué se descarta cuando un backend cae.

Errores comunes

• SDK que exportan directamente a un proveedor. Cada cambio de enrutamiento o de credenciales se convierte en un despliegue, y no hay ningún sitio donde filtrar los datos antes de que salgan.
• Tail sampling detrás de un balanceador simple. Los spans de una traza acaban en Collectors distintos y las decisiones de muestreo se toman sobre fragmentos.
• Sin memory limiter. La documentación de configuración incluye un processor memory_limiter; ponlo el primero en cada pipeline para que, ante un pico, el Collector rechace datos en lugar de quedarse sin memoria.
• Etiquetas de métricas con alta cardinalidad. Un ID de usuario o de petición como etiqueta de métrica multiplica las series temporales. Ponlo en los spans y en los logs.
• Un pipeline sin vigilancia. El Collector expone sus propias métricas, por defecto en el puerto 8888, como describe su documentación de telemetría interna. Crea alertas para las exportaciones fallidas, o te enterarás de la pérdida de datos en el incidente que los necesitaba.

Para el propio clúster, el diagrama de arquitectura de Kubernetes cubre el plano de control, los nodos y las cargas de trabajo, y el diagrama de arquitectura de microservicios cubre los servicios que observa este pipeline.

Constrúyelo en Archboard

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Del pack Kubernetes, añade dos marcos Namespace, shop y observability. Pon un Deployment por cada servicio en shop.
3. En observability, añade un DaemonSet para el agente y dos nodos Deployment para los niveles de balanceo y de muestreo.
4. Del pack DevOps, añade nodos Métricas, Trazas y Registros para los backends y un nodo Alerta para las alertas.
5. Conéctalos y etiqueta cada conexión con las señales y el protocolo, por ejemplo "OTLP/gRPC 4317". Haz discontinua la conexión de los logs de contenedores.
6. Añade un bloque Markdown del pack Básico con la política de muestreo.

El ejemplo usa 13 nodos de diagrama, dentro del plan Free. Si tus servicios ya se ejecutan en Kubernetes, la herramienta Kubernetes YAML a diagrama convierte los manifiestos en un primer borrador de la mitad izquierda.

Preguntas frecuentes

¿Necesito un Collector en gateway o bastan los agentes? Los agentes solos sirven para instalaciones pequeñas. Añade una gateway cuando necesites tail sampling, un solo lugar para credenciales y filtrado o varios backends; entonces el agente reenvía los datos a la gateway.

¿También los logs deberían pasar por el Collector? Pueden. El Filelog Receiver del agente lee los logs de los contenedores, añade los mismos metadatos de Kubernetes que en trazas y métricas y te permite filtrar antes de almacenar. Muchos equipos pasan los logs al Collector en último lugar, después de trazas y métricas.

¿Alguna vez basta con el head sampling? Sí, cuando el tráfico es bajo o todas las trazas se parecen. Si necesitas cada error y cada petición lenta, usa tail sampling y dibuja los dos niveles de gateway que requiere.

¿Dónde van los paneles y las alertas en el diagrama? Junto al almacén que consultan. Las reglas de alerta sobre métricas forman parte de la arquitectura: deciden a quién se despierta.

¿Cómo mantengo este diagrama al día? Cámbialo en el mismo pull request que la configuración del Collector y enlázalo desde el runbook. Consulta diagramas de arquitectura que no se quedan obsoletos.

Empieza gratis — un puesto, sin tarjeta de crédito.