Kowal_Sentry: instrucciones de instalación y configuración

Objetivo del módulo

Kowal_Sentry integra Magento 2 con Sentry y permite monitorizar:

• errores del backend PHP,
• errores JavaScript en el storefront y, opcionalmente, en el panel de administración,
• transacciones HTTP, CLI y cron,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking y preparación para source maps.

El módulo se ha preparado como paquete Composer y debería funcionar desde la ubicación vendor/kowal/module-sentry.

Requisitos

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• acceso a Sentry y al menos un proyecto
• dirección de e-mail del cliente y token de licencia para el repositorio Composer de Kowal

Instalación

Los siguientes comandos se han copiado de README.md.

Recibirás por e-mail los datos de acceso al repositorio Composer, es decir, la dirección de e-mail del cliente y el token de licencia, después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-sentrybin/magento module:enable Kowal_Sentrybin/magento setup:upgradebin/magento cache:flush

Importante

• El paquete Composer debe funcionar únicamente desde vendor/kowal/module-sentry.
• No se debe mantener simultáneamente el mismo módulo en app/code/Kowal/Sentry.
• Después de la instalación encontrarás la configuración en:

Stores -> Configuration -> Kowal -> Sentry

Inicio rápido

Configuración mínima necesaria para poner en marcha el módulo:

1. Establece Enable Module = Yes.
2. Establece Environment, por ejemplo production o staging.
3. Activa Enable Backend Monitoring y pega Backend DSN.
4. Si quieres monitorizar el frontend, activa Enable Frontend Monitoring y pega Frontend DSN.
5. Guarda la configuración y limpia la caché si es necesario en ese entorno.

Dónde obtener los datos de Sentry

DSN

Normalmente encontrarás el DSN aquí:

Settings -> Projects -> [projekt] -> Client Keys (DSN)

En los campos Backend DSN y Frontend DSN pega solo la URL del DSN, por ejemplo:

https://examplePublicKey@o0000000000000000.ingest.de.sentry.io/0000000000000000

No pegues el snippet completo:

\Sentry\init([ 'dsn' => 'https://examplePublicKey@o0000000000000000.ingest.de.sentry.io/0000000000000000',]);

Organization

La forma más sencilla de identificar el slug de la organización es a partir de la URL del panel de Sentry, por ejemplo:

https://sentry.io/settings/acme/projects/shop-frontend/

En este ejemplo:

• acme es Organization
• shop-frontend es Project Slug

Project Slug

Puedes consultarlo:

• desde la URL del proyecto en el panel de Sentry,
• o desde Settings -> Projects -> [projekt] -> Details

Auth token para source maps

Si utilizas sentry-cli, lo más recomendable es guardar el token fuera de Magento, por ejemplo en una variable de entorno:

SENTRY_AUTH_TOKEN

Creación del token:

• Settings -> Custom Integrations
• o User Settings -> Personal Tokens

Verificación después de la instalación

Después de la configuración básica puedes comprobar si el módulo está activo y si el SDK funciona. Los comandos de smoke test siguientes se han copiado de README.md.

Después de activar Enable Test Commands:

bin/magento kowal:sentry:test:errorbin/magento kowal:sentry:test:transactionbin/magento kowal:sentry:test:checkinbin/magento kowal:sentry:test:log

Configuración en el panel de Magento

Ruta:

Stores -> Configuration -> Kowal -> Sentry

A continuación se describen las secciones, opciones y variantes de configuración.

Sección General

Esta sección controla la activación del módulo, el entorno y la forma de calcular release.

Enable Module

• Yes: activa el módulo globalmente.
• No: el backend y el frontend no se inicializarán, aunque otras opciones estén activadas.

Recomendación:

• Yes en el entorno desde el que quieras enviar datos a Sentry.

Environment

Ejemplos:

• production
• staging
• development

Variantes:

• un nombre común para toda la instancia,
• valores diferentes por website/store view si necesitas separar los eventos.

Recomendación:

• sin espacios ni barras,
• mantén una nomenclatura constante entre backend, frontend y CI/CD.

Release Strategy

Variantes disponibles:

• manual: release se toma del campo Release Name Override
• env: release se obtiene de variables de entorno
• file: release se lee desde un archivo
• generated: release lo compone automáticamente el módulo

Cuándo usarlo:

