Implementación de Sentry en entorno propio

Además de ofrecer su código fuente, Sentry proporciona y mantiene una configuración mínima que puede utilizarse de inmediato para casos de uso simples. Este repositorio también sirve como modelo de cómo se conectan los diversos servicios de Sentry para una configuración completa, lo cual es útil para quienes desean mantener una instalación más extensa. Para simplificar, utilizamos Docker y Docker Compose, junto con scripts de instalación y actualización basados en bash.

Comenzando

Recomendamos descargar la última versión del repositorio autohospedado y ejecutar ./install.sh en este directorio. Este script se encargará de todo lo necesario para comenzar, incluyendo una configuración base, y luego indicará que ejecute docker-compose up -d para iniciar Sentry. Por defecto, Sentry se vincula al puerto 9000. Debería poder acceder a la página de inicio de sesión en http://127.0.0.1:9000.

Configuración

Es probable que desee ajustar la configuración predeterminada de Sentry. Las siguientes opciones están disponibles para este propósito:

1. sentry/config.yml — Contiene la mayoría (si no todas) de las opciones de configuración que se pueden ajustar. Este archivo se genera durante la instalación a partir de sentry/config.example.yml. El archivo en sí mismo documenta las opciones de configuración más comunes como comentarios de código. Algunas configuraciones comunes en este archivo incluyen:
   • system.url-prefix (se le pedirá que configure esto en la pantalla de bienvenida después de la instalación)
   • mail.* (aunque proporcionamos un servidor SMTP básico)
   • Integraciones como GitHub, Slack, etc.
2. sentry/sentry.conf.py — Contiene configuraciones más avanzadas. Este archivo se genera durante el proceso de instalación a partir de sentry/sentry.conf.example.py.
3. Variables de entorno — Las claves disponibles se definen en .env. Si necesita anular alguna variable de entorno, utilice algún método relacionado con el sistema para establecerlas. Para evitar cambios en Git, simplemente cree un archivo llamado .env.custom e inserte las variables de específicas del sistema en él. Para usarlo, utilice docker-compose --env-file /ruta/a/.env.custom up -d.
4. La Geolocalización utiliza un archivo de configuración personalizado para adaptarse a la tecnología subyacente.

Nota: Después de cambiar la configuración, debe reiniciar todos los servicios de Sentry ejecutando docker-compose restart web worker cron sentry-cleanup (o solo docker-compose restart para reiniciar todo).

Configuración de temas específicos

Hay más información sobre temas de configuración específicos relacionados con la autohospedaje:

• CA raíz personalizada
• Correo electrónico
• Geolocalización
• Inicio de sesión único (SSO)

Preparación para producción

Recomendamos encarecidamente utilizar un equilibrador de carga dedicado antes de vincular una configuración de Sentry a un dominio o subdominio específico. Un equilibrador de carga dedicado que realice la terminación SSL/TLS también reenviará las direcciones IP del cliente a la red interna de Docker Compose (ya que es casi imposible obtenerlo de otra manera) le proporcionará la mejor experiencia con Sentry. Como parte de esta configuración, recomendamos configurar controles de estado del equilibrador de carga dirigidos al punto final /_health/ utilizando el protocolo HTTP. Si Sentry se inicia, esto devolverá 200 o 500 con una lista de problemas.

Tenga en cuenta que todos estos usan un solo nodo para todos los servicios, incluido Kafka. Para cargas mayores, necesitará una máquina potente con mucha RAM y espacio de almacenamiento en disco. Para una mayor escalabilidad, probablemente utilizará un clúster con herramientas más complejas como Kubernetes. Debido a la naturaleza personalizada de la instalación autohospedada, no ofrecemos ninguna recomendación o guía sobre la escalabilidad.

Lanzamientos y actualizaciones de autohospedaje

Sentry ha reducido los lanzamientos regulares de autohospedaje para que sea lo más parecido posible a sentry.io. Hemos decidido seguir un plan de lanzamiento mensual utilizando el esquema de control de versiones CalVer. Cada 15 de mes se lanza una nueva versión, con lanzamientos posteriores según sea necesario. Puede encontrar la última versión en la sección de lanzamientos de nuestro repositorio autohospedado.

