Instalación de SigNoz APM de Código Abierto

SigNoz es una plataforma de monitoreo de rendimiento de aplicaciones (APM) de código abierto construida sobre OpenTelemetry que unifica trazas distribuidas, métricas y logs en una única interfaz. A diferencia de Jaeger o Zipkin que solo manejan trazas, SigNoz ofrece dashboards de métricas, gestión de logs y correlación entre las tres señales, siendo una alternativa completa a Datadog o New Relic para equipos que prefieren el control sobre sus datos. Esta guía cubre la instalación con Docker, la instrumentación de aplicaciones con OpenTelemetry y el análisis de rendimiento.

Requisitos Previos

  • Ubuntu 20.04/22.04 o CentOS 8+/Rocky Linux 8+
  • Docker 20.10+ y Docker Compose 2.x
  • 8 GB de RAM mínimo (SigNoz incluye ClickHouse como base de datos)
  • 4 vCPUs recomendado
  • 20 GB de espacio en disco
  • Puertos 3301 (UI), 4317 (OTLP gRPC), 4318 (OTLP HTTP)

Instalación con Docker Compose

SigNoz proporciona un script de instalación oficial que configura todos los componentes:

# Clonar el repositorio de SigNoz
git clone -b main https://github.com/SigNoz/signoz.git
cd signoz/deploy/docker/clickhouse-setup

# Revisar la configuración por defecto
cat docker-compose.yaml

# Iniciar SigNoz (incluye ClickHouse, Query Service, Frontend y OTel Collector)
docker compose -f docker-compose.yaml up -d

# Ver el progreso de inicio (puede tardar 3-5 minutos la primera vez)
docker compose -f docker-compose.yaml logs -f frontend

# Verificar que todos los servicios están corriendo
docker compose -f docker-compose.yaml ps

Los componentes que se despliegan:

  • ClickHouse: base de datos columnar para almacenar trazas, métricas y logs
  • ZooKeeper: coordinación del clúster ClickHouse
  • Query Service: backend Go que sirve la API
  • Frontend: interfaz web React
  • OTel Collector: recibe datos de OpenTelemetry de las aplicaciones
  • AlertManager: gestión de alertas

Para un despliegue en producción con almacenamiento persistente:

# Crear directorios de datos antes de iniciar
sudo mkdir -p /data/signoz/clickhouse /data/signoz/zookeeper
sudo chown -R 101:101 /data/signoz/clickhouse  # UID de ClickHouse

# Editar el docker-compose para usar volúmenes en disco
# Modificar los volumes de clickhouse y zookeeper para apuntar a /data/signoz/

Acceso a la Interfaz

Accede a http://tu-ip:3301 en el navegador. En el primer acceso:

  1. Crea la cuenta de administrador con email y contraseña
  2. La pantalla principal muestra los servicios detectados automáticamente
  3. Navega entre Services, Traces, Metrics y Logs en la barra lateral

Instrumentación con OpenTelemetry

OpenTelemetry (OTel) es el estándar abierto para instrumentación. SigNoz actúa como backend para los datos OTel de tus aplicaciones.

El OTel Collector de SigNoz escucha en:

  • tu-ip:4317 para OTLP sobre gRPC
  • tu-ip:4318 para OTLP sobre HTTP

Variables de entorno necesarias en las aplicaciones:

# Configuración base para cualquier aplicación con OTel
OTEL_EXPORTER_OTLP_ENDPOINT=http://tu-ip-signoz:4317
OTEL_RESOURCE_ATTRIBUTES=service.name=mi-servicio,deployment.environment=production
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Instrumentación de Python

# Instalar las dependencias de OpenTelemetry para Python
pip install opentelemetry-distro opentelemetry-exporter-otlp

# Auto-instrumentación: detecta e instrumenta automáticamente las librerías populares
opentelemetry-bootstrap -a install

Para aplicaciones Flask/Django:

# instrumento.py - Importar al inicio de tu aplicación

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
import os

# Configurar el proveedor de trazas
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "mi-servicio"),
    "deployment.environment": os.getenv("DEPLOYMENT_ENV", "production"),
})

provider = TracerProvider(resource=resource)

# Configurar el exportador OTLP hacia SigNoz
exporter = OTLPSpanExporter(
    endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://signoz:4317"),
    insecure=True,
)

provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# Ejecutar una aplicación Flask con auto-instrumentación
opentelemetry-instrument \
  --exporter_otlp_endpoint http://signoz:4317 \
  --service_name mi-flask-app \
  flask run --port=5000

# Para Django
opentelemetry-instrument \
  --exporter_otlp_endpoint http://signoz:4317 \
  --service_name mi-django-app \
  python manage.py runserver

Instrumentación de Node.js

# Instalar las dependencias de OTel para Node.js
npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-grpc

Crea tracing.js en la raíz de tu proyecto:

// tracing.js - Debe cargarse ANTES que el resto de la aplicación
'use strict';

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

const exporterOptions = {
  url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://signoz:4317',
};