• manual: cuando quieres introducir el release manualmente, más bien como opción de emergencia o en despliegues sencillos
• env: lo mejor en CI/CD, cuando el release se transmite mediante el deployment
• file: adecuado cuando el deployment guarda el identificador de versión en un archivo compartido
• generated: adecuado para empezar si aún no tienes un pipeline de release maduro

Variables de entorno compatibles:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Se utiliza solo con la estrategia manual.

Ejemplo:

magento-store@2.4.7-p1+20260410.1

Recomendación:

• exactamente el mismo valor debe utilizarse al subir los source maps.

Project Name

Nombre auxiliar del proyecto en los contextos del módulo. No es el Project Slug de Sentry.

Variantes:

• nombre de la instancia de la tienda,
• nombre del grupo de tiendas,
• nombre del proyecto interno.

Debug Mode

• Yes: logging diagnóstico más detallado
• No: modo de producción

Recomendación:

• No en producción,
• Yes temporalmente cuando estés diagnosticando la configuración.

Enable Test Commands

• Yes: habilita los comandos de prueba bin/magento
• No: los oculta durante el funcionamiento normal

Recomendación:

• Yes en staging o durante las pruebas,
• No en la configuración de producción permanente.

Sección Backend SDK

Se refiere al PHP SDK utilizado por storefront HTTP, admin, API, cron y CLI.

Enable Backend Monitoring

• Yes: activa la monitorización del backend
• No: el backend no envía errores ni traces a Sentry

Backend DSN

Es el DSN principal para el PHP SDK.

Variantes:

• proyecto de Sentry independiente solo para el backend
• el mismo proyecto para backend y frontend

Recomendación:

• en despliegues más maduros, mantén proyectos separados para backend y frontend,
• en instalaciones más pequeñas se puede empezar con un único proyecto compartido.

Error Sample Rate

Rango: 0-1

Ejemplos:

• 1: enviar todos los errores
• 0.5: enviar aproximadamente la mitad
• 0.25: enviar aproximadamente el 25%

Recomendación:

• normalmente 1.0 para errores, al menos al empezar.

Trace Sample Rate

Rango: 0-1

Ejemplos:

• 0.05: sampling bajo, adecuado para producción con mucho tráfico
• 0.1: punto de partida razonable
• 0.2: más datos a costa de mayor volumen

Recomendación:

• en producción normalmente 0.05-0.2, según el tráfico y el plan de Sentry.

Profile Sample Rate

Rango: 0-1

Variantes:

• 0: profiling desactivado
• valor bajo, por ejemplo 0.01: diagnóstico periódico de rendimiento

Recomendación:

• 0 o un valor muy bajo en producción.

Enable Logs

• Yes: envía structured logs
• No: sin logs en Sentry

Cuándo activarlo:

• cuando quieras correlacionar logs con traces y errores.

Enable Metrics API

• Yes: activa la fachada del módulo para métricas
• No: las métricas del lado del módulo no estarán activas

Nota:

• la versión actual sentry/sentry 4.24.x trata backend metrics como una API en desuso / no-op.

Enable Cron Monitoring

• Yes: envía check-ins y transacciones cron
• No: los cron no serán monitorizados por Sentry

Encontrarás los datos en Sentry en la sección:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitoriza los comandos bin/magento
• No: sin monitorización de procesos CLI

Útil para:

• importaciones,
• reindexaciones,
• comandos de integración personalizados.

Enable Adminhtml Monitoring

• Yes: monitoriza las requests del panel de administración
• No: limita el backend a storefront, API, cron y CLI

Enable API Monitoring

• Yes: monitoriza REST, GraphQL y otros endpoints
• No: excluye la parte de integración de la monitorización

Sección Frontend SDK

Se refiere al Browser SDK cargado en el storefront y, opcionalmente, en el panel de admin.

Enable Frontend Monitoring

• Yes: carga el Browser SDK
• No: el frontend no envía datos a Sentry

Frontend DSN

Variantes:

• proyecto frontend independiente
• el mismo DSN que el backend
• campo vacío para que el módulo intente hacer fallback a Backend DSN

Recomendación:

• como objetivo, un proyecto frontend independiente si quieres tener Issues, Replay y Performance claros.

Enable Storefront JS

• Yes: el Browser SDK funciona en el storefront
• No: sin SDK en la parte pública de la tienda

Enable Admin JS

• Yes: el Browser SDK también funciona en el panel de admin
• No: la monitorización JS se limita al storefront

Recomendación:

• actívalo solo cuando realmente estés diagnosticando problemas JS en el admin.

JS Trace Sample Rate

Rango: 0-1

Ejemplos:

• 0.01: con mucha prudencia
• 0.05: buen inicio para producción
• 0.1: más datos, mayor volumen

JS Replay Session Sample Rate

Rango: 0-1

Ejemplos:

• 0: sin replays completos
• 0.01: inicio seguro
• 0.05: más datos para analizar UX y errores

JS Replay On Error Sample Rate

Rango: 0-1

Ejemplos:

• 1: replay después de cada error en la sesión
• 0.5: replay después de una parte de los errores

Recomendación:

• a menudo es mejor punto de partida que un sampling alto de todas las sesiones.

Enable Session Replay

• Yes: activa Replay
• No: sin grabación de sesiones

Recomendación:

• actívalo junto con un enmascaramiento fuerte de checkout y pagos.

Enable User Feedback Widget

• Yes: el widget Feedback está disponible
• No: el widget no se carga

Nota:

• según el plan y la cuenta de Sentry, la función puede estar marcada como beta / experimental.

Enable Checkout Instrumentation

• Yes: añade breadcrumbs y tags de checkout
• No: sin contexto adicional de checkout

Recomendación:

• normalmente conviene dejarlo activado.

Enable Ajax Instrumentation

• Yes: breadcrumbs para AJAX / fetch / XHR
• No: menos contexto para problemas de frontend

Browser SDK CDN URL

Por defecto apunta al bundle oficial de Sentry.

Variantes:

• URL predeterminada del módulo
• mirror CDN propio
• bundle específico fijado / versión concreta

Cámbialo solo cuando:

• fijas la versión del SDK,
• tienes reglas CSP propias,
• utilizas mirror de assets.

Sección Privacy / Security

Esta sección se encarga de minimizar el riesgo de envío de datos sensibles.

Send Default PII

• Yes: el SDK puede enviar el conjunto predeterminado de datos de usuario y request
• No: política de privacidad más conservadora

Recomendación:

• normalmente No.

Anonymize IP

• Yes: no enviar la IP completa
• No: mantener el comportamiento estándar

Recomendación:

• normalmente Yes.

Mask Customer Data

• Yes: enmascara los datos del cliente
• No: menor protección de datos

Recomendación:

• prácticamente siempre Yes en producción.

Mask Checkout Fields

• Yes: enmascara los campos de checkout
• No: riesgo de fuga de datos del checkout

Recomendación:

• siempre Yes.

Mask Payment Fields

• Yes: enmascara los campos relacionados con el pago
• No: muy arriesgado

Recomendación:

• siempre Yes.

Block Authorization Headers

• Yes: elimina o enmascara Authorization y tokens
• No: riesgo de envío de datos de autenticación

Recomendación:

• siempre Yes.

Block Cookies

• Yes: elimina cookies de los datos del evento
• No: mayor riesgo de fuga de datos de sesión

Recomendación:

• normalmente Yes.

Block POST Bodies

• Yes: elimina los cuerpos POST
• No: envía más datos de la request

Recomendación:

• normalmente Yes, especialmente para checkout, login y formularios.

Redact Query Params

• Yes: enmascara los parámetros de query string
• No: el query string sigue siendo más legible, pero menos seguro

Additional Redacted Keys

Campo de texto para claves adicionales que se deben redactar.

Ejemplos:

• token
• api_key
• customer_email
• external_customer_id

Puedes separarlas con:

• comas,
• espacios,
• saltos de línea.

Replay Mask Selectors

Selectores CSS cuyo contenido debe enmascararse en Replay.

Ejemplos:

• .customer-email
• .field[name*='password']
• .payment-method

Replay Block Selectors

Selectores CSS que deben bloquearse por completo en Replay.

Ejemplos:

• .checkout-container
• .payment-method iframe
• .opc-wrapper

Allowed Domains for Replay Network Details

Lista de dominios para los que Replay puede adjuntar detalles de requests de red.

Ejemplos:

• store.example.com
• api.example.com
• trusted-partner.example

Recomendación:

• introduce solo dominios propios y de confianza.

Sección Filtering

Esta sección reduce el ruido y el volumen de eventos.

Ignore Exceptions Regex

Una regla regex por línea.

Ejemplos de uso:

• errores técnicos conocidos y no peligrosos,
• excepciones de integraciones externas que ya se gestionan de otra forma.

