LaravelLogsLayer - Captura de Logs de Erro

A biblioteca LaravelLogsLayer permite capturar logs de erros em aplicações Laravel e redirecioná-los para diversos canais, como Discord, E-mail, Logstash e Daily. Essa funcionalidade ajuda no monitoramento e notificação imediata de problemas em ambientes de produção.

Instalação

Para começar a usar esta lib, siga estas etapas:

1. Adicione o repositório da lib ao composer.json de sua aplicação:

 "repositories": [
    // Outros repositórios,
    {
        "type": "git",
        "url": "https://git.ae3tecnologia.com.br/AE3_TECNOLOGIA_OPENSOURCE/laravel-logs-layer.git"
    }
]

2. Instale a biblioteca usando o Composer:

composer require ae3/laravel-logs-layer

Channels Disponíveis e Configuração

Esta biblioteca suporta vários canais de captura de logs. Cada canal requer configuração específica por meio de variáveis de ambiente.

Logstash

Redirecione logs para a classe LogstashLogger. Configuração em config/logging.php:

'channels' => [
    // Outros canais,
    'logstash' => [
        'driver' => 'custom',
        'via' => \Ae3\LaravelLogsLayer\app\Loggers\LogstashLogger::class,
        'host' => env('LOGSTASH_HOST', 'host.docker.internal'),
        'port' => env('LOGSTASH_PORT', 5000),
        'environments' => env('LOGSTASH_ENVIRONMENTS', 'production'),
        'bubble' => true,
        'level' => Logger::DEBUG
        // 'level' => \Monolog\Level::Debug //Para versões mais recentes
    ],
],

Variáveis de Ambiente necessárias:

LOGSTASH_HOST=seu_host_logstash
LOGSTASH_PORT=porta_logstash
LOGSTASH_ENVIRONMENTS=ambientes_ativacao

---

Discord

Redirecione logs para a classe DiscordLogger. Configuração em config/logging.php:

'channels' => [
    // Outros canais,
    'discord' => [
        'driver' => 'custom',
        'via' => \Ae3\LaravelLogsLayer\app\Loggers\DiscordLogger::class,
        'bubble' => false,
        'webhook' => env('DISCORD_LOG_CHANNEL_WEBHOOK'),
        'environments' => env('DISCORD_LOG_CHANNEL_ENVIRONMENTS', 'production'),
        'bubble' => true,
        'level' => Logger::ERROR
    ],
],

Variáveis de Ambiente necessárias:

DISCORD_LOG_CHANNEL_WEBHOOK=webhook_discord
DISCORD_LOG_CHANNEL_ENVIRONMENTS=ambientes_ativacao

---

E-mail

Redirecione logs para a classe EmailLogger. Configuração em config/logging.php:

'channels' => [
    // Outros canais,
    'email' => [
        'driver' => 'custom',
        'via' => \Ae3\LaravelLogsLayer\app\Loggers\EmailLogger::class,
        'subject' => env('APP_NAME') . ' - Error Log',
        'host' => env('MAIL_HOST'),
        'port' => env('MAIL_PORT'),
        'from' => env('MAIL_FROM_ADDRESS'),
        'to' => env('EMAIL_LOG_CHANNEL_TO'),
        'email' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
        'encryption' => env('MAIL_ENCRYPTION'),
        'debug' => env('MAIL_DEBUG', false),
        'environments' => env('EMAIL_LOG_CHANNEL_ENVIRONMENTS', 'production'),
        'bubble' => true,
        'level' => Logger::CRITICAL,
    ],
],

Variáveis de Ambiente necessárias:

APP_NAME=nome_aplicacao
MAIL_HOST=host_email
MAIL_PORT=porta_email
MAIL_FROM_ADDRESS=remetente_email
MAIL_USERNAME=usuario_email
MAIL_PASSWORD=senha_email
MAIL_ENCRYPTION=criptografia_email
MAIL_DEBUG=debug_email (opcional)
EMAIL_LOG_CHANNEL_TO=destinatario_email
EMAIL_LOG_CHANNEL_ENVIRONMENTS=ambientes_ativacao

---

É possível habilitar mais de um canal para envio de logs. Para isso, basta adicionar à entrada channels de stack, os canais desejados em config/logging.php:

'stack' => [
    'driver' => 'stack',
    'channels' => ['email', 'discord', 'logstash'],
    'ignore_exceptions' => false,
],  

No exemplo acima, os logs serão enviados para os canais de e-mail, Discord e Logstash.

Você também pode adicionar uma variável de ambiente chamada LOG_STACK_CHANNELS com os nomes dos canais que você deseja ativar, separados por vírgula. Exemplo:

'stack' => [
    'driver' => 'stack',
    'channels' => explode(',', env('LOG_STACK_CHANNELS', 'daily')),
    'ignore_exceptions' => false,
]

LOG_STACK_CHANNELS=logstash,email

O exemplo acima, os logs serão enviados para os canais logstash e email que estão no .env.

Uso

Para disparar um log de erro, utilize a trait LogTrait em suas classes. Certifique-se de configurar as variáveis de ambiente relevantes para o canal escolhido.

