2. Logs

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 são eventos e erros que ocorem 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 (identificados, 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 detalhe 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 eu decidi utilizar a linguagem PHP em conjunto de uma biblioteca muito utilizada 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 (C.01) Para realizarmos o build da imagem definida no arquivo Dockerfile é necessário executar o seguinte comando: docker image build . -t php-fiddle 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 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} 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

Apr 6, 2025 - 23:42

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 são eventos e erros que ocorem 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 (identificados, 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 detalhe 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 eu decidi utilizar a linguagem PHP em conjunto de uma biblioteca muito utilizada 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

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

docker image build . -t php-fiddle

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

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}

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

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

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



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');

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

Enquanto executando o container, vamos realizar a execução do nosso código da seguinte forma

php main.php

A execução deverá ser parecido com a seguinte saída

/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 [] []

Podemos ver 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} .

Podemos ver que os 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, com o exemplo demonstrativo da utilização.

Ref. 1 - Ferramentas para gerenciamento de logs
Ref. 2 - Melhores ferramentas para gerenciamento de logs
Ref. 3 - Principais ferramentas de observabilidade
Ref. 4 - O que é observabilidade?
Ref. 5 - Three Pillars of Observability
Ref. 6 - 12 Logging best practices, dos and dont’s
Ref. 7 - Docker Docs
Ref. 8 - PHP Docs
Ref. 9 - Composer (A Dependency Manager for PHP)
Ref. 10 - Monolog
Ref. 11 - PSR-3