StackPractices
advanced Por Mathias Paulenko

Guía Completa de Observabilidad con el Stack de Grafana

Monta el stack completo de observabilidad de Grafana: Prometheus, Loki, Tempo, Alloy y Grafana con un solo docker-compose, correlación de señales y alertado por SLO.

Introducción

Son las 3 de la mañana, un deploy acaba de romper el checkout, y la evidencia que necesitás está repartida en tres sitios: un pico de latencia en Prometheus, un error en Loki, una traza en Tempo. Si esas señales no comparten labels e IDs, estás copiando trace IDs a mano en una barra de búsqueda — mientras el error budget se quema.

Esta guía es para desarrolladores backend y SRE que levantan el stack completo de Grafana — el stack LGTM (Loki, Grafana, Tempo, Metrics) — autoalojado con Docker Compose. Obtendrás un único docker-compose.yml con los seis servicios, instrumentación funcional con OpenTelemetry, datasources y dashboards aprovisionados y correlación de señales que de verdad resuelve. Prerequisitos: Docker Compose y al menos un servicio HTTP que instrumentar. Si desplegás en Kubernetes las configs aplican igual, pero la capa de aprovisionamiento cambia a Helm/Operator.

Cuándo usarlo (y cuándo no)

Tu situaciónRecomendación
Microservicios (>3) con guardia realLGTM autoalojado — control total, los datos quedan en tu infra
Equipo pequeño, sin capacidad de opsFree tier de Grafana Cloud (10k métricas, 50GB de logs) — salteate el self-hosting
Experimentación local rápidaImagen all-in-one grafana/otel-lgtm — todo el stack en un contenedor
Monolito, poco tráficoPrometheus + Grafana solos — Loki/Tempo suman coste real de memoria y storage
Escala de producción / retención largaEste compose es el punto de partida — planificá S3, Mimir y Loki/Tempo multinodo antes de llamarlo producción

El resto de la guía construye la opción del medio: LGTM autoalojado completo para equipos que son dueños de su observabilidad.

El stack de un vistazo

