Kowal_Sentry: instruções de instalação e configuração

Objetivo do módulo

Kowal_Sentry integra o Magento 2 com o Sentry e permite monitorizar:

• erros de backend PHP,
• erros JavaScript no storefront e, opcionalmente, no painel de administração,
• transações HTTP, CLI e cron,
• checkout breadcrumbs,
• Session Replay,
• User Feedback,
• release tracking e preparação para source maps.

O módulo foi preparado como pacote Composer e deve funcionar a partir da localização vendor/kowal/module-sentry.

Requisitos

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+
• acesso ao Sentry e a pelo menos um projeto
• token GitHub, se o repositório for instalado através de vcs privado

Instalação

Os comandos abaixo foram copiados 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

• O pacote Composer deve funcionar apenas a partir de vendor/kowal/module-sentry.
• Não deve manter simultaneamente o mesmo módulo em app/code/Kowal/Sentry.
• Após a instalação, encontra a configuração em:

Stores -> Configuration -> Kowal -> Sentry

Início rápido

Configuração mínima necessária para iniciar o módulo:

1. Defina Enable Module = Yes.
2. Defina Environment, por exemplo production ou staging.
3. Ative Enable Backend Monitoring e cole o Backend DSN.
4. Se quiser monitorizar o frontend, ative Enable Frontend Monitoring e cole o Frontend DSN.
5. Guarde a configuração e limpe a cache, se for necessário no ambiente em questão.

Onde obter os dados do Sentry

DSN

Normalmente encontra o DSN aqui:

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

Nos campos Backend DSN e Frontend DSN, cole apenas o próprio URL DSN, por exemplo:

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

Não cole o snippet completo:

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

Organization

A forma mais simples de ler o slug da organização é a partir do URL do painel Sentry, por exemplo:

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

Neste exemplo:

• acme é Organization
• shop-frontend é Project Slug

Project Slug

Pode lê-lo:

• a partir do URL do projeto no painel Sentry,
• ou em Settings -> Projects -> [projekt] -> Details

Auth token para source maps

Se usar sentry-cli, o ideal é manter o token fora do Magento, por exemplo numa variável de ambiente:

SENTRY_AUTH_TOKEN

Criação do token:

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

Verificação após a instalação

Após a configuração básica, pode verificar se o módulo está ativo e se o SDK funciona. Os comandos smoke-test abaixo foram copiados de README.md.

Depois de ativar Enable Test Commands:

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

Configuração no painel Magento

Caminho:

Stores -> Configuration -> Kowal -> Sentry

Abaixo encontra a descrição das secções individuais, possibilidades e variantes de configuração.

Secção General

Esta secção controla a ativação do módulo, o ambiente e a forma de calcular release.

Enable Module

• Yes: inicia o módulo globalmente.
• No: o backend e o frontend não serão inicializados, mesmo que outras opções estejam ativadas.

Recomendação:

• Yes no ambiente em que pretende enviar dados para o Sentry.

Environment

Exemplos:

• production
• staging
• development

Variantes:

• um nome comum para toda a instância,
• valores diferentes por website/store view, se precisar de separar os eventos.

Recomendação:

• sem espaços e sem barras,
• mantenha uma nomenclatura constante entre backend, frontend e CI/CD.

Release Strategy

Variantes disponíveis:

• manual: o release vem do campo Release Name Override
• env: o release é obtido a partir das variáveis de ambiente
• file: o release é lido a partir de um ficheiro
• generated: o release é composto automaticamente pelo módulo

Quando usar:

• manual: quando pretende introduzir o release manualmente, mais como solução de emergência ou em implementações simples
• env: melhor em CI/CD, quando o release é transmitido pelo deployment
• file: adequado quando o deployment grava o identificador da versão num ficheiro partilhado
• generated: adequado para começar, se ainda não tiver um pipeline de release maduro

Variáveis de ambiente suportadas:

• KOWAL_SENTRY_RELEASE
• SENTRY_RELEASE
• RELEASE_NAME
• GIT_COMMIT

Release Name Override