¿Por qué CalVer?

En resumen, esto es para que la versión autohospedada de Sentry se acerque lo más posible a la versión en tiempo real de sentry.io. En nuestro artículo de blog donde anunciamos el cambio, hay más detalles disponibles.

CalVer está optimizado para el despliegue continuo, no para la estabilidad a largo plazo. Recomendamos actualizar regularmente, al igual que lo hacemos en nuestro entorno SaaS.

Actualización

Animamos a todos a actualizar regularmente su instalación de Sentry para obtener la mejor y más reciente experiencia con Sentry.

Para actualizar, solo necesita descargar o verificar la versión del repositorio autohospedado que desea, reemplazar el contenido de la carpeta existente con esa versión y luego ejecutar ./install.sh.

Actualización de configuración

Es posible que tengamos algunas configuraciones actualizadas, especialmente para nuevas funciones, por lo que siempre debe verificar los archivos de configuración de ejemplo en el directorio sentry para ver si necesita actualizar la configuración existente. Hacemos todo lo posible por automatizar las actualizaciones de configuración clave, pero siempre debe verificar su configuración durante la actualización.

Antes de comenzar la actualización, cerramos todos los servicios y ejecutamos algunas migraciones de datos, por lo que se espera algún tiempo de inactividad. Hay una opción experimental --minimize-downtime que puede reducir el tiempo de inactividad durante la actualización. Use su propio riesgo y consulte el PR donde se implementa para obtener más información.

Pasos complejos

Tenemos tres pasos complejos que debe seguir para obtener cambios importantes en la base de datos:

1. Si viene de una versión anterior a la 9.1.2, primero debe actualizar a 9.1.2 y seguir estos pasos: ``` <tu.versión.sentry> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> última

2. Si viene de 9.1.2, primero debe actualizar a 21.5.0 y seguir estos pasos: ``` <tu.versión.sentry> -> 21.5.0 -> 21.6.3 -> última