const traceExporter = new OTLPTraceExporter(exporterOptions);

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'mi-servicio-node',
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'production',
  }),
  traceExporter,
  instrumentations: [
    getNodeAutoInstrumentations({
      // Instrumenta automáticamente: Express, HTTP, MySQL, PostgreSQL, Redis, etc.
      '@opentelemetry/instrumentation-fs': { enabled: false }, // Deshabilitar si genera demasiado ruido
    }),
  ],
});

sdk.start();

// Asegurar el cierre limpio al terminar la aplicación
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('OTel SDK cerrado correctamente'))
    .catch((error) => console.log('Error cerrando OTel SDK', error))
    .finally(() => process.exit(0));
});

// package.json - Cargar tracing.js antes de la aplicación
{
  "scripts": {
    "start": "node -r ./tracing.js app.js",
    "start:prod": "NODE_ENV=production OTEL_SERVICE_NAME=mi-api node -r ./tracing.js app.js"
  }
}

Instrumentación de Java

<!-- Añadir al pom.xml (Spring Boot) -->
<dependency>
  <groupId>io.opentelemetry.instrumentation</groupId>
  <artifactId>opentelemetry-spring-boot-starter</artifactId>
  <version>2.1.0-alpha</version>
</dependency>

# O usar el agente Java para auto-instrumentación sin cambios de código
# Descargar el agente OTel para Java
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

# Ejecutar la aplicación con el agente
java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=mi-servicio-java \
  -Dotel.exporter.otlp.endpoint=http://signoz:4317 \
  -Dotel.exporter.otlp.protocol=grpc \
  -jar mi-aplicacion.jar

# En Spring Boot application.yaml
management:
  otlp:
    metrics:
      export:
        url: http://signoz:4318/otlp/v1/metrics
  tracing:
    sampling:
      probability: 1.0  # 100% de muestreo (reducir en producción con alto tráfico)

spring:
  application:
    name: mi-servicio-spring

Análisis de Trazas y Rendimiento

Ver servicios y operaciones lentas

En la interfaz de SigNoz:

  1. Services: lista de servicios con métricas de latencia P50/P90/P99
  2. Haz clic en un servicio para ver las operaciones más lentas
  3. Traces: busca trazas específicas por servicio, operación, duración o atributos
# Buscar trazas con alta latencia via API de SigNoz
curl "http://localhost:8080/api/v1/traces?service=mi-servicio&minDuration=1000ms&limit=10"

Crear alertas de rendimiento

En Alerts → New Alert:

# Ejemplo de alerta para latencia alta
Nombre: Latencia P99 alta en API de pedidos
Tipo: Métricas
Condición: signoz_calls_total{service_name="api-pedidos", operation="POST /pedidos"} > 2000ms
Umbral: p99 > 2000 durante 5 minutos
Receptor: Slack - canal #alertas-api

Solución de Problemas

SigNoz no arranca o algún servicio falla:

# Ver el estado de todos los servicios
docker compose -f docker-compose.yaml ps

# Ver logs de un servicio específico
docker compose -f docker-compose.yaml logs clickhouse --tail 100
docker compose -f docker-compose.yaml logs query-service --tail 100

# ClickHouse necesita tiempo para inicializarse; esperar 2-3 minutos

Las trazas de la aplicación no aparecen en SigNoz:

# Verificar que el OTel Collector recibe datos
docker compose -f docker-compose.yaml logs otel-collector --tail 50

# Probar el endpoint OTLP desde la aplicación
curl -X POST http://signoz:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans": []}'
# Debe responder 200

# Verificar la conectividad de red desde el contenedor de la app al OTel Collector
docker exec mi-aplicacion nc -zv signoz 4317

Alto consumo de disco de ClickHouse:

# Ver el tamaño de los datos en ClickHouse
docker compose -f docker-compose.yaml exec clickhouse clickhouse-client \
  --query "SELECT database, table, formatReadableSize(sum(bytes)) as size FROM system.parts GROUP BY database, table ORDER BY sum(bytes) DESC"

# Configurar TTL de datos en ClickHouse (por defecto 30 días para trazas)
# En signoz/deploy/docker/clickhouse-setup/clickhouse-config.xml

El Frontend muestra "No services found":

# Verificar que la aplicación está enviando datos con el atributo service.name correcto
# Buscar en los logs del OTel Collector si hay errores de parsing

# Forzar la actualización de la caché de servicios
docker compose -f docker-compose.yaml restart query-service

Conclusión

SigNoz ofrece una plataforma APM completa que elimina la necesidad de pagar por herramientas propietarias costosas como Datadog o New Relic, con la ventaja de mantener todos los datos de rendimiento bajo tu control. La integración nativa con OpenTelemetry garantiza que la instrumentación realizada es estándar y portable, permitiendo cambiar de backend sin tocar el código de las aplicaciones. Para equipos que ya usan el stack de observabilidad de Grafana, SigNoz puede complementarlo aportando las capacidades de APM y análisis de rendimiento que faltan en Prometheus y Loki.