IA Cheatsheets

🔎 Zipkin Cheatsheet Completo 🔎

Zipkin es un sistema de trazabilidad distribuida de código abierto. Ayuda a recopilar datos de tiempo para cada operación a medida que una solicitud fluye a través de múltiples microservicios. Proporciona una interfaz de usuario para visualizar estos flujos de trazas, facilitando el análisis de latencia, la depuración de microservicios y el monitoreo del rendimiento.

1. 🌟 Conceptos Clave de Zipkin y Trazabilidad

2. 🛠️ Configuración e Instalación de Zipkin Server

2.1. Con Docker (Recomendado para Desarrollo/Pruebas)

docker run -d -p 9411:9411 openzipkin/zipkin

2.2. Con java -jar (Alternativa)

2.3. Configuración de Almacenamiento (Opcional)

Por defecto, Zipkin usa almacenamiento en memoria (no persistente). Para persistencia, usa variables de entorno al iniciar Zipkin:

3. 📝 Instrumentación de Aplicaciones (Spring Boot con Micrometer Tracing)

Micrometer Tracing (el sucesor de Spring Cloud Sleuth) es la forma recomendada de instrumentar aplicaciones Spring Boot para Zipkin (basado en OpenTelemetry).

  1. Añadir dependencias en pom.xml (en tu microservicio):

    <dependencies>
    &lt;!-- Micrometer Tracing Bridge para OpenTelemetry -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-otel</artifactId>
    </dependency>
    &lt;!-- Exporter para Zipkin -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-zipkin</artifactId>
    </dependency>
    &lt;!-- Para la API de OpenTelemetry (si necesitas instrumentación manual) -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
        <version>1.34.1</version> &lt;!-- Usar la versión compatible -->
    </dependency>
    &lt;!-- Spring Boot Actuator para exposición de métricas y health -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

  2. Configurar application.yml (en tu microservicio cliente):

    # src/main/resources/application.yml
spring:
  application:
    name: my-service-name # CRÍTICO: Nombre del servicio para las trazas
  zipkin:
    base-url: http://localhost:9411 # URL del servidor Zipkin
  sleuth: # Propiedades del "bridge" OpenTelemetry
    sampler:
      probability: 1.0 # Muestrear el 100% de las trazas (0.0 a 1.0)
    propagation:
      type: W3C # Usar el formato de encabezado W3C Trace Context (traceparent, tracestate)
      # Otros: B3 (para sistemas antiguos), B3_MULTI, B3_SINGLE

# Configuración explícita del exportador OTel (opcional si spring.zipkin.base-url es suficiente)
management:
  tracing:
    sampling:
      probability: 1.0
    propagation:
      type: W3C
    exporters:
      zipkin:
        endpoint: http://localhost:9411/api/v2/spans # Endpoint V2 de Zipkin
      logging: # Útil para depuración local
        enabled: true # Para ver las trazas en los logs de la consola

4. 🚀 Visualización de Trazas en la UI de Zipkin

  1. Acceder a la UI: http://localhost:9411
  2. Buscar Trazas:
    • Service Name: Filtra por el nombre de la aplicación (definido en spring.application.name).
    • Span Name: Filtra por el nombre de una operación (ej. GET /api/users).
    • Min Duration / Max Duration: Filtra por la duración de la traza.
    • Limit: Número máximo de trazas a mostrar.
    • Annotation Query: Buscar trazas con anotaciones/tags específicos (ej. error o http.status_code=500).
  3. Visualizar Detalles de la Traza:
    • Al seleccionar una traza, verás un gráfico de Gantt mostrando todos los Spans, su duración, y su relación jerárquica.
    • Haz clic en un Span para ver sus detalles (tags, logs de eventos, duración).

5. 📝 Envío de Spans a Zipkin (Protocolos)

Zipkin soporta varios protocolos para enviar Spans desde los servicios instrumentados a su Colector:

6. 🌐 Integración con Otros Componentes

7. 💡 Buenas Prácticas y Consejos

Este cheatsheet te proporciona una referencia completa de Zipkin, cubriendo sus conceptos esenciales de trazabilidad distribuida, cómo instalar el servidor, instrumentar aplicaciones Spring Boot con Micrometer Tracing, visualizar trazas y aplicar las mejores prácticas para un monitoreo y depuración eficientes en arquitecturas de microservicios.