3. Si viene de una versión anterior a 21.6.3, primero debe actualizar a 21.6.3: ``` <tu.versión.sentry> -> 21.6.3 -> última

En cualquier otro caso (21.6.3+), debería poder actualizar directamente a la última versión.

Compilaciones nocturnas

Ofrecemos compilaciones nocturnas del branch master del repositorio autohospedado para cada nuevo envío de Sentry y todos los proyectos compatibles:

• Snuba
• Relay
• Symbolicator

Nota: Estas compilaciones suelen ser estables, pero es posible que ocasionalmente encuentre versiones rotas, ya que estas versiones no se implementan primero en sentry.io. Tampoco se garantiza que pueda actualizar a versiones más altas sin perder datos. **Utilice compilaciones nocturnas bajo su propio riesgo**.

Respaldo y recuperación de autohospedaje

Respaldo rápido

Si necesita un método rápido para respaldar y recuperar una instancia de Sentry y no necesita datos de eventos históricos, puede utilizar los comandos integrados export e import. Estos comandos guardarán y cargarán todos los datos de proyectos y usuarios, pero no incluyen ningún dato de evento.

Respaldo

docker-compose run --rm -T -e SENTRY_LOG_LEVEL=CRITICAL web export > sentry/backup.json

Nota: Si omite la parte -T o -e SENTRY_LOG_LEVEL=CRITICAL, su archivo de respaldo contendrá líneas de registro y deberá eliminarlas de alguna manera.

Recuperación

Después de respaldar con el comando export, la forma más sencilla de recuperarlo es colocarlo en el directorio sentry dentro del repositorio principal self-hosted, junto al archivo de configuración. Este directorio se monta automáticamente en /etc/sentry, por lo que puede ejecutar el siguiente comando para recuperar su respaldo:

docker-compose run --rm -T web import /etc/sentry/backup.json

Si no ve ningún error y el proceso sale con el código 0, felicidades, acaba de recuperar su respaldo.

Nota: Recomendamos encarecidamente recuperar el respaldo en una instalación nueva (base de datos vacía pero con migraciones en ejecución) en la **misma versión de Sentry**. De lo contrario, es muy probable que encuentre errores y pueda dañar su base de datos.

Respaldo completo

La forma ideal de respaldar y recuperar Sentry es respaldar y recuperar todos los volúmenes de Docker que utiliza. Todos los volúmenes que guardan datos a largo plazo se han definido como volúmenes globales durante la instalación y tienen el prefijo sentry-:

• sentry-data
• sentry-postgres
• sentry-redis
• sentry-zookeeper
• sentry-kafka
• sentry-clickhouse
• sentry-symbolicator

Nota: Solo respaldando y recuperando estos volúmenes puede restaurar todos los datos persistentes. Si también necesita respaldar los datos en ejecución, recomendamos respaldar cualquier volumen específico del proyecto que cree docker-compose, generalmente con el prefijo sentry_self_hosted_sentry-.

Docker documenta cómo respaldar y recuperar volúmenes. Siempre que pueda leer el volumen sin problemas, puede usar diferentes métodos.

CA raíz personalizada para autohospedaje

A partir de Sentry 21.8.0, si necesita acceder a servicios de Sentry con certificados TLS que no provengan de CA raíz de confianza pública, ahora puede agregarlos fácilmente a los contenedores. Simplemente agregue los certificados a la carpeta certificates dentro del dircetorio raíz de la instalación de Sentry y reinicie los contenedores. Se utilizará su CA raíz personalizada además de las CA raíz de confianza pública.

Nota: Aunque puede ejecutar update-ca-certificates en cada contenedor, esto actualizará los paquetes raíz en el sistema en el disco, pero no realizará ninguna acción en las copias en memoria. Reiniciar los contenedores actualizará los paquetes y se asegurará de que se utilicen.

Si un certificado determinado tiene problemas, los registros del contenedor tendrán la salida de update-ca-certificates al inicio.

Dependencias con raíces integradas

Algunas dependencias eligen integrar sus propias raíces CA e ignoran las raíces del sistema CA. En los casos conocidos, se han configurado para usar las raíces del sistema. Si algo parece ignorar las raíces del sistema, cree un problema para que se rastree y corrija.

Raíces integradas anuladas

• Python
  • requests
  • botocore
  • grpc

Correo electrónico para autohospedaje

Nota: Recuerde que una vez que cambie la configuración, deberá reiniciar todos los servicios de Sentry. Para obtener más información, consulte la sección de configuración.

Correo electrónico saliente

El autohospedaje de Sentry viene con un servidor SMTP saliente integrado respaldado por exim4. La configuración predeterminada está configurada para usar este servidor. Solo necesita establecer una dirección válida para la configuración mail.from en config.yml y establecer SENTRY_MAIL_HOST en el FQDN de su instancia de Sentry en .env. Tenga en cuenta que si comienza a enviar demasiados correos electrónicos a direcciones públicas, su nuevo servidor podría marcarse como remitente de spam y ser prohibido.

Si desea utilizar un servidor SMTP externo, puede establecer las configuraciones mail.* relevantes en el archivo config.yml e ignorar el servidor SMTP integrado. Para obtener todos los detalles sobre el significado y la función de cada configuración, consulte nuestra documentación del servicio de correo electrónico.

Debido a la forma jerárquica de la configuración, si actualiza las configuraciones de mail a través de la interfaz web, también deberá comentar el valor predeterminado mail.host: 'smtp' en config.yml para que se seleccione la configuración deseada.

Correo electrónico entrante

El soporte de correo electrónico entrante proporcionado por Sentry a través de Mailgun es muy limitado. Puede encontrar toda la información sobre cómo configurarlo en nuestra documentación del servicio de corrreo electrónico entrante.

Geolocalización para autohospedaje

Sentry puede usar la base de datos gratuita GeoLite2-City de MaxMind para geolocalizar direcciones IP, proporcionando contexto adicional para los eventos de error de direcciones IP de usuario final conocidas y el historial de sesiones de los usuarios que inician sesión en la instalación de Sentry. Para ello, incluimos la herramienta geoipupdate de MaxMind.

Para aprovechar la geolocalización de direcciones IP en el lado del servidor, debe enviar primero las direcciones IP a Sentry. De forma predeterminada, los SDK más recientes no lo hacen.

Para habilitar la geolocalización de direcciones IP en el lado del servidor, registre una cuenta gratuita de MaxMind y luego indique a sus credenciales de Sentry colocando su archivo de configuración de MaxMind en geoip/GeoIP.conf.

AccountID 012345
LicenseKey foobarbazbuz
EditionIDs GeoLite2-City

Con este archivo de configuración, las ejecuciones posteriores de install.sh de Sentry actualizarán la base de datos de geolocalización de direcciones IP. La próxima vez que reinicie su instancia autohospedada de Sentry (especialmente los servicios relay y web), debería ver los datos más recientes. Aquí hay una forma de confirmar si funciona correctamente:

1. Para el servicio relay: Debería haber algo de púrpura en Paneles > Errores por país.
2. Para el servicio web: Configuración de usuario > Seguridad > Historial de sesiones debería mostrar el código de país y la región (por ejemplo, "US (CA)") debajo de la dirección IP en la tabla.

Es normal ver que el contenedor sentry_self_hosted_geoipupdate_1 sale poco después de iniciar, ya que actualizar la base de datos de geolocalización es un proceso por lotes único, no un trabajo de larga duración.

Actualización

Los servicios que utilizan el archivo GeoLite2-City.mmdb necesitan saber dónde encontrarlo. Las nuevas instalaciones configurarán esto automáticamente, pero si va a actualizar, deberá establecer manualmente lo siguiente antes de reiniciar Sentry.

En relay/config.yml (ejemplo):

processing:
  geoip_path: "/geoip/GeoLite2-City.mmdb"

En sentry/sentry.conf.py (ejemplo):

GEOIP_PATH_MMDB = '/geoip/GeoLite2-City.mmdb'

Inicio de sesión único (SSO) para autohospedaje

El SSO en Sentry se maneja de una de dos maneras:

• Mediante middleware que indica el usuario autenticado desde un proxy ascendente
• Mediante un servicio de terceros que implementa el pipeline de autenticación

Uso de middleware proxy (SAML2)

A partir de Sentry 20.6.0, el autohospedaje de Sentry tiene soporte integrado para SAML2 y algunos proveedores de autenticación. Para versiones anteriores, deberá agregar las siguientes líneas a sentry/requirements.txt antes de ejecutar ./install.sh:

sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2

Puede configurarlo de la misma manera que en sentry.io, excepto que necesitará usar el url-prefix de su propia instancia para las URL mencionadas en la documentación.

Inicio de sesión único con OAuth

Nota: Después de habilitar el SSO, este será el único método para iniciar sesión en su instancia autohospedada. Si necesita registrarse gratuitamente con SSO, puede comentar esto en un PR de GitHub.

Autenticación de Google

A partir de Sentry 9.1, el autohospedaje de Sentry viene con soporte integrado para la autenticación de Google. Para habilitarlo, necesita crear un ID de cliente y un secreto para su aplicación de Google, y luego ingresar estos valores en su archivo sentry/config.yaml:

auth-google.client-id: '<id de cliente>'
auth-google.client-secret: '<secreto de cliente>'

Nota: Recuerde que una vez que cambie la configuración, deberá reiniciar todos los servicios de Sentry. Para obtener más información, consulte la sección de configuración.

Autenticación de GitHub

A partir de Sentry 10, el autohospedaje de Sentry viene con soporte integrado para la autenticación de GitHub. Para habilitarlo, necesita crear una nueva aplicación GitHub en su organización e instalarla.

Crear una aplicación GitHub para SSO e integraciones

El nombre de la aplicación GitHub no debe contener espacios.

Si el formulario anterior no funciona para usted, necesita realizar la siguiente configuración para su aplicación GitHub:

Configuración	Valor
URL de la página de inicio	${urlPrefix}
URL de devolución de llamada de autorización de usuario	${urlPrefix}/auth/sso/
URL de configuración (opcional)	${urlPrefix}/extensions/github/setup/
URL de webhook	${urlPrefix}/extensions/github/webhook/

No olvide reemplazar todas las apariciones de ${urlPrefix} con su propio prefijo de URL.

Cuando se le pida que seleccione permisos, elija las siguientes opciones:

Permiso	Configuración
Permisos de organización / Miembros	Solo lectura
Permisos de usuario / Direcciones de correo electrónico	Solo lectura
Administración del repositorio	Solo lectura
Contenidos del repositorio	Solo lectura
Problemas	Lectura y escritura
Solicitudes de extracción	Lectura y escritura
Webhooks del repositorio	Lectura y escritura

Actualizar su configuración con la información de su aplicación GitHub

Luego, necesita configurar los siguientes valores de configuración:

En sentry/sentry.conf.py:

GITHUB_APP_ID="<ID de aplicación>"
GITHUB_API_SECRET="<secreto de cliente>"
GITHUB_REQUIRE_VERIFIED_EMAIL = True  # Opcional pero recomendado

# Solo si está utilizando GitHub Enterprise
#GITHUB_BASE_DOMAIN = "git.ejemplo.com"
#GITHUB_API_DOMAIN = "api.git.ejemplo.com"

En sentry/config.yaml:

# github-app.id: <ID de aplicación>
# github-app.name: '<nombre de la aplicación GitHub>'
# github-app.webhook-secret: '<secreto de webhook>' # Solo si está configurado en GitHub
# github-app.client-id: '<ID de cliente>'
# github-app.client-secret: '<secreto de cliente>'
# github-app.private-key: |
#   -----BEGIN RSA PRIVATE KEY-----
#   claveprivadaclaveprivadaclaveprivadaclaveprivada
#   claveprivadaclaveprivadaclaveprivadaclaveprivada
#   claveprivadaclaveprivadaclaveprivadaclaveprivada
#   claveprivadaclaveprivadaclaveprivadaclaveprivada
#   claveprivadaclaveprivadaclaveprivadaclaveprivada
#   -----END RSA PRIVATE KEY-----

Esto también habilitará la integración de GitHub para su instancia.

Nota: Recuerde que una vez que cambie la configuración, deberá reiniciar todos los servicios de Sentry. Para obtener más información, consulte la sección de configuración.

Proveedor personalizado

Actualmente, la API se considera inestable y puede cambiar. Las cosas pueden no cambiar mucho, pero hay algunos lugares que necesitan limpieza.

Dicho esto, si desea construir el suyo propio, consulte una de las implementaciones de referencia anteriores.

Solución de problemas para autohospedaje

Recuerde que el repositorio autohospedado está dirigido a cargas medias y bajas y tiene en cuenta la simplicidad. Las personas que necesitan configuraciones más grandes o tienen picos de eventos pueden expandir esto según sus necesidades y entorno específicos.

Común

Puede ver los registros de cada servicio ejecutando docker-compose logs <nombre_servicio>. Puede usar la bandera -f para "seguir" los registros entrantes y la bandera -t para las marcas de tiempo. Si no pasa ningún nombre de servicio, obtendrá los registros de todos los servicios en ejecución. Para obtener más detalles, consulte la referencia del comando logs.

Kafka

Una de las cosas más propensas a causar problemas es Kafka. El error más reportado es:

Exception: KafkaError{code=OFFSET_OUT_OF_RANGE,val=1,str="Broker: Offset out of range"}

Esto ocurre cuando Kafka y el consumidor no están sincronizados. Las posibles causas son:

1. Espacio en disco o memoria insuficiente
2. Los picos continuos de eventos causan tiempos de procesamiento largos, lo que hace que Kafka descarte mensajes cuando supera el tiempo de retención
3. Problemas de sincronización de fecha/hora debido a reinicios o ciclos de pausa/reanudación

Recuperación

Solución correcta

La *correcta* solución es la siguiente (informada por @rmisyurev):

1. Obtener la lista de consumidores: ``` docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --list

