SigNoz en VPS: APM open source en 15 minutos

Las herramientas SaaS de observabilidad tienen un modelo de precios temible: gratis hasta un puñado de hosts y, después, la factura se dispara con cada servicio añadido. Para una agencia web que gestiona diez proyectos de clientes o un desarrollador independiente que escala su SaaS, la cuenta mensual supera rápidamente los 200 a 500 € sin que el valor añadido sea proporcional.

SigNoz cambia las reglas del juego. Es una plataforma de observabilidad open source (licencia Apache 2.0) que se apoya en ClickHouse para el almacenamiento de alto rendimiento de las trazas y las métricas, y en el protocolo OpenTelemetry para la instrumentación. Sus datos se quedan en su casa, usted controla la retención y solo paga el VPS que hace funcionar la stack.

SigNoz se apoya en ClickHouse, un motor de base de datos columnar muy exigente en memoria. El mínimo absoluto recomendado es 4 GB de RAM — por debajo, el OOM killer del kernel mata ClickHouse antes incluso de que se cargue la UI. Para un uso en producción con varias aplicaciones instrumentadas, apunte a 8 GB.

Esta es la lista completa de requisitos previos:
- Un VPS con Ubuntu 22.04 o Debian 12.
- Docker Engine ≥ 24 y Docker Compose V2 instalados.
- El puerto 8080 abierto en su cortafuegos (UI de SigNoz).
- Los puertos 4317 (OTLP/gRPC) y 4318 (OTLP/HTTP) abiertos para recibir las trazas.
- Un acceso root o sudo en el VPS.
- Al menos 20 GB de espacio libre en disco para ClickHouse y sus archivos de datos.

SigNoz recibe las trazas mediante el protocolo OTLP. Así es como se conectan tres entornos comunes.

Node.js (Express/Fastify):

npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

OTEL_EXPORTER_OTLP_ENDPOINT="http://<IP_VPS>:4318" \
OTEL_SERVICE_NAME="my-api" \
node -r ./tracing.js app.js

Python (FastAPI/Flask):

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

OTEL_EXPORTER_OTLP_ENDPOINT="http://<IP_VPS>:4318" \
OTEL_SERVICE_NAME="my-python-service" \
opentelemetry-instrument uvicorn main:app

Go — spans manuales:

go get go.opentelemetry.io/otel \
       go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
       go.opentelemetry.io/otel/sdk/trace

Inicialice el trazador en su main.go y cree spans alrededor de las operaciones críticas:

tracer := otel.Tracer("my-go-service")
ctx, span := tracer.Start(ctx, "fetch-user-details")
defer span.End()
span.SetAttributes(attribute.String("user.id", userID))

En los tres casos, las trazas aparecen en la interfaz de SigNoz bajo Services en los segundos siguientes a la primera llamada HTTP.

En un VPS con disco limitado, la retención predeterminada de SigNoz (3 días para trazas, 30 días para métricas) puede llenar el disco en pocas semanas.

Ajustar la retención desde la UI: vaya a Settings → Retention Period para establecer duraciones distintas para trazas, métricas y logs. Para una agencia que gestiona varios proyectos, 7 días de trazas y 90 días de métricas es un buen equilibrio.

TTL de ClickHouse con volumen frío:

Si su VPS dispone de un segundo volumen más económico montado en /mnt/cold, puede configurar ClickHouse para mover los datos más antiguos automáticamente:

<storage_configuration>
  <disks>
    <default/>
    <cold_disk>
      <type>local</type>
      <path>/mnt/cold/clickhouse/</path>
    </cold_disk>
  </disks>
  <policies>
    <tiered>
      <volumes>
        <hot><disk>default</disk></hot>
        <cold><disk>cold_disk</disk></cold>
      </volumes>
    </tiered>
  </policies>
</storage_configuration>

Luego aplique la política TTL sobre la tabla de trazas de SigNoz:

ALTER TABLE signoz_traces.distributed_signoz_index_v2
  MODIFY TTL toDateTime(timestamp) + INTERVAL 7 DAY
  TO VOLUME 'cold',
  toDateTime(timestamp) + INTERVAL 30 DAY DELETE;

