Grafana Tempo y OpenTelemetry: trazado distribuido en VPS

OpenTelemetry es un proyecto graduado de CNCF que unifica los tres pilares de la observabilidad — trazas, métricas y logs — bajo un estándar neutral al proveedor. A diferencia de los agentes Datadog o New Relic que te encierran en un contrato y formato propietario, el OTel Collector recibe, transforma y exporta la telemetría a cualquier backend compatible. Puedes cambiar de almacenamiento sin tocar una sola línea de tu código.

Los SDKs cubren Node.js, Python, Go, Java, PHP, Ruby y la mayoría de los lenguajes modernos. Los propagadores de contexto W3C TraceContext y B3 están incluidos: transmiten automáticamente el trace-id entre tus microservicios vía headers HTTP, sin configuración adicional.

Tu VPS necesita al menos 2 GB de RAM (4 GB recomendados en producción) y acceso root o sudo. Docker Engine ≥ 24 y Docker Compose v2 deben estar instalados.

Planifica un subdominio dedicado — por ejemplo grafana.tu-dominio.com — para exponer la interfaz Grafana detrás de un proxy inverso TLS. Los puertos 4317 (OTLP/gRPC) y 4318 (OTLP/HTTP) deben estar abiertos en tu firewall en el lado privado para recibir telemetría desde tus aplicaciones; no los expongas en la interfaz pública. Los puertos 3200 (Tempo) y 3000 (Grafana) permanecen internos a la red Docker.

Planifica al menos 10 GB libres para los bloques de trazas. El montaje por defecto en /tmp/tempo no sobrevive a los reinicios: reemplázalo con un volumen Docker o un disco dedicado antes de ir a producción.

El flujo de datos sigue cuatro pasos:

1. Tu aplicación instrumenta sus peticiones con un SDK OTel y exporta spans al OTel Collector (OTLP gRPC puerto 4317 o HTTP puerto 4318).
2. El OTel Collector recibe, agrupa en lotes y exporta a Tempo vía OTLP gRPC interno. Puede enviar simultáneamente métricas a Prometheus y logs a Loki.
3. Grafana Tempo almacena bloques de trazas comprimidos en disco (o S3). Expone una API TraceQL en el puerto 3200.
4. Grafana consulta Tempo con TraceQL, muestra flamegraphs, grafos de servicios y span metrics.

TraceQL es el lenguaje de consulta nativo de Tempo: {service.name="api" && status=error && duration>500ms}.

Span Metrics es un pipeline de Tempo que deriva automáticamente métricas RED de las trazas entrantes, sin añadir un solo contador a tu código.

Tempo ofrece dos opciones principales de almacenamiento.

Almacenamiento local en volumen Docker: recomendado para un VPS standalone. Ajusta block_retention en tempo.yaml: 72 h para staging, 168 a 720 h para producción. Cada hora de trazas comprimidas ocupa aproximadamente 100–300 MB.

Almacenamiento de objetos compatible con S3: para un stack multi-nodo o almacenamiento ilimitado. Tempo es compatible con AWS S3, MinIO, Scaleway Object Storage y cualquier backend con API S3. La WAL siempre permanece en disco local para garantizar la durabilidad de las trazas en vuelo.

El compactor de Tempo fusiona bloques pequeños y aplica la política de retención automáticamente cada 5 minutos.

La auto-instrumentación OTel para Node.js captura automáticamente llamadas HTTP salientes, peticiones Express/Fastify, consultas a bases de datos y más, sin modificar tu lógica de negocio.

Instala los paquetes:

npm install @opentelemetry/sdk-node \
             @opentelemetry/auto-instrumentations-node \
             @opentelemetry/exporter-trace-otlp-grpc

Crea tracing.js:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'grpc://localhost:4317',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Inicia tu aplicación:

export OTEL_SERVICE_NAME=mi-api
export OTEL_EXPORTER_OTLP_ENDPOINT=http://tu-vps:4317
node --require ./tracing.js app.js

Instala y bootstrap:

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

Inicia tu aplicación:

export OTEL_SERVICE_NAME=mi-servicio-python
export OTEL_EXPORTER_OTLP_ENDPOINT=http://tu-vps:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
opentelemetry-instrument python app.py

Django, Flask, FastAPI, SQLAlchemy y los clientes HTTP se instrumentan automáticamente. Para instrumentación manual:

from opentelemetry import trace
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("procesar-pedido") as span:
    span.set_attribute("pedido.id", pedido_id)

Grafana 10+ permite definir alertas directamente sobre métricas derivadas de trazas. Las Span Metrics de Tempo generan automáticamente tres métricas por servicio: tasa de peticiones, histograma de latencia y contador de errores.

Para crear un SLO sobre la tasa de error de tu API, ve a Alerting → Alert rules → New alert rule en Grafana, elige la fuente de datos Prometheus e introduce una consulta que calcule la proporción de errores. Define el umbral (por ejemplo > 0.05 para una tasa de error superior al 5%) y la ventana de evaluación. Configura un punto de contacto: Alertmanager, PagerDuty, Slack o webhook. Las alertas basadas en trazas son mucho más precisas que las alertas sobre métricas sintéticas.

No llegan spans a Tempo. Comprueba primero que el OTel Collector es accesible desde tu aplicación (telnet tu-vps 4317). Revisa los logs del Collector: un error connection refused en tempo:4317 indica que Tempo no ha arrancado o su puerto interno no está expuesto en la red Docker.

Conexión rechazada desde la aplicación al Collector. En UFW o firewalld, permite los puertos 4317 y 4318 solo para las IPs de tus aplicaciones. En producción, aplicaciones y Collector deben estar en la misma red privada.

Trazas truncadas o spans faltantes. El batch processor puede tardar hasta 5 s en enviar. Para desarrollo, reduce timeout: 1s. Si los spans faltan sistemáticamente, verifica que el propagador de contexto W3CTraceContextPropagator está activo en tu SDK.

Tempo consume demasiado espacio en disco. Reduce block_retention y reinicia Tempo. El compactor aplicará la nueva política en el siguiente ciclo.

Grafana no encuentra trazas desde los logs de Loki. Verifica que tus aplicaciones inyectan trace_id en sus logs y que el campo Derived fields en la fuente de datos Loki apunta al patrón correcto.