Despliegue de Sig

Configuración de SigNoz y aplicaciones

Después de una instalación exitosa de SigNoz, es necesario configurar el acceso al mismo y comenzar a enviar datos desde sus aplicaciones. También aseguraremos una conexión segura a la interfaz de usuario de SigNoz a través de HTTPS.

1. Acceso inicial a la interfaz de usuario de SigNoz

Por defecto, la interfaz de usuario de SigNoz está disponible en la dirección http://SU_DIRECCIÓN_IP:3301. Ábrala en su navegador. Al iniciar sesión por primera vez, se le pedirá que cree una cuenta de administrador. Establezca un nombre de usuario y una contraseña segura.

2. Configuración de HTTPS con Caddy

El uso de HTTP para acceder al panel de monitoreo es altamente indeseable. Configuraremos Caddy — un servidor web fácil de usar con emisión y renovación automática de certificados TLS de Let's Encrypt — para proporcionar acceso HTTPS.

Pasos preliminares:

1. Asegúrese de que su dominio (por ejemplo, signoz.yourdomain.com) apunte a la dirección IP de su VPS.
2. Asegúrese de que los puertos 80 (HTTP) y 443 (HTTPS) estén abiertos en su UFW (ya los abrimos en la sección "Preparación del servidor").

Instalación de Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y # Instalación de Caddy

Configuración de Caddyfile:

Cree o edite el archivo /etc/caddy/Caddyfile. Reemplace signoz.yourdomain.com con su dominio real.

# /etc/caddy/Caddyfile
signoz.yourdomain.com {
    # Emisión y renovación automática de certificados TLS
    tls {
        # Use su correo electrónico para notificaciones de Let's Encrypt
        email [email protected]
    }

    # Proxy de todas las solicitudes al Frontend de SigNoz
    reverse_proxy localhost:3301 {
        # Adición de los encabezados necesarios para un funcionamiento correcto
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
    }

    # Habilitar compresión (opcional, pero recomendado)
    encode gzip zstd

    # Registro de acceso (opcional)
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

Cree un directorio para los logs de Caddy:

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

Reinicio de Caddy:

sudo caddy validate -adapter caddyfile --config /etc/caddy/Caddyfile # Verificación de la configuración
sudo systemctl reload caddy # Recarga de Caddy para aplicar los cambios
sudo systemctl enable caddy # Asegurarse de que Caddy se inicie al arrancar el sistema

Ahora puede acceder a SigNoz en https://signoz.yourdomain.com.

3. Envío de datos a SigNoz usando OpenTelemetry

SigNoz utiliza activamente OpenTelemetry (OTel) — un estándar abierto para la recopilación de telemetría. Para enviar logs, métricas y trazas desde sus aplicaciones, deberá integrar el SDK de OTel en su código o usar el OTel Collector.

Ejemplo para una aplicación Node.js (trazado básico):

Instale los paquetes necesarios de OpenTelemetry:

npm install @opentelemetry/sdk-node @opentelemetry/api @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-otlp-proto-http @opentelemetry/sdk-trace-node

Cree el archivo tracing.js:

// tracing.js
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-otlp-proto-http');

const traceExporter = new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces', // Dirección del OpenTelemetry Collector de SigNoz
});

