Skip to main content

Integracion Sentry — Releases y alertas

Frihet se integra con Sentry para el seguimiento de errores en produccion. La integracion incluye el etiquetado automatico de releases tras cada deploy, auto-resolucion de issues asociados a la version anterior y forwarding de alertas criticas a Telegram.

Esta integracion esta dirigida a desarrolladores que usan la API de Frihet o construyen sobre la plataforma. Para usuarios finales, los errores de la aplicacion web de Frihet ya estan monitorizados por el equipo de Frihet.

Configuracion inicial​

1. Obtener el DSN de Sentry​

En tu proyecto Sentry:

  1. Settings → Projects → selecciona tu proyecto → Client Keys (DSN).
  2. Copia el DSN — tiene el formato https://XXXXXXX@oXXXXXX.ingest.sentry.io/XXXXXXX.

2. Conectar con Frihet​

  1. Ve a Desarrolladores → Integraciones → Sentry.
  2. Introduce el DSN de tu proyecto Sentry.
  3. Introduce el Auth Token de Sentry (Settings → Auth Tokens → Create New Token, permisos: project:releases, org:read).
  4. Selecciona el entorno Sentry (production, staging) que quieres monitorizar.
  5. Guarda. Frihet valida la conexion enviando un evento de prueba.
# Verificar conexion via CLI Frihet
frihet sentry:ping
# Respuesta esperada: Sentry DSN OK — project: my-project (slug: my-project)

3. Configurar la organizacion y proyecto Sentry​

# En .env o variables de entorno del proyecto
SENTRY_DSN=https://xxxxxxx@oxxxxxx.ingest.sentry.io/xxxxxxx
SENTRY_AUTH_TOKEN=sntryu_xxxxxxx
SENTRY_ORG=my-organization
SENTRY_PROJECT=my-project

Etiquetado automatico de releases​

Tras cada deploy exitoso a produccion, Frihet crea automaticamente un release en Sentry con:

  • Version: el hash corto del commit de produccion (git rev-parse --short HEAD)
  • Fecha de deploy: timestamp UTC del deploy
  • Entorno: production (o el que hayas configurado)
  • Commits: lista de commits desde el release anterior (requiere integracion GitHub/GitLab en Sentry)
# El release se crea equivalente a:
sentry-cli releases new ${VERSION}
sentry-cli releases set-commits ${VERSION} --auto
sentry-cli releases deploys ${VERSION} new -e production
sentry-cli releases finalize ${VERSION}

Puedes ver los releases en Sentry → Releases → tu proyecto.

Auto-resolucion de issues​

Cuando se crea un nuevo release en Sentry, los issues que estaban asociados a la version anterior y que no han vuelto a ocurrir se marcan automaticamente como Resolved in next release.

Si el mismo error ocurre de nuevo en el nuevo release, Sentry lo reactiva como Regression y Frihet envia una notificacion inmediata (ver alertas).

Para que la auto-resolucion funcione correctamente:

  1. La integracion de source maps debe estar activa (ver seccion source maps).
  2. Los issues deben tener fingerprint consistente entre releases.

Reglas de alertas​

Configura las alertas en Desarrolladores → Sentry → Reglas de alerta:

Plantillas incluidas​

ReglaCondicionCanal
Error critico nuevoIssue nuevo con level=fatal en 5 minTelegram + Email
RegressionIssue resuelto que reapareceTelegram
Umbral de errores> 100 eventos en 1 horaEmail
Performance degradadaP95 latencia > 3s durante 15 minEmail

Puedes editar los umbrales y canales en cualquier momento.

Forwarding a Telegram​

Para recibir alertas en Telegram:

  1. Ve a Configuracion → Notificaciones → Telegram y configura el bot si aun no lo has hecho.
  2. En las reglas de Sentry, activa el canal Telegram.
  3. Selecciona el chat de destino (usuario personal, grupo de equipo, o canal).

Formato del mensaje Telegram:

🔴 [FATAL] TypeError: Cannot read properties of undefined (reading 'id')
Proyecto: my-frihet-integration
Release: a3f2b1c
URL: /api/v1/invoices/create
Eventos: 23 en los últimos 5 min
Ver en Sentry: https://sentry.io/organizations/my-org/issues/12345/

Source maps​

Para que los stack traces en Sentry sean legibles (en lugar de codigo minificado), configura la subida de source maps en tu pipeline de CI/CD:

# Instalar CLI Sentry
npm install --save-dev @sentry/cli

# En tu script de deploy (post-build)
npx sentry-cli sourcemaps inject ./dist
npx sentry-cli sourcemaps upload ./dist \
  --org $SENTRY_ORG \
  --project $SENTRY_PROJECT \
  --release $(git rev-parse --short HEAD)

Para proyectos Vite, usa el plugin oficial:

npm install --save-dev @sentry/vite-plugin
// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  plugins: [
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
  build: { sourcemap: true },
});

Rotacion del Auth Token​

El Auth Token de Sentry debe rotarse periodicamente por seguridad (recomendado cada 90 dias). Para rotar:

  1. En Sentry: Settings → Auth Tokens → Revoke el token antiguo → Create New Token.
  2. En Frihet: Desarrolladores → Sentry → Actualizar token.
  3. Actualiza el token en tus variables de entorno de CI/CD.
# Verificar que el nuevo token funciona
frihet sentry:ping --token sntryu_nuevo_token

Gotchas​

  • Slug del proyecto Sentry: el slug es el identificador URL del proyecto (ej: javascript-react, frihet-erp-web). No confundir con el nombre mostrado. El slug aparece en la URL de Sentry: sentry.io/organizations/my-org/projects/SLUG/.
  • Auth Token vs DSN: el DSN es para enviar eventos (cliente). El Auth Token es para la API de gestion (crear releases, subir source maps). Necesitas ambos.
  • Issues de terceros: si tu integracion usa librerias de terceros que lanzan errores, considera usar inboundFilters en Sentry para ignorar errores conocidos sin valor de debug.
  • Entorno staging vs production: crea reglas de alerta separadas para cada entorno. Los errores en staging no deben disparar alertas de produccion.
  • Rate limits: el plan gratuito de Sentry tiene un limite de 5.000 eventos/mes. Si lo superas, los eventos adicionales se descartan sin notificacion. Monitoriza el uso en Sentry → Settings → Usage & Billing.

Relacionado​