GlitchTip + Sentry no Laravel

Guia de instalação e configuração do monitoramento de erros desta aplicação usando o GlitchTip (alternativa open-source compatível com o Sentry) através do pacote oficial sentry/sentry-laravel.

A instância utilizada é: https://glitchtip.etecnologia.com.br/

O GlitchTip é totalmente compatível com o protocolo do Sentry, por isso usamos o pacote oficial do Sentry para Laravel. A única diferença é a URL do DSN, que aponta para o servidor do GlitchTip em vez de sentry.io.

1. Instalação do pacote

Todos os comandos rodam através do Laravel Sail (Docker).

vendor/bin/sail composer require sentry/sentry-laravel

Este projeto já utiliza a versão ^4.26 (ver composer.json).

Em seguida, publique o arquivo de configuração (gera config/sentry.php):

vendor/bin/sail artisan sentry:publish --dsn=<SEU_DSN_DO_GLITCHTIP>

O comando sentry:publish publica a config e já grava a variável SENTRY_LARAVEL_DSN no seu .env. Caso prefira configurar manualmente, pule o --dsn e edite o .env como descrito na seção 4.

2. Criação do projeto no GlitchTip

Acesse https://glitchtip.etecnologia.com.br/ e faça login.
Selecione (ou crie) uma Organização.
No menu lateral, vá em Projects e clique em Create a new project (botão + Create Project).
Em Platform, escolha PHP → Laravel.
Defina o nome do projeto (ex.: logistica) e a equipe responsável.
Clique em Create Project.
Na tela seguinte, o GlitchTip exibe o DSN do projeto. Copie-o — ele tem o formato:
```
https://<CHAVE_PUBLICA>@glitchtip.etecnologia.com.br/<ID_DO_PROJETO>
```
Exemplo já em uso neste ambiente:
```
https://db4b78402ab74387aced6f9c731a4388@glitchtip.etecnologia.com.br/1
```
O DSN também pode ser recuperado depois em Settings → Projects → (seu projeto) → Client Keys (DSN).

3. Configuração no Laravel

O arquivo config/sentry.php é o ponto central. Os valores principais são lidos a partir do .env (não edite o DSN diretamente no config — use o .env). Os campos relevantes:

Chave no config	Origem (.env)	Função
`dsn`	`SENTRY_LARAVEL_DSN`	Endereço do projeto no GlitchTip. Obrigatório.
`send_default_pii`	`SENTRY_SEND_DEFAULT_PII`	Envia dados do usuário/requisição (IP, headers, etc.).
`traces_sample_rate`	`SENTRY_TRACES_SAMPLE_RATE`	Taxa de amostragem de performance (`0.0` a `1.0`).
`environment`	`APP_ENV`	Separa eventos por ambiente (local, production…).

4. Variáveis de ambiente

Adicione ao .env (valores atuais de desenvolvimento):

SENTRY_LARAVEL_DSN=https://db4b78402ab74387aced6f9c731a4388@glitchtip.etecnologia.com.br/1
SENTRY_SEND_DEFAULT_PII=true
SENTRY_TRACES_SAMPLE_RATE=1.0

E em .env.production, preencha com o DSN do projeto de produção (mantenha as chaves presentes no arquivo):

SENTRY_LARAVEL_DSN=
SENTRY_SEND_DEFAULT_PII=
SENTRY_TRACES_SAMPLE_RATE=

Produção: use SENTRY_TRACES_SAMPLE_RATE mais baixo (ex.: 0.2) para reduzir o volume de eventos de performance, e avalie SENTRY_SEND_DEFAULT_PII=false caso não queira enviar dados pessoais (IP, e-mail) ao servidor de erros.

Após alterar o .env, limpe o cache de configuração:

vendor/bin/sail artisan config:clear

5. Integração no código

A instalação neste projeto já contempla três pontos de integração:

5.1. Captura de exceções (`bootstrap/app.php`)

O handler de exceções do Laravel 11 é conectado ao Sentry/GlitchTip:

use Sentry\Laravel\Integration;

->withExceptions(function (Exceptions $exceptions) {
    Integration::handles($exceptions);
})->create();

5.2. Identificação do usuário (`app/Providers/AppServiceProvider.php`)

Anexa o usuário autenticado a cada evento enviado, facilitando rastrear quem encontrou o erro:

use Illuminate\Auth\Events\Authenticated;
use Illuminate\Support\Facades\Event;
use Sentry\Laravel\Integration;
use Sentry\State\Scope;