Ignore URLs Regex

Una regla regex por línea.

Ejemplos:

• endpoints de health-check,
• webhooks de prueba,
• recursos técnicos.

Ignore Transactions

Un nombre de transacción por línea.

Recomendación:

• primero recopila datos,
• después filtra las transacciones de poco valor y repetitivas.

Ignore Bots

• Yes: excluye el tráfico de bots y crawlers
• No: también monitorizas el tráfico automático

Recomendación:

• Yes con mucho tráfico SEO.

Ignore Health Checks

• Yes: omite /health, /status, /ping y similares
• No: esas requests llegarán a Sentry

Ignore Admin Routes

• Yes: reduce los eventos del admin
• No: el admin sigue monitorizado

Ignore Static Resource Errors

• Yes: filtra parte de los errores de assets .js y .css
• No: todos los errores de este tipo siguen siendo visibles

Recomendación:

• normalmente Yes si no quieres llenar el proyecto de ruido después de los deploys.

Sección Context

Controla la cantidad de contexto de negocio añadido a los eventos.

Attach Store Context

• Yes: adjunta store_id, store_code, nombre de la tienda y moneda
• No: sin este contexto

Recomendación:

• Yes, especialmente con multistore.

Attach Website Context

• Yes: adjunta datos de website
• No: sin este nivel de identificación

Attach Customer Context

• Yes: adjunta contexto anonimizado del cliente
• No: sin datos sobre el estado del cliente

Attach Quote Context

• Yes: adjunta contexto del carrito / quote
• No: menos datos para diagnosticar el checkout

Attach Cart Totals

• Yes: adjunta totales del carrito
• No: evento más ligero

Recomendación:

• actívalo solo si esos datos ayudan realmente en el análisis.

Attach Order Context

• Yes: adjunta contexto del pedido
• No: sin datos sobre order flow

Especialmente útil para:

• invoice,
• shipment,
• e-mails transaccionales,
• integraciones ERP / OMS.

Attach Product Context

• Yes: adjunta contexto básico de producto
• No: sin este contexto

Attach Category Context

• Yes: adjunta contexto básico de categoría
• No: sin este contexto

Attach Payment / Shipping Method

• Yes: adjunta payment_method y shipping_method
• No: menos datos para el checkout

Recomendación:

• es una de las configuraciones de diagnóstico más valiosas.

Attach Module Version

• Yes: adjunta la versión de Kowal_Sentry
• No: sin esta información en los eventos

Attach Magento Version

• Yes: adjunta la versión de Magento
• No: sin contexto de plataforma

Attach Deployment Metadata

• Yes: adjunta datos adicionales sobre el deploy si están disponibles
• No: sin estos metadatos

Útil cuando quieres relacionar rápidamente un problema con un rollout o un build concreto.

Sección Source Maps / Release

Esta sección ordena los parámetros necesarios para release y source maps. La propia subida debería realizarse en CI/CD, no durante el runtime de Magento.

Enable Source Map Upload

• Yes: confirma que organizativamente utilizas source maps
• No: el módulo no asume source maps en la configuración

Nota:

• es una flag de configuración, no un mecanismo de subida.

Source Map Upload Mode

Variantes:

• manual: comandos manuales de sentry-cli
• ci: subida en el pipeline CI/CD
• deploy_hook: subida en el hook de deployment

Recomendación:

• en producción, lo más habitual es ci.

Assets Base URL

Ejemplo:

https://store.example.com/static/frontend

Este valor debe corresponder a lo que el Browser SDK ve en el stack trace. De lo contrario, los source maps no se emparejarán.

Release Dist

dist opcional para release.

Ejemplos:

• storefront
• admin
• pl-store

Úsalo cuando un release tiene varias variantes de assets.

Organization

Slug de la organización utilizado por sentry-cli y la API.

Cómo encontrarlo:

• desde la URL del panel de Sentry,
• por ejemplo https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Slug del proyecto utilizado por el workflow de release y source maps.

Cómo encontrarlo:

• desde la URL del proyecto,
• o Settings -> Projects -> [projekt] -> Details

Release File Path

Ruta al archivo con el nombre del release para la estrategia file.

Ejemplos:

• /var/www/shared/release.txt
• pub/media/deploy/release-id.txt

Sección User Feedback

Configuración del widget de reporte de problemas del lado del navegador.

Widget Theme

Variantes:

• light
• dark
• system

