DEV Community

Diogo Antunes
Diogo Antunes

Posted on

2. Logs

#programming #learning #php #observability

O que são logs?

Logs, são uma parte importante da Observabilidade, que servem para nos permitir entender o estado do sistema ao analisar os dados que são gerados por meio deles.

Os logs geralmente são eventos e erros que ocorrem em um sistema, bons exemplo são Logs de erros, logins e configurações do sistema.

O que logs registram?

Logs geralmente registram

  • Horário de execução;
  • Identificadores de execução (identificadores, referencias de entidades como “ids”);
  • Endereço de quem realizou a ação/fluxo (IP);
  • Demais detalhes de evento (login, logout, registro, exclusão);
  • Demais detalhes de erros (mensagens, códigos, trace de exceptions).

Como os logs são gerados?

Logs são gerados automaticamente por aplicações ao serem executados comandos predefinidos.

Quais são as limitações dos logs?

A principal limitação dos Logs é depender de uma pre configuração para que sejam realizados esses registros. Por conta disso, acabam sendo limitados a registrar uma ação por vez, sendo Erros, Debugs, Eventos, Ações.

Boas Práticas na Geração de Logs

Estrutura e formato

  • Mantenha um padrão consistente de formatação em toda a aplicação
  • Inclua timestamp em formato padronizado
  • Utilize IDs de correlação para rastrear requisições através de diferentes serviços

Níveis de Log

  • ERROR: Use para falhas que precisam de atenção imediata
  • WARN: Para situações potencialmente prejudiciais
  • INFO: Para eventos significativos do negócio
  • DEBUG: Para informações detalhadas úteis durante o desenvolvimento

Conteúdo

  • Evite dados sensíveis (senhas, tokens, dados pessoais)
  • Inclua contexto suficiente para entender o problema
  • Use mensagens descritivas e acionáveis
  • Registre stacktraces completos para erros
  • Siga regulamentações de privacidade (GDPR, LGPD)
  • Não registre informações duplicadas
  • Não use logs para métricas de negócio

Como podemos monitorar logs?

É possível utilizar de softwares específicos para monitamento de logs. Alguns exemplos são:

  • Grafana Loki;
  • Scalyr
  • Logstash

Também é possível fazer o monitoramento e gerenciamento dos Logs utilizando alguns conjuntos de ferramentas:

  • Grafana Loki + Grafana dashboards;
  • Elasticsearch, Logstash e Kibana (Stack ELK);
  • Graylog (Gerenciamento de Logs);
  • Splunk (Gerenciamento de Logs);
  • Loggly (Gerenciamento de Logs);
  • Sumo Logic (Gerenciamento de Logs).

Aplicação prática de logs com PHP + Monolog

Para a representação prática de Logs foi decidido por se utilizar da linguagem PHP em conjunto de uma biblioteca muito popular para a criação de Logs, o Monolog, que implementa uma interface definida como PSR-3.

Para essa implementação, será utilizado uma runtime do PHP 8.3 no sistema operacional alpine-linux, por meio de um container Docker.

Utilizaremos também um software chamado Composer, ele servirá para gerenciar as dependencias da nossa aplicação de teste, com ele será possível baixar e importar mais facilmente o pacote Monolog.

Inicio da aplicação

Para iniciarmos, será necessário criar um arquivo Dockerfile e salvar o seguinte conteúdo dentro dele

Dockerfile

FROM php:8.3-alpine

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

LABEL authors="haaragard"

WORKDIR /var/www/app
Enter fullscreen mode Exit fullscreen mode

(C.01) Para realizarmos o build da imagem definida no arquivo Dockerfile é necessário executar o seguinte comando:

docker image build . -t php-fiddle
Enter fullscreen mode Exit fullscreen mode
  • Este realizará a build da nossa imagem definida no arquivo Dockerfile(O arquivo Dockerfile precisa estar no mesmo contexto de execução, por isso o ponto “.”).
  • O comando image build . serve para realizar o build da nossa imagem Docker pre-definida no arquivo Dockerfile.
  • A flag -t php-fiddle serve para nomearmos a nossa imagem como php-fiddle , poderíamos adiconar alguma “versão” acrescentando um texto :my-version juntamente do php-fiddle , porém queremos criar apenas um nome não versionado.

