Kowal_Sentry: instrucciones de instalación y configuración

Objetivo del módulo

Kowal_Sentryintegra Magento 2 con Sentry y permite monitorizar:

• errores del backend PHP,
• errores JavaScript en 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ónvendor/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 Kowal

Instalación

Los siguientes comandos se han copiado deREADME.md.

Recibirás por e-mail los datos de acceso al repositorio Composer, dirección de e-mail del cliente y token de licencia, tras 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 correo electrónico 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.store
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
composer require kowal/module-sentry
bin/magento module:enable Kowal_Sentry
bin/magento setup:upgrade
bin/magento cache:flush

Importante

• El paquete Composer debe funcionar únicamente desdevendor/kowal/module-sentry.
• No se debe mantener simultáneamente el mismo módulo enapp/code/Kowal/Sentry.
• Tras 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. ConfiguraEnable Module = Yes.
2. ConfiguraEnvironmentmás alto, por ejemploproductionostaging.
3. ActivaEnable Backend Monitoringy pegaBackend DSN.
4. Si quieres monitorizar el frontend, activaEnable Frontend Monitoringy pegaFrontend DSN.
5. Guarda la configuración y limpia la caché si es necesario en el entorno correspondiente.

Dónde obtener los datos de Sentry

DSN

Normalmente encontrarás el DSN aquí:

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

En los camposBackend DSNyFrontend DSN pega solo la URL 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 leer 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:

• acmeesOrganization
• shop-frontendesProject Slug

Project Slug

Puedes leerlo:

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

Auth token para source maps

Si usassentry-cli, lo mejor es mantener el token fuera de Magento, por ejemplo en una variable de entorno:

SENTRY_AUTH_TOKEN

Creación del token:

• Settings -> Custom Integrations
• oUser Settings -> Personal Tokens

Verificación tras 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 smoke-test siguientes se han copiado deREADME.md.

Tras activarEnable Test Commands:

bin/magento kowal:sentry:test:error
bin/magento kowal:sentry:test:transaction
bin/magento kowal:sentry:test:checkin
bin/magento kowal:sentry:test:log

Configuración en el panel de Magento

Ruta:

Stores -> Configuration -> Kowal -> Sentry

A continuación se describen las secciones, 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 calcularrelease.

Enable Module

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

Recomendación:

• Yesen el entorno desde el que quieres enviar datos a Sentry.

Environment

Ejemplos:

• production
• staging
• development

Variantes:

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

Recomendación:

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

Release Strategy

Variantes disponibles:

• manual: la release procede del campoRelease Name Override
• env: la release se obtiene de variables de entorno
• file: la release se lee desde un archivo
• generated: la release se compone automáticamente mediante el módulo

Cuándo usar:

• manual: cuando quieres introducir la release manualmente, más bien de forma excepcional o en despliegues sencillos
• env: la mejor opción en CI/CD, cuando la release se transmite durante el deployment
• file: adecuada cuando el deployment guarda el identificador de versión en un archivo compartido
• generated: buena para empezar si todavía no tienes un pipeline de release maduro

Variables de entorno compatibles:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Se usa solo con la estrategiamanual.

Ejemplo:

magento-store@2.4.7-p1+20260410.1

Recomendación:

• debe usarse exactamente el mismo valor al subir source maps.

Project Name

Nombre auxiliar del proyecto en los contextos del módulo. No es elProject Slugde Sentry.

Variantes:

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

Debug Mode

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

Recomendación:

• Noen producción,
• Yestemporalmente cuando diagnosticas la configuración.

Enable Test Commands

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

Recomendación:

• Yesen staging o durante las pruebas,
• Noen 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 independiente solo para backend
• el mismo proyecto para backend y frontend

Recomendación:

• en implantaciones más maduras, mantén 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:

• normalmente1.0para errores, al menos al principio.

Trace Sample Rate

Rango:0-1

Ejemplos:

• 0.05: sampling bajo, adecuado en 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 normalmente0.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 ejemplo0.01: diagnóstico periódico de rendimiento

Recomendación:

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

• actualmentesentry/sentry 4.24.xtrata backend metrics como API en retirada /no-op.

Enable Cron Monitoring

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

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

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitoriza comandosbin/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 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 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 frontend independiente
• el mismo DSN que backend
• campo vacío para que el módulo intente fallback aBackend DSN

Recomendación:

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

Enable Storefront JS

• Yes: Browser SDK funciona en 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 a storefront

Recomendación:

• actívalo solo cuando realmente diagnostiques problemas JS en 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 replay completos
• 0.01: inicio seguro
• 0.05: más datos para análisis UX y errores

JS Replay On Error Sample Rate

Rango:0-1

Ejemplos:

• 1: replay tras cada error de 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ívalo junto con un enmascaramiento sólido 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 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 concreto / versión concreta fijada

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

• normalmenteNo.

Anonymize IP

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