Recomendación:

• normalmente system.

Widget Language

Ejemplos:

• pl-PL
• en-US

Recomendación:

• en multistore, ajústalo al locale del store view.

Auto-open after selected errors

• Yes: después de errores frontend seleccionados puede aparecer una propuesta de feedback
• No: el widget no se abre automáticamente

Recomendación:

• úsalo con prudencia para no resultar demasiado agresivo para el usuario.

Show on checkout success

• Yes: el trigger de Feedback puede aparecer en la página de éxito del pedido
• No: sin trigger en este lugar

Show on contact page

• Yes: trigger o widget en la página de contacto
• No: sin exposición en la contact page

Show in footer

• Yes: trigger siempre visible en el footer o como elemento fijo de la página
• No: sin trigger permanente

Es la opción más sencilla si quieres tener un botón Zglos problem.

Custom Trigger Selector

Selector CSS de un elemento existente que abre Feedback.

Ejemplos:

• #report-issue
• .js-sentry-feedback

Utiliza este campo si quieres conectar el widget a tu propio botón en el layout o en un CMS block.

Sección Cron Monitoring

Esta sección controla los check-ins y monitores para los cron de Magento.

Enable auto-registration of configured cron jobs

• Yes: el primer check-in puede crear o actualizar un monitor en Sentry
• No: el módulo envía check-ins sin auto-configuración del monitor

Recomendación:

• Yes si tienes un deployment controlado y jobs definidos conscientemente.

Monitored job codes

Lista de job_code de Magento.

Puedes separarlos con:

• comas,
• espacios,
• saltos de línea.

Variantes:

• campo vacío: monitorizar todos los cron
• lista de job_code seleccionados: monitorizar solo tareas críticas

Ejemplos:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

Una regla por línea:

job_code:minutes

Ejemplo:

catalog_product_alert:10

Úsalo cuando el cron se ejecuta de forma irregular y quieres reducir las falsas alarmas.

Max runtime per job

Una regla por línea:

job_code:minutes

Ejemplo:

indexer_reindex_all_invalid:30

Al superar el límite, Sentry puede marcar el monitor como problemático.

Check-in slug prefix

Ejemplo:

magento-

Útil cuando una organización de Sentry monitoriza varias instancias de Magento y quieres evitar colisiones de nombres.

Perfiles de configuración recomendados

Inicio seguro en producción

• Enable Module = Yes
• Enable Backend Monitoring = Yes
• Enable Frontend Monitoring = Yes
• Error Sample Rate = 1
• Trace Sample Rate = 0.05 o 0.1
• JS Trace Sample Rate = 0.01 o 0.05
• Enable Session Replay = Yes
• JS Replay Session Sample Rate = 0.01
• JS Replay On Error Sample Rate = 1
• Send Default PII = No
• Anonymize IP = Yes
• Mask Customer Data = Yes
• Mask Checkout Fields = Yes
• Mask Payment Fields = Yes
• Block Authorization Headers = Yes
• Block Cookies = Yes
• Block POST Bodies = Yes
• Redact Query Params = Yes
• Ignore Bots = Yes
• Ignore Health Checks = Yes

Perfil de diagnóstico en staging

• Trace Sample Rate más alto, por ejemplo 0.2
• JS Trace Sample Rate más alto, por ejemplo 0.1
• temporalmente Debug Mode = Yes
• Enable Test Commands = Yes
• prudencia con Replay: mantén igualmente el enmascaramiento y los bloqueos

Variante mínima solo backend

• Enable Backend Monitoring = Yes
• Backend DSN completado
• Enable Frontend Monitoring = No

Es un buen primer paso si quieres empezar por activar la monitorización de excepciones y cron del lado PHP.

Errores de configuración más frecuentes

• Pegar el snippet completo \Sentry\init(...) en lugar de solo el DSN.
• Presencia simultánea del módulo en vendor/ y app/code/.
• Valores de release distintos entre eventos y source maps.
• Sampling de Replay demasiado agresivo en producción.
• Desactivar el enmascaramiento de checkout y pagos.
• Dejar un DSN de ejemplo en una configuración activa.

Resumen

Lo más seguro es empezar con la monitorización del backend, una monitorización prudente del frontend y ajustes de privacidad restrictivos. Cuando los datos en Sentry sean estables y legibles, se puede aumentar gradualmente el trace sampling, Replay y el alcance del contexto de negocio.