Exemplo:

use Ae3\LaravelLogsLayer\app\Traits\LogTrait;

class MyClass
{
    use LogTrait;

    public function myMethod()
    {
        try {
            // Código que pode gerar um erro
        } catch (Exception $e) {
            $loggedExceptionDTO = $this->logException(__METHOD__, $e);
        }
    }
}

No caso do método logException, o primeiro parâmetro é o nome do método que está chamando o log, o segundo parâmetro é a exceção que foi capturada e o terceiro parâmetro é o nível do log (opcional, padrão: error). Existem três níveis de log: error, critical e emergency.

O retorno do método logException é um objeto do tipo LoggedExceptionDTO. Esse objeto contém informações sobre o log que foi capturado, como o código do log, o nível do log, o nome do método que chamou o log, a mensagem de erro, o stack trace, entre outros.

Você pode utilizar essas informações para exibir uma mensagem de erro amigável para o usuário ou para registrar o log em um banco de dados, por exemplo.

Como saber qual nível de log de erro utilizar?

1. Emergency: O nível de log emergency é o mais alto em termos de gravidade. Ele deve ser usado para situações em que ocorrem erros graves que requerem intervenção imediata, uma vez que podem representar uma interrupção crítica ou completa do funcionamento da aplicação. Exemplos incluem falhas graves de infraestrutura, perda de conexão com bancos de dados essenciais, falhas de segurança críticas, entre outros.
2. Critical: O nível critical é usado para erros críticos que também requerem atenção urgente, embora possam não ser tão catastróficos quanto os eventos de emergência. Esses erros têm um impacto significativo na operação da aplicação e exigem uma investigação e correção imediatas. Um exemplo de uso seria quando uma funcionalidade vital da aplicação falha, mas a aplicação ainda consegue continuar operando em um modo limitado.
3. Error: O nível error é um nível de gravidade menor em comparação com os anteriores. Ele é usado para registrar erros que ocorrem na aplicação, mas não são tão críticos a ponto de interromper completamente o funcionamento da aplicação. Erros desse tipo não impedem a aplicação de continuar operando, mas ainda assim precisam ser corrigidos para evitar problemas futuros ou impactos negativos nos usuários. Exemplos podem incluir erros de validação de entrada, erros de banco de dados não críticos, falhas de autenticação, entre outros.

Outros tipos de log fornecidos por LogTrait

A trait LogTrait fornece uma série de outros métodos para simplificar a captura de logs que não sejam erros.

• logInfo(string $message, array $customData = []): Captura um log de informação.
• logNotice(string $message, array $customData = []): Captura um log de aviso.
• logWarning(string $message, array $customData = []): Captura um log de advertência.
• logDebug(string $message, array $customData = []): Captura um log de depuração.
• logAlert(string $message, array $customData = []): Captura um log de alerta.

Dica importante

Algumas informações são capturadas automaticamente pela biblioteca e incluídas no log. Essas informações são:

• Usuário logado (se houver).
• URL atual (se houver).
• SQL executado (se houver).
• Guzzle request (se houver).

Para capturar o Guzzle request, é necessário utilizar o middleware GuzzleLoggingMiddleware fornecido pela biblioteca. Segue abaixo um exemplo:

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Client;
use Ae3\LaravelLogsLayer\app\Middlewares\GuzzleLoggingMiddleware;

$handlerStack = HandlerStack::create(new CurlHandler());
$handlerStack->push(new GuzzleLoggingMiddleware(), 'logger');

$clientOptions['handler'] = $handlerStack;
$client = new Client($clientOptions);

Você também pode incluir informações que você julgar importantes para a análise do log. Para isso, utilize o parâmetro $customData dos métodos de log. Esse parâmetro deve ser um array associativo, onde a chave é o nome do campo e o valor é o valor do campo. Exemplo:

$this->logException(__METHOD__, $e, 'error', [
    'info1' => $info1,
    'info2' => $info2
]);

Escondendo dados sensíveis em capturas do Guzzle

Se você estiver usando o Guzzle para fazer requisições HTTP, é possível esconder dados sensíveis que podem estar presentes no corpo da requisição. Por padrão, a biblioteca esconde os campos abaixo:

• password,
• password_confirmation,
• token,
• api_token,
• api_key,
• access_token,
• refresh_token,
• authorization_code
• client_secret

Você pode adicionar outros campos que desejar. Para isso, basta adicionar uma variável de ambiente chamada LOGS_LAYER_SENSITIVE_DATA com os nomes dos campos que você deseja esconder, separados por vírgula. Exemplo:

LOGS_LAYER_SENSITIVE_DATA=card,credit_card

Essa variável de ambiente irá sobrescrever os campos padrão.

---

Contribuições e Licença

Contribuições para esta biblioteca são bem-vindas! Sinta-se à vontade para contribuir com melhorias, correções de bugs ou novos recursos por meio de pull requests no repositório oficial: https://git.ae3tecnologia.com.br/AE3_TECNOLOGIA_OPENSOURCE/laravel-logs-layer

Esta biblioteca é licenciada sob LICENCE.