Recomendación:

• normalmenteYes.

Mask Customer Data

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

Recomendación:

• prácticamente siempreYesen producción.

Mask Checkout Fields

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

Recomendación:

• siempreYes.

Mask Payment Fields

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

Recomendación:

• siempreYes.

Block Authorization Headers

• Yes: elimina o enmascaraAuthorizationy tokens
• No: riesgo de envío de datos de autenticación

Recomendación:

• siempreYes.

Block Cookies

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

Recomendación:

• normalmenteYes.

Block POST Bodies

• Yes: elimina cuerposPOST
• No: envía más datos del request

Recomendación:

• normalmenteYes, especialmente para checkout, login y formularios.

Redact Query Params

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

Additional Redacted Keys

Campo de texto para claves adicionales que deben redactarse.

Ejemplos:

• token
• api_key
• customer_email
• external_customer_id

Puedes separarlos:

• con comas,
• con espacios,
• con líneas nuevas.

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 e inofensivos,
• 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 recopila datos,
• después filtra transacciones de poco valor y repetitivas.

Ignore Bots

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

Recomendación:

• Yescon mucho tráfico SEO.

Ignore Health Checks

• Yes: omite/health,/status,/pingy similares
• No: estos requests llegarán a Sentry

Ignore Admin Routes

• Yes: limita eventos del admin
• No: admin permanece monitorizado

Ignore Static Resource Errors

• Yes: filtra parte de los errores de assets.jsy.css
• No: todos los errores de este tipo permanecen visibles

Recomendación:

• normalmenteYessi no quieres llenar el proyecto de ruido tras los deploys.

Sección Context

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

Attach Store Context

• Yes: adjuntastore_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 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,
• 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: adjuntapayment_methodyshipping_method
• No: menos datos para checkout

Recomendación:

• es uno de los ajustes de diagnóstico más valiosos.

Attach Module Version

• Yes: adjunta la versión deKowal_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 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 subida debe 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 presupone 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 manualessentry-cli
• ci: subida en pipeline CI/CD
• deploy_hook: subida en hook de deployment

Recomendación:

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

Assets Base URL

Ejemplo:

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

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

Release Dist

Opcionaldistopcional para release.

Ejemplos:

• storefront
• admin
• pl-store

Úsalo cuando una release tenga varias variantes de assets.

Organization

Slug de la organización utilizado porsentry-cliy API.

Cómo encontrarlo:

• desde la URL del panel de Sentry,
• por ejemplohttps://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,
• oSettings -> Projects -> [projekt] -> Details

Release File Path

Ruta al archivo con el nombre de la release para la estrategiafile.

Ejemplos:

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

Sección User Feedback

Configuración del widget de notificación de problemas en el lado del navegador.

Widget Theme

Variantes:

• light
• dark
• system

Recomendación:

• normalmentesystem.

Widget Language

Ejemplos:

• pl-PL
• en-US

Recomendación:

• en multistore, ajústalo 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:

• úsalo 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 visible de forma permanente 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ónZglos problem.

Custom Trigger Selector

Selector CSS de un elemento existente que abre Feedback.

Ejemplos:

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

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

Sección Cron Monitoring

Esta sección controla check-ins y monitores para los 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:

• Yessi tienes un deployment controlado y jobs definidos conscientemente.

Monitored job codes

Lista dejob_codede Magento.

Puedes separarlos:

• con comas,
• con espacios,
• con líneas nuevas.

Variantes:

• campo vacío: monitorizar todos los crons
• lista dejob_codeseleccionados: 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 un cron se ejecuta de forma irregular y quieres limitar falsas alarmas.

Max runtime per job

Una regla por línea:

job_code:minutes

Ejemplo:

indexer_reindex_all_invalid:30

Tras 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 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.05o0.1
• JS Trace Sample Rate = 0.01o0.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

• más altosTrace Sample Ratemás alto, por ejemplo0.2
• más altosJS Trace Sample Ratemás alto, por ejemplo0.1
• temporalmenteDebug Mode = Yes
• Enable Test Commands = Yes
• prudencia con Replay: mantén igualmente enmascaramiento y bloqueos

Variante mínima solo backend

• Enable Backend Monitoring = Yes
• Backend DSNcompletado
• Enable Frontend Monitoring = No

Es un buen primer paso si primero quieres poner en marcha la monitorización de excepciones y crons del lado PHP.

Errores de configuración más frecuentes

• Pegar todo el snippet\Sentry\init(...)en lugar del DSN solo.
• Presencia simultánea del módulo envendor/yapp/code/.
• Valores distintos dereleaseentre eventos y source maps.
• Sampling de Replay demasiado agresivo en producción.
• Desactivar el enmascaramiento del checkout y los pagos.
• Dejar el 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 se vuelvan estables y legibles, se puede aumentar gradualmente el trace sampling, Replay y el alcance del contexto de negocio.