(C.02) Para executar um container com a nossa imagem com o build já realizado:

docker run --rm -it -v $PWD:/var/www/app php-fiddle sh
Enter fullscreen mode Exit fullscreen mode
  • Este comando executará o nosso container php-fiddle , e iniciará rodando o terminal sh
  • A flag --rm serve para remover o container logo após o fim da execução do comando (como vamos utilizar o terminal de forma interativa (-it … sh), ele ficará preso até o fim da execução do terminal.
  • A flag -itserve para executar o comando final de forma interativa com o terminal do host.
  • A flag -vserve para fazer um “vinculo” de storages, com o conteúdo $PWD:/var/www/app é feito o vínculo da nossa pasta de execução($PWD) com o caminho /var/www/app .

(C.03) Para executar algum script específico sem “prender” o terminal, é possível com o comando:

docker run --rm -v $PWD:/var/www/app php-fiddle {some-script}
Enter fullscreen mode Exit fullscreen mode
  • Este comando executará o script {some-script} dentro do container php-fiddle contendo os arquivos do contexto atual.

Definindo nossas dependencias

Para iniciarmos o desenvolvimento, precisamos configurar a nossa aplicação com o Composer, que precisa ser configurado com algumas definições, escopos e dependencias(caso utilizados, no nosso caso será o monolog)

(Os passos a seguir serão realizados dentro do container, após executar o comando C.02)

Vamos iniciar a configuração do nosso projeto com o Composer

composer init -n --name php/fiddle
Enter fullscreen mode Exit fullscreen mode
  • O comando composer init fará a criação do nosso projeto com o Composer
  • A flag -n fará com que seja uma criação sem mais opções interativas com o terminal.
  • A flag --name com o conteúdo php/fiddle nomeará nosso projeto como php/fiddle

Também será necessário definir e baixar as dependências, que será apenas o monolog

composer require monolog/monolog
Enter fullscreen mode Exit fullscreen mode
  • O comando composer require fará a inclusão de uma biblioteca às nossas dependencias Composer.

Criando o arquivo main.php

Deverá ser criado o arquivo main.php com o seguinte conteúdo

main.php

<?php

require_once "vendor/autoload.php";

$log = new \Monolog\Logger(name: 'logger-name');
$streamHandler = new \Monolog\Handler\StreamHandler(
    stream: STDOUT,
    level: \Monolog\Level::Warning
);
$log->pushHandler(handler: $streamHandler);

$log->warning(
    message: 'Foo',
    context: [
        'bar' => 'baz',
        'some' => 'more',
        'context' => 'data',
    ]
);
$log->error(message: 'Bar');
Enter fullscreen mode Exit fullscreen mode
  • O código a cima irá produzir 2 Logs no terminal, o primeiro Log será do tipo warning e o segundo será do tipo error.
  • O comando require_once realizará a inclusão das configurações e bibliotecas gerenciadas pelo Composer.
  • Os demais comandos são para a instância do nosso Logger, configuração e produção de registros.
  • Na definição do StreamHandler é possível definir outra saída de texto, em vez do terminal, para que seja registrado em um local, como um arquivo log_register.log.
  • O arquivo base de exemplo para este código se encontra em monolog - README

Execução e logs

Executaremos o nosso código da seguinte forma

php main.php
Enter fullscreen mode Exit fullscreen mode

Após a execução, será visível a seguinte saída no terminal

/var/www/app # php main.php
[2025-04-06T21:31:37.326611+00:00] logger-name.WARNING: Foo {"bar":"baz","some":"more","context":"data"} []
[2025-04-06T21:31:37.326965+00:00] logger-name.ERROR: Bar [] []
Enter fullscreen mode Exit fullscreen mode

Vemos que a biblioteca monolog já produz nossos logs com um certo padrão, contendo [{date_time_tz}] {logger_name}.{logger_level}: {log_message} {context_from_array_to_json} {other_data} .

Considerando o resultado, é perceptível que Logs realizam uma parte importante no registro de eventos em tempo de execução, esses eventos podem ser uma execução de fluxo dentro da aplicação garantindo o funcionamento, até erros inesperados ou debugs.

Com isso, finalizamos o estudo de Logs, tendo um exemplo demonstrativo desta prática tão importante do uso de Logs.

Top comments (0)