flowchart diagram: APP[

Cada señal responde una pregunta distinta:

PilarHerramientaQué pregunta responde
MétricasPrometheus”¿Está roto?” — números agregados en el tiempo
LogsLoki”¿Qué pasó?” — detalle de eventos, buscable
TrazasTempo”¿Dónde está roto?” — causalidad por request
VisualizaciónGrafanaUnifica las tres en dashboards y correlación
RecolecciónAlloyEnvía logs a Loki (reemplaza al Promtail EOL)
AlertadoAlertmanagerEnruta las alertas de Prometheus a humanos

Algo que muerde a todo equipo: unificá los nombres de labels desde el día uno (service, environment, version). La correlación entre señales solo funciona cuando service="checkout" significa lo mismo en métricas, logs y trazas.

Docker Compose unificado

Los seis servicios abajo son un solo archivo — la pieza que la mayoría de los tutoriales separa. Un único compose con todos los servicios, volúmenes compartidos y los puertos que vas a tocar:

# docker-compose.yml — stack LGTM completo en un archivo
services:
  prometheus:
    image: prom/prometheus:latest
    ports: ["9090:9090"]
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - ./alert_rules.yml:/etc/prometheus/alert_rules.yml
      - prometheus-data:/prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.retention.time=15d"

  loki:
    image: grafana/loki:latest
    ports: ["3100:3100"]
    volumes:
      - loki-data:/loki
    command: -config.file=/etc/loki/local-config.yaml

  alloy:
    image: grafana/alloy:latest
    volumes:
      - ./alloy/config.alloy:/etc/alloy/config.alloy
      - /var/run/docker.sock:/var/run/docker.sock:ro   # necesario para el discovery de docker
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
    command: ["run", "--server.http.listen-addr=0.0.0.0:12345", "/etc/alloy/config.alloy"]

  tempo:
    image: grafana/tempo:latest
    ports: ["3200:3200", "4318:4318"]
    volumes:
      - ./tempo.yaml:/etc/tempo.yaml
      - tempo-data:/tmp/tempo

  grafana:
    image: grafana/grafana:latest
    ports: ["3000:3000"]
    environment:
      - GF_AUTH_ANONYMOUS_ENABLED=true   # solo dev — quitar en entornos reales
    volumes:
      - ./grafana/provisioning:/etc/grafana/provisioning
      - ./grafana/dashboards:/var/lib/grafana/dashboards
      - grafana-data:/var/lib/grafana

  alertmanager:
    image: prom/alertmanager:latest
    ports: ["9093:9093"]
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml

volumes:
  prometheus-data:
  loki-data:
  tempo-data:
  grafana-data:

En producción cambiarías latest por versiones fijadas y desactivarías el acceso anónimo, pero esto levanta el pipeline completo.

Prometheus: métricas

Prometheus es el almacén de métricas: extrae (scrape) los endpoints /metrics en intervalos, guarda series temporales y evalúa reglas de alerta. Todo lo dirige prometheus.yml:

# prometheus.yml — config de scrape
global:
  scrape_interval: 15s

alerting:
  alertmanagers:
    - static_configs:
        - targets: ["alertmanager:9093"]

rule_files:
  - alert_rules.yml

scrape_configs:
  - job_name: "services"
    metrics_path: "/metrics"
    static_configs:
      - targets: ["app:8080"]           # tus servicios instrumentados
        labels:
          environment: "production"
  - job_name: "node-exporter"           # CPU/disco del host para el método USE
    static_configs:
      - targets: ["node-exporter:9100"]

Instrumentar una app es exponer /metrics con una librería cliente: prometheus_client para Python, prom-client para Node, el registro Prometheus de Micrometer para Java. La receta del exporter (python-prometheus-metrics-exporter) cubre el código; el hábito clave es counters con labels, no counters por endpoint — un label en un counter es una serie; un nombre de métrica nuevo por endpoint es una bomba de cardinalidad.

Dos formas de PromQL para memorizar — la segunda es la que los tutoriales suelen tener mal:

# Tasa de error por servicio en 5m
sum(rate(http_requests_total{status=~"5.."}[5m])) by (service)

# Latencia p95 por endpoint — el by va en el sum, no en histogram_quantile
histogram_quantile(0.95, sum by (endpoint, le) (rate(http_request_duration_seconds_bucket[5m])))

histogram_quantile es una función, no un agregador: hay que hacer sum by (…, le) dentro, conservando el label le, o el cálculo del percentil sale mal.

Loki + Alloy: logs

Loki es el almacén de logs — indexa solo los labels (no el contenido del log), y por eso es barato de operar: el volumen de logs cuesta storage, no índice. Promtail era su colector, pero Promtail llegó a fin de vida el 2 de marzo de 2026; su reemplazo es Grafana Alloy — el mismo colector basado en OTel que además envía métricas y trazas.

La config de Alloy que reemplaza a promtail.yml — descubre contenedores Docker y envía a Loki:

// alloy/config.alloy — descubre contenedores docker, reenvía logs a Loki
discovery.docker "linux" {
  host = "unix:///var/run/docker.sock"
}

discovery.relabel "logs" {
  targets = discovery.docker.linux.targets
  rule {
    source_labels = ["__meta_docker_container_name"]
    regex         = "/(.*)"
    target_label  = "service"          // quita la / inicial y deja el label consistente con las métricas
  }
}

loki.source.docker "default" {
  host             = "unix:///var/run/docker.sock"
  targets          = discovery.relabel.logs.targets
  relabel_rules    = discovery.relabel.logs.rules
  forward_to       = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint { url = "http://loki:3100/loki/api/v1/push" }
}

Dos detalles que rompen la recolección de logs en silencio: el contenedor de Alloy debe montar /var/run/docker.sock (está en el compose de arriba), y __meta_docker_container_name incluye una / inicial — quitála con la regla regex: "/(.*)" o tu label service no coincidirá con el de las métricas.

Consultá Loki con LogQL desde Explore en Grafana:

# logs de error de un servicio
{service="checkout"} |= "error"

# tasa de logs de error por minuto
sum(rate({service="checkout"} |= "error" [5m]))

# logs JSON — parsea campos, filtra por level, extrae trace_id
{service="checkout"} | json | level="error" | line_format "{{.msg}} trace={{.trace_id}}"

Escribí logs JSON con trace_id — es el campo que hace funcionar la correlación traza→logs después.

Tempo: trazas

Tempo es el almacén de trazas — recibe spans OTLP, indexa solo por trace ID y los guarda barato. tempo.yaml declara los receivers (OTLP + Jaeger legacy para migraciones):

# tempo.yaml — receivers y storage local
server:
  http_listen_port: 3200

distributor:
  receivers:
    otlp:
      protocols:
        http:
        grpc:
    jaeger:
      protocols:
        thrift_http:

storage:
  trace:
    backend: local
    local:
      path: /tmp/tempo/blocks
    wal:
      path: /tmp/tempo/wal

Tus apps envían spans por OpenTelemetry a http://tempo:4318/v1/traces. Un servicio Flask se ve así:

# otel_tracing.py — Flask + exporter OTLP HTTP
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.instrumentation.flask import FlaskInstrumentor

resource = Resource.create({"service.name": "checkout", "service.version": "1.4.2"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://tempo:4318/v1/traces"))
)
trace.set_tracer_provider(provider)

FlaskInstrumentor().instrument_app(app)  # service.name debe coincidir con el label de métricas/logs

El atributo service.name es tu clave de correlación — mismo valor que el label service en Prometheus y Alloy.

Grafana: capa de unificación

Grafana es donde las tres fuentes se encuentran. Aprovisioná todo como código — datasources y dashboards cargan al arranque, versionados en Git:

# grafana/provisioning/datasources/datasources.yml
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    uid: prometheus             # uid explícito — la config de correlación lo referencia
  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100
    uid: loki
  - name: Tempo
    type: tempo
    access: proxy
    url: http://tempo:3200
    uid: tempo
    jsonData:
      tracesToLogsV2:           # el legacy tracesToLogs necesita que el datasourceUid exista
        datasourceUid: loki
        spanStartTimeShift: "-1h"
        spanEndTimeShift: "1h"
        filterByTraceID: true
      tracesToMetrics:
        datasourceUid: prometheus
        tags: [{ key: "service.name", value: "service" }]

Sin uid explícitos, la correlación se rompe en silencio — Grafana genera UIDs aleatorios y tracesToLogsV2.datasourceUid: loki no resuelve a nada.

# grafana/provisioning/dashboards/dashboards.yml — carga dashboards desde disco
apiVersion: 1
providers:
  - name: "default"
    folder: ""
    type: file
    options:
      path: /var/lib/grafana/dashboards

Un JSON de dashboard aprovisionable necesita uid, schemaVersion y gridPos por panel — la forma mínima que Grafana acepta al importar. Armalo en la UI, exportalo y metelo en grafana/dashboards/.

Alertado

Prometheus evalúa reglas y dispara a Alertmanager, que agrupa, deduplica y enruta. Alertá sobre síntomas que el usuario siente (tasa de error, SLO de latencia), no sobre causas (CPU, disco) — las causas van a los dashboards.

# alert_rules.yml — alertas de tasa de error + burn rate
groups:
  - name: api
    rules:
      - alert: HighErrorRate
        expr: sum(rate(http_requests_total{status=~"5.."}[5m])) by (service)
              / sum(rate(http_requests_total[5m])) by (service) > 0.05
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Tasa de error >5% en {{ $labels.service }}"

      - alert: FastErrorBudgetBurn        # 2% del presupuesto quemado en 1h con SLO 99.9%
        expr: sum(rate(http_requests_total{status=~"5.."}[1h])) by (service)
              / sum(rate(http_requests_total[1h])) by (service) > 0.05 * (1 - 0.999) * 14.4 / 0.0005
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Quema rápida del error budget en {{ $labels.service }}"
# alertmanager.yml — warnings a Slack, críticos a guardia
route:
  receiver: slack
  group_by: ["service", "severity"]
  group_wait: 30s
  repeat_interval: 4h
  routes:
    - match: {severity: critical}
      receiver: pagerduty
receivers:
  - name: slack
    slack_configs:
      - api_url: "https://hooks.slack.com/services/XXX"   # tu webhook
        channel: "#alerts"
  - name: pagerduty
    pagerduty_configs:
      - service_key: "XXX"

Probá las reglas antes de que te despierten — promtool test rules alert_rules.yml las corre contra fixtures en local.

Escalado a producción

El compose de arriba es una base sólida de dev/producción chica, pero tres costuras lo separan de producción real:

  • Object storage: Loki y Tempo están diseñados para S3/GCS/Azure Blob, no para disco local. Mover storage.trace.backend y el storage_config de Loki a object storage elimina tu mayor restricción de retención — los volúmenes locales se llenan y fuerzan borrado.
  • Métricas a largo plazo: el TSDB local de Prometheus está pensado para 15 días. Para retención mayor o queries multi-cluster, el mismo ecosistema ofrece Mimir (el almacén Prometheus de largo plazo de Grafana) o Thanos — el PromQL es idéntico, cambia el backend.
  • Capa de ingesta: poner un OpenTelemetry Collector entre tus apps y Tempo (apps → Collector → Tempo) te da tail sampling — “guardá solo trazas con errores o latencia p99” en vez de guardar todo. Eso hace al storage de trazas asequible a volumen; el sampling a nivel app conserva el 100% del ruido.

En Kubernetes aplica el mismo modelo mental — cambiarías el compose por el Helm chart lgtm-distributed o por los charts individuales por componente, y docker_sd por kubernetes_sd_configs.

Una nota sobre la estrategia de sampling mientras escalás: head sampling (decidir en la app, antes de que termine el span) es barato pero tira justo las trazas que querés — las lentas y las con error. Tail sampling (decidir en el Collector, cuando la traza completa) cuesta más memoria porque buffera trazas, pero te permite guardar el 100% de errores y un porcentaje chico del tráfico aburrido. La mayoría de los equipos arranca con “guardá siempre trazas con error + ~10% del resto” y ajusta desde ahí.

La config del Collector que hace eso — las apps apuntan su exporter OTLP al Collector en vez de a Tempo directamente:

# otel-collector-config.yaml — tail sampling: errores + 10% del resto
receivers:
  otlp:
    protocols:
      http:
      grpc:

processors:
  tail_sampling:
    decision_wait: 10s
    policies:
      - name: keep-errors
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: keep-slow
        type: latency
        latency: { threshold_ms: 2000 }
      - name: keep-10-percent
        type: probabilistic
        probabilistic: { sampling_percentage: 10 }

exporters:
  otlphttp:
    endpoint: http://tempo:4318/v1/traces

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [tail_sampling]
      exporters: [otlphttp]

Las políticas se evalúan con OR — una traza que cumpla cualquier política se reenvía. Por eso los errores y las trazas lentas siempre sobreviven mientras solo una fracción del tráfico sano llega al storage.

Observabilidad guiada por SLO

El beneficio real del stack: alertas atadas a objetivos, no a conjeturas. Tres términos que se confunden:

TérminoQué esEjemplo
SLIService Level Indicator — la métrica en síp99 latencia < 300ms
SLOService Level Objective — objetivo en una ventana99.9% de requests < 300ms en 30 días
SLAEl compromiso contractual (normalmente más laxo que el SLO)99.5% con penalidades

El error budget es lo que el SLO te permite gastar: un SLO de 99.9% de disponibilidad son 0.1% de fallos = ~43 min/mes de caída permitida. Quemalo lento y seguís deployando funcionalidades; quemalo rápido (la alerta FastErrorBudgetBurn de arriba) y congelás deploys para trabajar en fiabilidad. Ese trade-off es la diferencia entre observabilidad como decoración y observabilidad como sistema operativo para los deploys.

Para la plantilla del documento SLO y la política de alertado que la acompaña, mirá la plantilla de SLO y la guía de monitorización y alertado.

Correlación de señales

La correlación es el punto central: un usuario reporta “falla el checkout” y vos querés métrica → traza → log en tres clics, no en tres búsquedas:

  1. Métrica → traza: los exemplars en los histogramas enlazan puntos de p99 a un trace_id concreto (activá tracesToMetrics + storage de exemplars en Prometheus).
  2. Traza → log: tracesToLogsV2 en el datasource de Tempo filtra Loki por service=X + trace_id=Y — funciona porque tus logs JSON llevan trace_id y el label está unificado.
  3. Log → traza: los derived fields del datasource de Loki convierten un trace_id en una línea de log en un link clickeable a Tempo.

Ese último tramo necesita una config que nadie incluye — derivedFields en el datasource de Loki:

  - name: Loki
    type: loki
    url: http://loki:3100
    uid: loki
    jsonData:
      derivedFields:
        - name: TraceID
          matcherRegex: '"trace_id":\\s*"([a-f0-9]+)"'   # regex con un grupo de captura = el trace id
          url: "$${__value.raw}"                        # $$ escapa la interpolación del provisioning
          datasourceUid: tempo                          # a dónde salta el link

Cada campo solo extrae cuando captura un grupo — si la regex está mal no hay error, el botón simplemente no aparece.

Esa cadena solo funciona si service significa lo mismo en todos lados — por eso la disciplina de labels es una buena práctica, no un detalle opcional.

Buenas prácticas

  • Instrumentá con OpenTelemetry, no con agentes de vendor — el día que te mudés a un backend gestionado, la instrumentación no cambia.
  • Capá la cardinalidad de labels deliberadamente: una regla útil es mantener cada dimensión por debajo de ~10 valores por métrica y evitar valores sin límite como user_id o request_id — esos van a logs y trazas, no a series temporales.
  • Definí retención por señal, no global: métricas 15d locales + downsample para más tiempo, logs según lo que un incidente real necesita, trazas con sampling — trazas a máxima fidelidad en cada request se encarecen rápido.
  • Mantené los dashboards como código; cada dashboard que alguien edita en la UI y nunca exporta es uno que vas a reconstruir tras una actualización.
  • Alertá sobre burn rate del SLO y síntomas visibles para el usuario; el resto va a dashboards o canales silenciados.

Errores comunes

  • Tratar las tres señales como tres proyectos separados — el valor del stack es la correlación, y la correlación falla por labels inconsistentes antes que por piezas faltantes.
  • Seguir usando Promtail — llegó a EOL en marzo de 2026; migrá a Alloy en vez de fijar un componente muerto.
  • Labels de cardinalidad alta en métricas (user_id, order_id, URLs crudas) — la forma más común de reventar la memoria de Prometheus; revisá prometheus_tsdb_head_series.
  • Alertar sobre causas en vez de síntomas — “CPU > 80%” entrena al equipo a ignorar alertas; “burn rate del error budget” lo entrena a actuar.
  • Sin política de retención ni sampling — las instalaciones ingenuas guardan todo a máxima fidelidad hasta que el storage obliga la conversación en el peor momento.
  • Omitir uid en datasources aprovisionados — las configs de correlación resuelven en silencio a nada.
  • rate() sobre no-counters — rate() sobre un gauge o un histograma crudo produce basura; solo counters.

Ver también

Lecturas adicionales

Preguntas frecuentes

¿Cuál es la diferencia entre métricas, logs y trazas?

Las métricas son números agregados en el tiempo ("la tasa de error es 4%"). Los logs son eventos individuales con detalle ("este request lanzó NullPointerException en la línea 42"). Las trazas siguen un request único entre servicios, mostrando la cadena causal y el tiempo de cada salto. Las métricas detectan, las trazas localizan, los logs explican.

¿Debería usar Promtail o Grafana Alloy?

Alloy. Promtail llegó a fin de vida el 2 de marzo de 2026 — Alloy es su reemplazo y cubre recolección de logs, métricas y trazas en un solo agente. Las configs promtail.yml existentes se traducen a la sintaxis de componentes de Alloy casi 1:1.

¿Cómo correlaciono una traza con sus logs?

Escribí logs JSON incluyendo trace_id, configurá tracesToLogsV2 en el datasource de Tempo con datasourceUid: loki (con un uid explícito en el datasource de Loki) y mantené el label service idéntico en las tres señales. Entonces un span en Grafana tiene un botón "Logs for this span".

¿Cuándo sobra el stack LGTM completo?

Para un monolito o un servicio sin guardia, Prometheus + Grafana alcanza — Loki y Tempo suman coste de storage y operación. Para un equipo sin capacidad de ops, el free tier de Grafana Cloud (10k métricas, 50GB logs) gana contra un stack autoalojado que no podés mantener. Para experimentos locales, la imagen all-in-one grafana/otel-lgtm es el camino más rápido.

¿Cómo sampleo trazas sin perder las importantes?

El head sampling en la app (guardar 1 de cada N trazas) es barato pero descarta las trazas lentas y con error junto a las aburridas — justo las que vas a necesitar en un incidente. El patrón común es un OTel Collector haciendo tail sampling: guardar el 100% de las trazas con errores o sobre un umbral de latencia, más un porcentaje fijo del resto. Cuesta memoria del Collector pero hace viable el storage de trazas a volumen.

¿Cómo controlo la memoria de Prometheus?

Cardinalidad. Cada combinación única de labels es una serie en memoria; labels como user_id, request_id o URL crudas explotan el head block. Mantené los valores acotados, revisá prometheus_tsdb_head_series y descartá métricas de cardinalidad alta con metric_relabel_configs antes de que ingieran.