// Dentro de boot():
Event::listen(function (Authenticated $event) {
    Integration::configureScope(function (Scope $scope) use ($event): void {
        $scope->setUser([
            'id'    => $event->user->getAuthIdentifier(),
            'name'  => $event->user->name ?? null,
            'email' => $event->user->email ?? null,
        ]);
    });
});

5.3. Rota de teste (`routes/web.php`)

Uma rota dispara uma exceção proposital para validar a integração:

Route::get('/teste01', function () {
    throw new Exception('My first GlitchTip error!');
});

Remova ou proteja a rota /teste01 antes de ir para produção.

6. Testando a integração

Suba os containers:
```
vendor/bin/sail up -d
```
Acesse a rota de teste no navegador:
```
http://localhost/teste01
```
A página deve estourar a exceção My first GlitchTip error!.
Abra https://glitchtip.etecnologia.com.br/ → seu projeto → Issues. O erro deve aparecer em alguns segundos, com a mensagem, o stack trace e (se logado) os dados do usuário autenticado.

Alternativamente, via Tinker:

vendor/bin/sail artisan tinker
>>> \Sentry\captureMessage('Teste manual de GlitchTip');

7. Criação do webhook (alertas)

O webhook permite que o GlitchTip notifique sistemas externos (Slack, Discord, Microsoft Teams, n8n, ou um endpoint próprio) quando um novo erro/issue ocorre.

7.1. Configurar no GlitchTip

Em https://glitchtip.etecnologia.com.br/, abra o projeto.
Vá em Settings → Alerts (Regras de alerta do projeto).
Clique em Create New Alert (ou edite uma existente).
Configure as condições do disparo:
- Quantity / Timespan: quantas ocorrências em quanto tempo disparam o alerta (ex.: 1 evento em 1 minuto).
Em Alert Recipients, adicione um recipiente do tipo Webhook (ou General Webhook / Discord / Slack conforme o destino).
Cole a URL do webhook de destino.
- Para Slack/Discord/Teams: use a Incoming Webhook URL gerada na respectiva plataforma.
- Para um endpoint próprio: informe a URL pública que receberá o POST.
Salve.

7.2. Formato do payload

O GlitchTip envia uma requisição POST com Content-Type: application/json. O corpo segue o formato compatível com os webhooks do Sentry/MS Teams, contendo os campos do alerta:

{
  "alias": "GlitchTip",
  "text": "GlitchTip Alert",
  "attachments": [
    {
      "title": "My first GlitchTip error!",
      "title_link": "https://glitchtip.etecnologia.com.br/<org>/issues/<id>",
      "text": "Exception em routes/web.php",
      "color": "#e52b50"
    }
  ],
  "sections": []
}

O formato exato varia conforme o tipo de recipiente escolhido (Slack, Discord, Teams ou webhook genérico). Para integrações customizadas, registre o payload recebido uma vez e ajuste o parser ao formato real.

7.3. Receber o webhook na própria aplicação (opcional)

Caso queira tratar o alerta dentro do Laravel, crie uma rota pública (sem auth) para receber o POST:

// routes/web.php
Route::post('/webhooks/glitchtip', function (\Illuminate\Http\Request $request) {
    \Illuminate\Support\Facades\Log::info('GlitchTip alert', $request->all());

    return response()->json(['ok' => true]);
});

Como o endpoint é público, valide a origem (ex.: um token secreto no path ou header) e garanta que a rota esteja fora dos middlewares de autenticação/permissão (auth, CheckPermissionAccess).

Referências

Pacote: https://github.com/getsentry/sentry-laravel
Documentação Sentry/Laravel: https://docs.sentry.io/platforms/php/guides/laravel/
GlitchTip: https://glitchtip.com/documentation
Instância interna: https://glitchtip.etecnologia.com.br/

GlitchTip + Sentry no Laravel

GlitchTip + Sentry no Laravel

Índice

1. Instalação do pacote

2. Criação do projeto no GlitchTip

3. Configuração no Laravel

4. Variáveis de ambiente

5. Integração no código

5.1. Captura de exceções (bootstrap/app.php)

5.2. Identificação do usuário (app/Providers/AppServiceProvider.php)

5.3. Rota de teste (routes/web.php)

6. Testando a integração

7. Criação do webhook (alertas)

7.1. Configurar no GlitchTip

7.2. Formato do payload

7.3. Receber o webhook na própria aplicação (opcional)

Referências

5.1. Captura de exceções (`bootstrap/app.php`)

5.2. Identificação do usuário (`app/Providers/AppServiceProvider.php`)

5.3. Rota de teste (`routes/web.php`)