Usado apenas com a estratégia manual.

Exemplo:

magento-store@2.4.7-p1+20260410.1

Recomendação:

• exatamente o mesmo valor deve ser usado no upload dos source maps.

Project Name

Nome auxiliar do projeto nos contextos do módulo. Não é o Project Slug do Sentry.

Variantes:

• nome da instância da loja,
• nome do grupo de lojas,
• nome do projeto interno.

Debug Mode

• Yes: logging de diagnóstico mais detalhado
• No: modo de produção

Recomendação:

• No em produção,
• Yes temporariamente, quando está a diagnosticar a configuração.

Enable Test Commands

• Yes: disponibiliza comandos de teste bin/magento
• No: oculta-os na operação normal

Recomendação:

• Yes em staging ou durante os testes,
• No na configuração de produção permanente.

Secção Backend SDK

Diz respeito ao PHP SDK usado por storefront HTTP, admin, API, cron e CLI.

Enable Backend Monitoring

• Yes: ativa a monitorização do backend
• No: o backend não envia erros e traces para o Sentry

Backend DSN

É o DSN principal para o PHP SDK.

Variantes:

• projeto Sentry separado apenas para o backend
• o mesmo projeto para backend e frontend

Recomendação:

• em implementações mais maduras, mantenha projetos separados para backend e frontend,
• em instalações mais pequenas, pode começar com um único projeto comum.

Error Sample Rate

Intervalo: 0-1

Exemplos:

• 1: enviar todos os erros
• 0.5: enviar cerca de metade
• 0.25: enviar cerca de 25%

Recomendação:

• normalmente 1.0 para erros, pelo menos no início.

Trace Sample Rate

Intervalo: 0-1

Exemplos:

• 0.05: sampling baixo, adequado para produção com muito tráfego
• 0.1: ponto de partida razoável
• 0.2: mais dados à custa do volume

Recomendação:

• em produção, normalmente 0.05-0.2, dependendo do tráfego e do plano Sentry.

Profile Sample Rate

Intervalo: 0-1

Variantes:

• 0: profiling desativado
• valor baixo, por exemplo 0.01: diagnóstico periódico de desempenho

Recomendação:

• 0 ou um valor muito baixo em produção.

Enable Logs

• Yes: envia structured logs
• No: sem logs no Sentry

Quando ativar:

• quando quiser correlacionar logs com traces e erros.

Enable Metrics API

• Yes: ativa a fachada do módulo para métricas
• No: as métricas do lado do módulo não estarão ativas

Nota:

• o atual sentry/sentry 4.24.x trata backend metrics como API em descontinuação / no-op.

Enable Cron Monitoring

• Yes: envia check-ins e transações cron
• No: os crons não serão monitorizados pelo Sentry

Encontrará os dados no Sentry na secção:

• Crons
• Monitors

Enable CLI Monitoring

• Yes: monitoriza comandos bin/magento
• No: sem monitorização de processos CLI

Útil para:

• importações,
• reindexações,
• comandos de integração personalizados.

Enable Adminhtml Monitoring

• Yes: monitoriza pedidos do painel de administração
• No: limita o backend ao storefront, API, cron e CLI

Enable API Monitoring

• Yes: monitoriza REST, GraphQL e outros endpoints
• No: exclui a parte de integração da monitorização

Secção Frontend SDK

Diz respeito ao Browser SDK carregado no storefront e, opcionalmente, no painel admin.

Enable Frontend Monitoring

• Yes: carrega o Browser SDK
• No: o frontend não envia dados para o Sentry

Frontend DSN

Variantes:

• projeto frontend separado
• o mesmo DSN que o backend
• campo vazio para que o módulo tente fallback para Backend DSN

Recomendação:

• idealmente, um projeto frontend separado se quiser ter Issues, Replay e Performance mais legíveis.

Enable Storefront JS

• Yes: o Browser SDK funciona no storefront
• No: sem SDK na parte pública da loja

Enable Admin JS

• Yes: o Browser SDK também funciona no painel admin
• No: monitorização JS limitada ao storefront

