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 debe 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
• token GitHub, si el repositorio se instala mediante un vcs privado

Instalación

Los siguientes comandos se han copiado de README.md.

composer config repositories.sentry vcs https://github.com/kowalco/sentrycomposer config --global --auth github-oauth.github.com composer require kowal/module-sentrybin/magento module:enable Kowal_Sentrybin/magento setup:upgradebin/magento cache:flush

Importante

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

Stores -> Configuration -> Kowal -> Sentry

Inicio rápido

Configuración mínima necesaria para iniciar el módulo:

1. Establezca Enable Module = Yes.
2. Establezca Environment, por ejemplo production o staging.
3. Active Enable Backend Monitoring y pegue Backend DSN.
4. Si desea monitorizar el frontend, active Enable Frontend Monitoring y pegue Frontend DSN.
5. Guarde la configuración y limpie la caché si es necesario en el entorno correspondiente.

De dónde obtener los datos de Sentry

DSN

Normalmente encontrará el DSN aquí:

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

En los campos Backend DSN y Frontend DSN debe pegar solo la URL DSN, por ejemplo:

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

No pegue el snippet completo:

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

Organization

La forma más sencilla de obtener el slug de la organización es desde 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

Puede obtenerlo:

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

Auth token para source maps

Si utiliza sentry-cli, es mejor 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 tras la instalación

Después de la configuración básica, puede comprobar si el módulo está activo y si el SDK funciona. Los comandos 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 describe cada sección, sus posibilidades 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: inicia el módulo de forma global.
• No: backend y frontend no se inicializarán, aunque otras opciones estén activadas.

Recomendación:

• Yes en el entorno desde el que desea 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 necesita separar eventos.

Recomendación:

• sin espacios ni barras,
• mantenga 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 es compuesto automáticamente por el módulo

Cuándo usar:

• manual: cuando desea introducir el release manualmente, más bien de forma excepcional o en implementaciones sencillas
• env: lo mejor en CI/CD, cuando el release se transmite durante el deployment
• file: adecuado cuando el deployment guarda el identificador de versión en un archivo compartido
• generated: adecuado para empezar, si todavía no dispone de un pipeline de release maduro

Variables de entorno admitidas:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Se usa solo con la estrategia manual.

Ejemplo:

magento-store@2.4.7-p1+20260410.1

Recomendación:

• exactamente el mismo valor debe usarse al subir 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 diagnostique la configuración.

Enable Test Commands

• Yes: habilita 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 permanente de producción.

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 básico para PHP SDK.

Variantes:

• proyecto Sentry separado solo para backend
• el mismo proyecto para backend y frontend

Recomendación:

• en implementaciones más maduras, mantenga proyectos separados para backend y frontend,
• en instalaciones más pequeñas se puede empezar con un único proyecto común.

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 inicio.

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 del volumen

Recomendación:

• en producción normalmente 0.05-0.2, dependiendo del tráfico y del 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 desea 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:

• el actual sentry/sentry 4.24.x trata backend metrics como API en desuso / no-op.

Enable Cron Monitoring

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

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

• Crons
• Monitors

Enable CLI Monitoring

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

Útil para:

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

Enable Adminhtml Monitoring

• Yes: monitoriza requests del panel de administración
• No: limita el backend al 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 administración.

Enable Frontend Monitoring

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

Frontend DSN

Variantes:

• proyecto de frontend separado
• 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 de frontend separado si desea tener Issues, Replay y Performance claros.

Enable Storefront JS

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

Enable Admin JS

• Yes: Browser SDK también funciona en el panel de administración
• No: monitorización JS limitada al storefront

Recomendación:

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

JS Trace Sample Rate

Rango: 0-1

Ejemplos:

• 0.01: muy prudente
• 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 tras cada error en la sesión
• 0.5: replay tras una parte de los errores

Recomendación:

• a menudo es un 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ívelo junto con un enmascaramiento fuerte del checkout y los 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 etiquetas 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 concreto / versión concreta fijados

Cámbielo solo cuando:

• fije la versión del SDK,
• tenga reglas CSP propias,
• utilice 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:

• por lo general No.

Anonymize IP

• Yes: no transmitir 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 campos del checkout
• No: riesgo de fuga de datos del checkout

Recomendación:

• siempre Yes.

Mask Payment Fields

• Yes: enmascara 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 cuerpos POST
• No: envía más datos del request

Recomendación:

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

Redact Query Params

• Yes: enmascara parámetros query string
• No: el query string queda más legible, pero es menos seguro

Additional Redacted Keys

Campo de texto para claves adicionales que se deben redactar.

Ejemplos:

• token
• api_key
• customer_email
• external_customer_id

Puede separarlas por:

• 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:

• introduzca 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 críticos,
• excepciones de integraciones externas que ya se gestionan de otra forma.

Ignore URLs Regex

Una regla regex por línea.

Ejemplos:

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

Ignore Transactions

Un nombre de transacción por línea.

Recomendación:

• primero recopile datos,
• después filtre las transacciones de bajo valor y repetitivas.

Ignore Bots

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

Recomendación:

• Yes con mucho tráfico SEO.

Ignore Health Checks

• Yes: omite /health, /status, /ping y similares
• No: esos requests llegan a Sentry

Ignore Admin Routes

• Yes: limita eventos del admin
• No: el admin permanece 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 desea llenar el proyecto de ruido tras deploys.

Sección Context

Controla la cantidad de contexto de negocio que se añade a los eventos.

Attach Store Context

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

Recomendación:

• Yes, especialmente con multistore.

Attach Website Context

• Yes: adjunta datos del 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ívelo solo cuando estos datos realmente ayuden en el análisis.

Attach Order Context

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

Especialmente útil para:

• invoice,
• shipment,
• emails transaccionales,
• integraciones ERP / OMS.

Attach Product Context

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

Attach Category Context

• Yes: adjunta contexto básico de la 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 uno de los ajustes de diagnóstico más valiosos.

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 la plataforma

Attach Deployment Metadata

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

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

Sección Source Maps / Release

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

Enable Source Map Upload

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

Nota:

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

Source Map Upload Mode

Variantes:

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

Recomendación:

• en producción, normalmente ci.

Assets Base URL

Ejemplo:

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

Este valor debe corresponder a lo que 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

Úselo cuando un release tenga varias variantes de assets.

Organization

Slug de la organización utilizado por sentry-cli y 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 en el 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ústelo al locale del store view.

Auto-open after selected errors

• Yes: tras determinados errores de frontend puede aparecer una propuesta de feedback
• No: el widget no se abre automáticamente

Recomendación:

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

Show on checkout success

• Yes: el trigger 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 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 desea tener un botón Zglos problem.

Custom Trigger Selector

Selector CSS de un elemento existente que abre Feedback.

Ejemplos:

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

Use este campo si desea vincular el widget a un botón propio en el layout o en un bloque CMS.

Sección Cron Monitoring

Esta sección controla check-ins y monitores para crons 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 autoconfiguración del monitor

Recomendación:

• Yes, si tiene un deployment controlado y jobs definidos de forma consciente.

Monitored job codes

Lista de job_code de Magento.

Puede separarlos por:

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

Variantes:

• campo vacío: monitorizar todos los crons
• 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

Úselo cuando el cron se ejecute de forma irregular y quiera reducir falsas alarmas.

Max runtime per job

Una regla por línea:

job_code:minutes

Ejemplo:

indexer_reindex_all_invalid:30

Después de superar el límite, Sentry puede marcar el monitor como problemático.

Check-in slug prefix

Ejemplo:

magento-

Útil cuando una organización Sentry monitoriza varias instancias Magento y desea 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 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: mantenga 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 desea empezar por activar la monitorización de excepciones y crons del lado PHP.

Errores de configuración más frecuentes

• Pegar el snippet completo Sentryinit(...) en lugar del DSN solo.
• Presencia simultánea del módulo en vendor/ y app/code/.
• Valores diferentes de release entre eventos y source maps.
• Sampling 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 monitorización del backend, 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.