Una vez instrumentadas sus aplicaciones, SigNoz rellena automáticamente la vista Services con la latencia P50/P99, la tasa de error y el rendimiento de cada servicio. Puede crear alertas sobre cualquiera de estas señales.

Alerta sobre la latencia P99:
1. Vaya a Alerts → New Alert Rule.
2. Elija el tipo Metric Based Alert.
3. Introduzca la condición: p99(signoz_latency_bucket{service_name="my-api"}) > 500 (alerta si P99 > 500 ms).
4. Configure el canal de notificación: Slack, email o webhook.

Alerta sobre la tasa de error:
Use la condición rate(signoz_calls_total{service_name="my-api",status_code="STATUS_CODE_ERROR"}[5m]) > 0.05 para disparar una alerta cuando más del 5 % de las llamadas fallen en 5 minutos.

Detección de anomalía (alerta sobre variación repentina):
SigNoz soporta reglas de alerta de tipo Anomaly (pestaña dedicada en la creación de reglas): defina una ventana de referencia (por ejemplo, 7 días) y un umbral de desviación aceptable. Cualquier desviación inusual en el rendimiento o la latencia dispara la alerta — útil para detectar degradaciones lentas que los umbrales fijos no capturan.

Crear un dashboard personalizado:
1. Vaya a Dashboards → New Dashboard.
2. Añada un panel de tipo Time Series y seleccione una métrica Prometheus.
3. Aplique filtros por servicio, entorno o endpoint.

SigNoz en modo standalone gestiona sin esfuerzo hasta una decena de servicios instrumentados que generan unos pocos miles de spans por segundo.

Cuándo considerar el paso a cluster:
- Su VPS alcanza regularmente el 80% de uso de CPU en el proceso ClickHouse.
- El volumen de trazas supera 5 000 spans/s en pico sostenido.
- Necesita alta disponibilidad con cero tiempo de inactividad durante las actualizaciones.

Escalado vertical primero: antes de distribuir, duplique la RAM del VPS. ClickHouse está diseñado para aprovechar mucha memoria; pasar de 8 a 16 GB RAM suele trasladar el cuello de botella de la CPU a la red.

Escalado horizontal: SigNoz proporciona charts Helm para un despliegue Kubernetes con ClickHouse distribuido. En un VPS, la opción más sencilla es un segundo VPS dedicado a ClickHouse, conectado al primero por red privada.

La UI no se carga en el puerto 8080
Compruebe que el contenedor signoz-frontend está en estado running y que su cortafuegos autoriza el puerto:

docker compose ps | grep frontend
ufw status | grep 8080

Las trazas no aparecen en la interfaz
La causa más frecuente es una variable OTEL_EXPORTER_OTLP_ENDPOINT incorrecta. Verifique que:
- la URL apunta a la IP pública del VPS, no a localhost;
- el puerto es 4318 para OTLP/HTTP (o 4317 para gRPC);
- ningún cortafuegos bloquea ese puerto entre su aplicación y el VPS.

Test rápido desde el servidor de la aplicación:

curl -v http://<IP_VPS>:4318

Una respuesta 405 Method Not Allowed confirma que el collector escucha correctamente.

ClickHouse OOM — contenedor en bucle de reinicio
Consulte dmesg | grep -i oom para confirmar el kill. Si la RAM es insuficiente, limite el uso de memoria de ClickHouse:

echo '<max_memory_usage>2000000000</max_memory_usage>' \
  >> /etc/clickhouse-server/users.xml
docker compose restart clickhouse

Timeout de arranque de SigNoz
Si docker compose ps muestra el contenedor signoz en starting durante más de 5 minutos, ClickHouse no está listo todavía. SigNoz espera una respuesta de ClickHouse antes de inicializarse. Compruebe los logs del contenedor ClickHouse:

docker compose logs clickhouse --tail=50

Un disco lleno o permisos insuficientes sobre el volumen de datos son las causas más comunes de este bloqueo.

Error connection refused desde la aplicación
Asegúrese de que los puertos 4317 o 4318 están abiertos en el cortafuegos del VPS SigNoz, y de que la URL en OTEL_EXPORTER_OTLP_ENDPOINT apunta a la IP pública del VPS, no a localhost.