Recomendação:

• ative apenas quando estiver realmente a diagnosticar problemas JS no admin.

JS Trace Sample Rate

Intervalo: 0-1

Exemplos:

• 0.01: muito cauteloso
• 0.05: bom início para produção
• 0.1: mais dados, maior volume

JS Replay Session Sample Rate

Intervalo: 0-1

Exemplos:

• 0: sem replays completos
• 0.01: início seguro
• 0.05: mais dados para análise de UX e erros

JS Replay On Error Sample Rate

Intervalo: 0-1

Exemplos:

• 1: replay após cada erro na sessão
• 0.5: replay após parte dos erros

Recomendação:

• frequentemente é um melhor ponto de partida do que um sampling elevado de todas as sessões.

Enable Session Replay

• Yes: ativa Replay
• No: sem gravação de sessões

Recomendação:

• ative em conjunto com um forte mascaramento do checkout e pagamentos.

Enable User Feedback Widget

• Yes: o widget Feedback fica disponível
• No: o widget não é carregado

Nota:

• dependendo do plano e da conta Sentry, a funcionalidade pode estar assinalada como beta / experimental.

Enable Checkout Instrumentation

• Yes: adiciona breadcrumbs e tags de checkout
• No: sem contexto adicional de checkout

Recomendação:

• normalmente vale a pena manter ativado.

Enable Ajax Instrumentation

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

Browser SDK CDN URL

Por predefinição, aponta para o bundle oficial do Sentry.

Variantes:

• URL predefinido do módulo
• mirror CDN próprio
• bundle específico / versão específica fixada

Altere apenas quando:

• fixar a versão do SDK,
• tiver regras CSP próprias,
• usar mirror de assets.

Secção Privacy / Security

Esta secção é responsável por minimizar o risco de envio de dados sensíveis.

Send Default PII

• Yes: o SDK pode enviar o conjunto predefinido de dados do utilizador e do pedido
• No: política de privacidade mais conservadora

Recomendação:

• normalmente No.

Anonymize IP

• Yes: não transmitir o IP completo
• No: manter o comportamento padrão

Recomendação:

• normalmente Yes.

Mask Customer Data

• Yes: mascara os dados do cliente
• No: menor proteção dos dados

Recomendação:

• praticamente sempre Yes em produção.

Mask Checkout Fields

• Yes: mascara os campos do checkout
• No: risco de fuga de dados do checkout

Recomendação:

• sempre Yes.

Mask Payment Fields

• Yes: mascara campos relacionados com pagamento
• No: muito arriscado

Recomendação:

• sempre Yes.

Block Authorization Headers

• Yes: remove ou mascara Authorization e tokens
• No: risco de envio de dados de autenticação

Recomendação:

• sempre Yes.

Block Cookies

• Yes: remove cookies dos dados do evento
• No: maior risco de fuga de dados de sessão

Recomendação:

• normalmente Yes.

Block POST Bodies

• Yes: remove corpos POST
• No: envia mais dados do pedido

Recomendação:

• normalmente Yes, especialmente para checkout, login e formulários.

Redact Query Params

• Yes: mascara parâmetros de query string
• No: a query string permanece mais legível, mas menos segura

Additional Redacted Keys

Campo de texto para chaves adicionais a redigir.

Exemplos:

• token
• api_key
• customer_email
• external_customer_id

Pode separar:

• por vírgulas,
• por espaços,
• por novas linhas.

Replay Mask Selectors

Seletores CSS cujo conteúdo deve ser mascarado em Replay.

Exemplos:

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

Replay Block Selectors

Seletores CSS que devem ser totalmente bloqueados em Replay.

Exemplos:

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

Allowed Domains for Replay Network Details

Lista de domínios para os quais o Replay pode incluir detalhes dos pedidos de rede.

Exemplos:

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

Recomendação:

• introduza apenas domínios próprios e de confiança.

Secção Filtering

Esta secção limita o ruído e o volume de eventos.

Ignore Exceptions Regex

Uma regra regex por linha.

Exemplos de utilização:

• erros técnicos conhecidos e não perigosos,
• exceções de integrações externas que já são tratadas de outra forma.

Ignore URLs Regex

Uma regra regex por linha.

Exemplos:

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

Ignore Transactions

Um nome de transação por linha.

Recomendação:

• primeiro recolha dados,
• depois filtre transações de baixo valor e repetitivas.

Ignore Bots

• Yes: exclui tráfego de bots e crawlers
• No: também monitoriza tráfego automático

Recomendação:

• Yes com tráfego SEO elevado.

Ignore Health Checks

• Yes: ignora /health, /status, /ping e semelhantes
• No: estes pedidos chegam ao Sentry

Ignore Admin Routes

• Yes: limita eventos do admin
• No: o admin permanece monitorizado

Ignore Static Resource Errors

• Yes: filtra parte dos erros de assets .js e .css
• No: todos estes erros permanecem visíveis

Recomendação:

• normalmente Yes, se não quiser encher o projeto com ruído após deploys.

Secção Context

Controla a quantidade de contexto de negócio adicionada aos eventos.

Attach Store Context

• Yes: adiciona store_id, store_code, nome da loja e moeda
• No: sem este contexto

Recomendação:

• Yes, especialmente em multistore.

Attach Website Context

• Yes: adiciona dados do website
• No: sem este nível de identificação

Attach Customer Context

• Yes: adiciona contexto anonimizado do cliente
• No: sem dados sobre o estado do cliente

Attach Quote Context

• Yes: adiciona contexto do carrinho / quote
• No: menos dados para diagnóstico do checkout

Attach Cart Totals

• Yes: adiciona totais do carrinho
• No: evento mais leve

Recomendação:

• ative apenas quando esses dados ajudarem realmente na análise.

Attach Order Context

• Yes: adiciona contexto da encomenda
• No: sem dados sobre o order flow

Particularmente útil para:

• invoice,
• shipment,
• emails transacionais,
• integrações ERP / OMS.

Attach Product Context

• Yes: adiciona contexto básico de produto
• No: sem este contexto

Attach Category Context

• Yes: adiciona contexto básico de categoria
• No: sem este contexto

Attach Payment / Shipping Method

• Yes: adiciona payment_method e shipping_method
• No: menos dados para o checkout

Recomendação:

• é uma das definições de diagnóstico mais valiosas.

Attach Module Version

• Yes: adiciona a versão Kowal_Sentry
• No: sem esta informação nos eventos

Attach Magento Version

• Yes: adiciona a versão Magento
• No: sem contexto da plataforma

Attach Deployment Metadata

• Yes: adiciona dados adicionais sobre o deploy, se disponíveis
• No: sem estes metadados

Útil quando pretende associar rapidamente um problema a um rollout ou a uma build específica.

Secção Source Maps / Release

Esta secção organiza os parâmetros necessários para release e source maps. O upload em si deve ocorrer em CI/CD, e não durante o runtime do Magento.

Enable Source Map Upload

• Yes: confirma que, a nível organizacional, utiliza source maps
• No: o módulo não assume source maps na configuração

Nota:

• é uma flag de configuração, não um mecanismo de upload.

Source Map Upload Mode

Variantes:

• manual: comandos manuais sentry-cli
• ci: upload no pipeline CI/CD
• deploy_hook: upload no hook de deployment

Recomendação:

• em produção, mais frequentemente ci.

Assets Base URL

Exemplo:

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

Este valor tem de corresponder ao que o Browser SDK vê no stack trace. Caso contrário, os source maps não serão correspondidos.

Release Dist

dist opcional para release.

Exemplos:

• storefront
• admin
• pl-store

Use quando um release tiver várias variantes de assets.

Organization

Slug da organização usado por sentry-cli e API.

Como encontrar:

• a partir do URL do painel Sentry,
• por exemplo https://sentry.io/settings/acme/projects/shop-frontend/ -> acme

Project Slug

Slug do projeto usado pelo workflow de release e source maps.

Como encontrar:

• a partir do URL do projeto,
• ou Settings -> Projects -> [projekt] -> Details

