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
• endereço de e-mail do cliente e token de licença para o repositório Composer Kowal

Instalação

Os comandos abaixo foram copiados de README.md.

Receberá os dados de acesso ao repositório Composer, o endereço de e-mail do cliente e o token de licença, por e-mail após a compra. Também estão disponíveis no painel do cliente depois de iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do 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

• 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, encontrará 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 necessário no ambiente em questão.

Onde obter os dados do Sentry

DSN

Normalmente, encontrará 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:

\Sentry\init([ '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 obtê-lo:

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

Auth token para source maps

Se utilizar sentry-cli, é preferível 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

Depois da 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

Segue-se a descrição das secções individuais, das possibilidades e das variantes de configuração.

Secção General

Esta secção controla a ativação do módulo, o ambiente e a forma de calcular o 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 a partir do qual 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 eventos.

Recomendação:

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

Release Strategy

Variantes disponíveis:

• manual: o release é obtido a partir 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 utilizar:

• manual: quando pretende introduzir o release manualmente, sobretudo como solução de recurso ou em implementações simples
• env: a melhor opção em CI/CD, quando o release é transmitido pelo deployment
• file: adequado quando o deployment grava o identificador da versão num ficheiro partilhado
• generated: bom 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

Utilizado apenas com a estratégia manual.

Exemplo:

magento-store@2.4.7-p1+20260410.1

Recomendação:

• exatamente o mesmo valor deve ser utilizado 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 estiver a diagnosticar a configuração.

Enable Test Commands

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

Recomendação:

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

Secção Backend SDK

Refere-se ao PHP SDK utilizado 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 nem traces para o Sentry

Backend DSN

Este é 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 partilhado.

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 tráfego elevado
• 0.1: ponto de partida razoável
• 0.2: mais dados à custa de maior 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ção,
• comandos de integração personalizados.

Enable Adminhtml Monitoring

• Yes: monitoriza requests 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

Refere-se ao Browser SDK carregado no storefront e, opcionalmente, no painel de administração.

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 o módulo tentar fazer fallback para Backend DSN

Recomendação:

• a prazo, um projeto frontend separado, se quiser ter Issues, Replay e Performance claros.

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 de administração
• 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 ponto de partida 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 uma parte dos erros

Recomendação:

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

Enable Session Replay

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

Recomendação:

• ative em conjunto com uma forte máscara do checkout e dos 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 deixar 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 fixa

Altere apenas quando:

• estiver a fixar a versão do SDK,
• tiver regras CSP próprias,
• utilizar 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 request
• No: política de privacidade mais conservadora

Recomendação:

• geralmente No.

Anonymize IP

• Yes: não transmite o IP completo
• No: mantém o comportamento padrão

Recomendação:

• normalmente Yes.

Mask Customer Data

• Yes: mascara os dados do cliente
• No: menor proteção de 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 o 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 request

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,
• espaços,
• novas linhas.

Replay Mask Selectors

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

Exemplos:

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

Replay Block Selectors

Seletores CSS que devem ser totalmente bloqueados no 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 anexar detalhes dos requests 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 reduz 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 inofensivos,
• 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: esses requests são enviados para o Sentry

Ignore Admin Routes

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

Ignore Static Resource Errors

• Yes: filtra parte dos erros de assets .js e .css
• No: todos os erros deste tipo 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: anexa store_id, store_code, o nome da loja e a moeda
• No: sem este contexto

Recomendação:

• Yes, especialmente em multistore.

Attach Website Context

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

Attach Customer Context

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

Attach Quote Context

• Yes: anexa contexto do carrinho / quote
• No: menos dados para diagnosticar o checkout

Attach Cart Totals

• Yes: anexa os totais do carrinho
• No: evento mais leve

Recomendação:

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

Attach Order Context

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

Especialmente útil para:

• invoice,
• shipment,
• e-mails transacionais,
• integrações ERP / OMS.

Attach Product Context

• Yes: anexa contexto básico do produto
• No: sem este contexto

Attach Category Context

• Yes: anexa contexto básico da categoria
• No: sem este contexto

Attach Payment / Shipping Method

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

Recomendação:

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

Attach Module Version

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

Attach Magento Version

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

Attach Deployment Metadata

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

Útil quando quer 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 ser feito 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 o release.

Exemplos:

• storefront
• admin
• pl-store

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

Organization

Slug da organização utilizado por sentry-cli e pela 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 utilizado 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 comunicação 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:

• utilize com cuidado para não ser demasiado intrusivo 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 permanentemente visível no rodapé ou como elemento fixo da página
• No: sem trigger permanente

Esta é 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

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

Secção Cron Monitoring

Esta secção controla check-ins e monitors para os 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 auto-configuraçã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,
• espaços,
• 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

Utilize quando o cron possa ser executado de forma irregular e quiser reduzir falsos alertas.

Max runtime per job

Uma regra por linha:

job_code:minutes

Exemplo:

indexer_reindex_all_invalid:30

Depois de excedido o limite, o Sentry pode assinalar o monitor como problemático.

Check-in slug prefix

Exemplo:

magento-

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

Perfis de configuração recomendados

Arranque 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
• cuidado com o Replay: mantenha ainda assim as máscaras e os bloqueios

Variante mínima apenas backend

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

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

Erros de configuração mais comuns

• Colar o snippet completo \Sentry\init(...) em vez de apenas o DSN.
• Presença simultânea do módulo em vendor/ e app/code/.
• Valores diferentes de release entre eventos e source maps.
• Sampling de Replay demasiado agressivo em produção.
• Desativação da máscara do checkout e dos pagamentos.
• Deixar o DSN de exemplo numa configuração ativa.

Resumo

O mais seguro é começar pela monitorização do backend, uma monitorização prudente do frontend e configuraçõ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.