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ón | Recomendación |
|---|---|
| Microservicios (>3) con guardia real | LGTM autoalojado — control total, los datos quedan en tu infra |
| Equipo pequeño, sin capacidad de ops | Free tier de Grafana Cloud (10k métricas, 50GB de logs) — salteate el self-hosting |
| Experimentación local rápida | Imagen all-in-one grafana/otel-lgtm — todo el stack en un contenedor |
| Monolito, poco tráfico | Prometheus + Grafana solos — Loki/Tempo suman coste real de memoria y storage |
| Escala de producción / retención larga | Este 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
Cada señal responde una pregunta distinta:
| Pilar | Herramienta | Qué pregunta responde |
|---|---|---|
| Métricas | Prometheus | ”¿Está roto?” — números agregados en el tiempo |
| Logs | Loki | ”¿Qué pasó?” — detalle de eventos, buscable |
| Trazas | Tempo | ”¿Dónde está roto?” — causalidad por request |
| Visualización | Grafana | Unifica las tres en dashboards y correlación |
| Recolección | Alloy | Envía logs a Loki (reemplaza al Promtail EOL) |
| Alertado | Alertmanager | Enruta 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.backendy elstorage_configde 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érmino | Qué es | Ejemplo |
|---|---|---|
| SLI | Service Level Indicator — la métrica en sí | p99 latencia < 300ms |
| SLO | Service Level Objective — objetivo en una ventana | 99.9% de requests < 300ms en 30 días |
| SLA | El 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:
- Métrica → traza: los exemplars en los histogramas enlazan puntos de
p99a untrace_idconcreto (activátracesToMetrics+ storage de exemplars en Prometheus). - Traza → log:
tracesToLogsV2en el datasource de Tempo filtra Loki porservice=X+trace_id=Y— funciona porque tus logs JSON llevantrace_idy el label está unificado. - Log → traza: los derived fields del datasource de Loki convierten un
trace_iden 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_idorequest_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
uiden 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
- Guía Completa de Prometheus y Grafana — el pilar de métricas en profundidad: PromQL, exporters, diseño de dashboards
- Guía Completa de Monitorización y Alertado — estrategia de alertado, proceso SLO y el lado de política del stack
- Guía de Distributed Tracing — OpenTelemetry y diseño de trazas en profundidad
- Agregación de Logs — Centralizar, Buscar — alternativas a Loki y diseño de logs centralizados
- Guía de Gestión de Alertas — escalación, runbooks, fatiga de alertas
- Archivos complementarios — docker-compose ejecutable y todas las configs de esta guía
Lecturas adicionales
- Docs del stack LGTM de Grafana — el nombre oficial y la documentación de componentes (Loki, Tempo, Mimir/Prometheus, Grafana)
- Documentación de Grafana Alloy — el reemplazo de Promtail:
discovery.docker,loki.source.docker,loki.write - Prometheus — reglas de alerta y PromQL — la forma correcta de agregación de
histogram_quantiley pruebas de reglas - Documentación de OpenTelemetry — endpoints OTLP, BatchSpanProcessor, resource attributes que dirigen la correlación
- Google SRE Workbook — Alerting on SLOs — la matemática de burn rate detrás de
FastErrorBudgetBurn
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.
Recursos Relacionados
Prometheus y Grafana: métricas, dashboards y alertas
Instrumenta servicios con métricas de Prometheus, consúltalas en PromQL, construye dashboards en Grafana y publica reglas de alerta que no oscilan.
GuideTrazado distribuido: OpenTelemetry, Jaeger y Zipkin
Domina el trazado distribuido con OpenTelemetry, Jaeger y Zipkin. Propagación de trazas entre servicios, contexto de span, estrategias de muestreo y depuración en producción.
PatternPatrón Health Check: Sondeos de Liveness y Readiness
Implementa sondeos de liveness y readiness para orquestadores. Cubre probes en Kubernetes, chequeos de dependencias y degradación elegante.
PatternCircuit Breaker con Monitoring
Cómo exponer circuit breaker state como métricas para observability. Cubre Prometheus integration, reglas de alerting, dashboards y state transitions.
GuideSentry: Triage y Resolución de Errores
Dominá Sentry para el seguimiento de errores en producción. Cubre integración del SDK en Python, Node.js y Java, release tracking, source maps, performance monitoring y alertas.
GuideGuía Completa de Monitoreo y Alertas
Monta un stack de monitoreo en producción con Prometheus, Grafana y AlertManager — métodos RED/USE, alertas que no fatigan y SLOs con error budget.