Release File Path

Caminho para o ficheiro com o nome do release na estratégia file.

Exemplos:

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

Secção User Feedback

Configuração do widget de reporte de problemas no lado do browser.

Widget Theme

Variantes:

• light
• dark
• system

Recomendação:

• normalmente system.

Widget Language

Exemplos:

• pl-PL
• en-US

Recomendação:

• em multistore, ajuste ao locale da store view.

Auto-open after selected errors

• Yes: após erros de frontend selecionados, pode surgir uma proposta de feedback
• No: o widget não abre automaticamente

Recomendação:

• use com cautela, para não ser demasiado agressivo para o utilizador.

Show on checkout success

• Yes: o trigger Feedback pode aparecer na página de sucesso da encomenda
• No: sem trigger neste local

Show on contact page

• Yes: trigger ou widget na página de contacto
• No: sem exposição na contact page

Show in footer

• Yes: trigger sempre visível no rodapé ou como elemento fixo da página
• No: sem trigger permanente

É a opção mais simples se quiser ter um botão Zglos problem.

Custom Trigger Selector

Seletor CSS de um elemento existente que abre o Feedback.

Exemplos:

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

Use este campo se quiser ligar o widget ao seu próprio botão no layout ou num bloco CMS.

Secção Cron Monitoring

Esta secção controla check-ins e monitores para crons Magento.

Enable auto-registration of configured cron jobs

• Yes: o primeiro check-in pode criar ou atualizar um monitor no Sentry
• No: o módulo envia check-ins sem autoconfiguração do monitor

Recomendação:

• Yes, se tiver um deployment controlado e jobs definidos conscientemente.

Monitored job codes

Lista de job_code Magento.

Pode separar:

• por vírgulas,
• por espaços,
• por novas linhas.

Variantes:

• campo vazio: monitorizar todos os crons
• lista de job_code selecionados: monitorizar apenas tarefas críticas

Exemplos:

• sales_clean_quotes
• catalog_product_alert
• indexer_reindex_all_invalid

Timeout threshold per job

Uma regra por linha:

job_code:minutes

Exemplo:

catalog_product_alert:10

Use quando o cron por vezes é executado de forma irregular e pretende limitar falsos alarmes.

Max runtime per job

Uma regra por linha:

job_code:minutes

Exemplo:

indexer_reindex_all_invalid:30

Após exceder o limite, o Sentry pode marcar o monitor como problemático.

Check-in slug prefix

Exemplo:

magento-

Útil quando uma organização Sentry monitoriza várias instâncias Magento e pretende evitar colisões de nomes.

Perfis de configuração recomendados

Início seguro em produção

• Enable Module = Yes
• Enable Backend Monitoring = Yes
• Enable Frontend Monitoring = Yes
• Error Sample Rate = 1
• Trace Sample Rate = 0.05 ou 0.1
• JS Trace Sample Rate = 0.01 ou 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 em staging

• Trace Sample Rate mais elevado, por exemplo 0.2
• JS Trace Sample Rate mais elevado, por exemplo 0.1
• temporariamente Debug Mode = Yes
• Enable Test Commands = Yes
• cautela com Replay: mantenha sempre o mascaramento e os bloqueios

Variante mínima apenas backend

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

É um bom primeiro passo se quiser começar por ativar a monitorização de exceções e crons no lado PHP.

Erros de configuração mais frequentes

• Colar o snippet completo Sentryinit(...) em vez apenas do DSN.
• Presença simultânea do módulo em vendor/ e app/code/.
• Valores diferentes de release entre eventos e source maps.
• Sampling Replay demasiado agressivo em produção.
• Desativar o mascaramento do checkout e pagamentos.
• Deixar um DSN de exemplo na configuração ativa.

Resumo

O mais seguro é começar pela monitorização do backend, monitorização cautelosa do frontend e definições de privacidade restritivas. Quando os dados no Sentry se tornarem estáveis e legíveis, pode aumentar gradualmente o trace sampling, o Replay e o âmbito do contexto de negócio.