const sdk = new opentelemetry.NodeSDK({
  serviceName: 'my-node-app',
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start()
  .then(() => console.log('Tracing initialized'))
  .catch((error) => console.error('Error initializing tracing', error));

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.error('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Ejecute su aplicación Node.js con este archivo:

node -r ./tracing.js your-app.js

Para otros lenguajes de programación y para el envío de métricas/logs, el proceso es similar: utilice los SDK y exportadores de OTel correspondientes. El OpenTelemetry Collector en SigNoz escucha por defecto los puertos 4317 (gRPC) y 4318 (HTTP) para trazas, así como 4317/4318 para métricas y 4317 para logs. Al enviar datos desde la aplicación, especifique la dirección localhost:4318 o localhost:4317, ya que el OTel Collector funciona en la misma pila de Docker Compose que la propia aplicación SigNoz.

Para recopilar logs del host o de otros contenedores, se puede configurar un OpenTelemetry Collector separado o utilizar el controlador de logs de Docker que envía los logs a SigNoz.

4. Verificación de la operatividad

Después de configurar las aplicaciones y enviar los datos, acceda a la interfaz de usuario de SigNoz (https://signoz.yourdomain.com). Vaya a las secciones "Traces", "Metrics" o "Logs". Debería ver los datos entrantes. Si no hay datos, verifique:

• Logs de los contenedores de SigNoz: docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs
• Logs de Caddy: sudo journalctl -u caddy.service
• La correcta configuración del SDK de OTel en su aplicación.
• La disponibilidad de puertos entre la aplicación y el OTel Collector de SigNoz.

Resolución de problemas + Preguntas frecuentes

Durante el despliegue y la operación de SigNoz, pueden surgir varios problemas. A continuación, se presentan preguntas típicas y sus soluciones.

1. La interfaz de usuario de SigNoz no está disponible por dirección IP o dominio.

Qué verificar:

• Estado de los contenedores Docker: Asegúrese de que todos los contenedores de SigNoz estén en ejecución.

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml ps

  Todos los servicios deben estar en estado running. Si no es así, verifique los logs del contenedor problemático:

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs signoz-frontend

• Cortafuegos (UFW): Asegúrese de que los puertos 80, 443 (para Caddy) y 3301 (para acceso directo a la UI de SigNoz) estén abiertos.

  sudo ufw status verbose

• Caddy: Si usa Caddy, verifique su estado y logs.

  sudo systemctl status caddy

  sudo journalctl -u caddy.service

  Asegúrese de que su dominio se resuelva correctamente a la dirección IP del servidor.
• Conflictos de puertos: Verifique si otros servicios no están ocupando los puertos 80, 443 o 3301.

  sudo netstat -tulpn | grep -E "80|443|3301"

Cómo solucionar: Reinicie los servicios Docker o Caddy problemáticos. Abra los puertos necesarios en UFW. Corrija el registro DNS para el dominio.

2. No llegan logs, métricas o trazas a SigNoz.

Qué verificar:

• Configuración de OpenTelemetry Collector: Asegúrese de que el OTel Collector en SigNoz esté en ejecución y escuchando los puertos correctos.

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs signoz-otel-collector

• Configuración de la aplicación: Verifique que su aplicación esté configurada correctamente para enviar datos al OTel Collector de SigNoz (normalmente http://localhost:4318 o http://localhost:4317 desde otros contenedores en la misma red de Docker Compose).

  curl -v -X POST http://localhost:4318/v1/traces -d '{"resourceSpans":[]}'

  Esta es una prueba simple de la disponibilidad del endpoint OTLP.
• Disponibilidad de red: Si la aplicación se encuentra en otro host, asegúrese de que su red pueda acceder a los puertos del OTel Collector en su VPS.
• Errores en los logs de la aplicación: Verifique los logs de la aplicación que debería enviar telemetría en busca de errores de exportación de OTel.

Cómo solucionar: Corrija la configuración de la aplicación o del OTel Collector. Verifique la conectividad de red entre los componentes.

3. SigNoz funciona lento o consume muchos recursos.

Qué verificar:

• Recursos del servidor: Verifique la carga de CPU, el uso de RAM y la velocidad del disco en su VPS.

  htop

  df -h

  iostat -x 1 10

• ClickHouse: ClickHouse es el principal consumidor de recursos. Verifique sus logs en busca de errores o advertencias.

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs signoz-clickhouse

• Volumen de datos: Evalúe el volumen de datos entrantes. Es posible que su VPS simplemente no pueda manejar la carga actual.

Cómo solucionar: Aumente los recursos del VPS (CPU, RAM, NVMe SSD). Optimice las aplicaciones para reducir el volumen de telemetría enviada (por ejemplo, muestreo de trazas). Configure la política de retención de datos en SigNoz para la eliminación automática de datos antiguos.

4. ¿Qué configuración mínima de VPS es adecuada?

Para fines de prueba o proyectos muy pequeños (1-2 aplicaciones, bajo volumen de datos), se puede empezar con 2 CPU, 4 GB de RAM y 100 GB de NVMe SSD. Sin embargo, para cualquier operación seria, incluso para equipos pequeños, se recomienda un mínimo de 4 CPU, 8-16 GB de RAM y 200 GB de NVMe SSD para un funcionamiento estable y la capacidad de almacenar datos durante varias semanas.

5. ¿Qué elegir: VPS o dedicado para esta tarea?

La elección entre un VPS y un servidor dedicado depende de la escala y los requisitos de rendimiento. Un VPS es adecuado para la mayoría de los proyectos medianos (hasta 10-20 servicios, varios cientos de GB de datos al mes) debido a su flexibilidad y costo. Un servidor dedicado es necesario para instalaciones grandes, donde se procesan terabytes de datos, se requiere el máximo rendimiento de ClickHouse, almacenamiento a largo plazo o requisitos estrictos de aislamiento de recursos. Si tiene dudas, comience con un VPS y escale a un servidor dedicado a medida que crezcan sus necesidades.

6. ¿Cómo actualizar SigNoz a una nueva versión?

Para actualizar SigNoz, ejecute los siguientes comandos en el directorio ~/signoz/signoz/deploy/:

git pull                       # Obtener los últimos cambios del repositorio de SigNoz
docker compose -f docker-compose.yaml pull # Descargar nuevas versiones de imágenes Docker
docker compose -f docker-compose.yaml up -d # Recrear contenedores con las nuevas imágenes
docker image prune -f          # Limpiar imágenes Docker antiguas no utilizadas

Siempre consulte la documentación oficial de SigNoz para obtener instrucciones de actualización específicas para una versión concreta, ya que a veces pueden ser necesarios pasos adicionales.