2. Obtener información del grupo: ``` docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers -describe

3. Usar una prueba de ejecución (opcional) para observar qué pasará con el offset: ``` docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --dry-run

4. Establecer el offset en el más reciente y ejecutar: ``` docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --execute

Puede reemplazar snuba-consumers con otros grupos de consumidores o temas events según sea necesario.

Opción hardcore

La *opción hardcore* es eliminar todos los volúmenes relacionados con Kafka y recrearlos, lo que provocará la pérdida de datos. Después de eliminar estos volúmenes, cualquier dato pendiente _se perderá_.

1. Detener la instancia: ``` docker-compose down --volumes

2. Eliminar volúmenes relacionados con Kafka y Zookeeper: ``` docker volume rm sentry-kafka docker volume rm sentry-zookeeper

3. Ejecutar el script de instalación nuevamente: ``` ./install.sh

4. Iniciar la instancia: ``` docker-compose up -d

Reducción del uso de disco

Si desea reducir el espacio en disco utilizado por Kafka, debe calcular cuidadosamente la cantidad de datos que ingiere y la cantidad de pérdida de datos que puede tolerar, y luego seguir las sugerencias en este excelente post de StackOverflow o en nuestro foro comunitario.

Redis

En la configuración autohospedada, Redis se utiliza tanto como almacenamiento de datos transaccionales como como cola de trabajo de Celery. Por esta razón, puede estar sobrecargado durante los picos de eventos. A partir de la versión 20.10.1, hemos realizado algunas mejoras significativas en este aspecto. Si todavía encuentra problemas, puede considerar ampliar Redis mismo o cambiar a un intermediario de Celery diferente, como RabbitMQ.

Workers

Si ve errores como:

Los trabajadores en segundo plano no se han registrado recientemente. Parece que tiene una acumulación de 200 tareas. Sus trabajadores no se están ejecutando o necesita más capacidad.

Puede beneficiarse del uso de trabajadores adicionales dedicados. Esto se logra creando nuevos servicios de worker en docker-compose.override.yml y vinculándolos a colas específicas utilizando el parámetro -Q nombre_cola. Un ejemplo sería:

trabajador1:
    << : *sentry_defaults
    command: run worker -Q eventos.procesar_evento

Para ver un ejemplo más completo, consulte la solución de ejemplo en nuestro foro comunitario.

Postgres

Postgres se utiliza para el almacenamiento de datos principle, así como para el almacenamiento de datos de tipo clave/valor en nodestore. La tabla nodo_nodestore puede crecer rápidamente, especialmente con un uso intensivo de las funciones de monitoreo de rendimiento, ya que los datos de seguimiento se almacenan en esta tabla.

La tabla nodo_nodestore se limpia como parte de la tarea de limpieza, pero Postgres puede no tener la oportunidad de limpiar la tabla (especialmente en situaciones de sobrecarga), por lo que incluso si las filas pueden eliminarse, aún ocupan espacio en disco.

Puede usar pg-repack, que reempaqueta una tabla creando una nueva tabla y copiando los datos antes de eliminar la tabla anterior. Debe ejecutarlo después del script de limpieza y tenga en cuenta que al crear la tabla, **el uso del disco aumentará antes de disminuir**.

Aquí hay un ejemplo de script:

# Solo mantener los últimos 7 días de datos de nodestore. Usamos intensamente el monitoreo de rendimiento.
docker-compose run -T web cleanup --days 7 -m nodestore -l debug
# Esto asegura que pg-repack exista antes de ejecutar, ya que el contenedor se recrea en las actualizaciones
docker-compose run -T postgres bash -c "apt update && apt install -y --no-install-recommends postgresql-9.6-repack && su postgres -c 'pg_repack -E info -t nodestore_node'"

Otros

Si todavía tiene problemas, siempre puede visitar nuestro foro comunitario para buscar temas existentes o crear uno nuevo y pedir ayuda. Recuerde que esperamos que la comunidad se ayude a sí misma, y los empleados de Sentry también intentan monitorear y responder las preguntas del foro cuando tienen tiempo.

Al informar problemas o hacer preguntas en el foro, compartir sus registros de instalación, registros de servicios y versión de Sentry ahorrará tiempo y esfuerzo para usted y para las personas que intentan ayudarle.