2. Logs

Diogo Antunes — Sun, 06 Apr 2025 22:09:29 +0000

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

(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

<?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

Executaremos o nosso código da seguinte forma

php main.php

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

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.

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

1. Um breve estudo sobre observabilidade

Diogo Antunes — Sun, 06 Apr 2025 18:11:16 +0000

O que é a Observabilidade?

A observabilidade se refere a capacidade de compreender o estado interno ou condições de um ou mais sistemas complexos se baseando apenas em saídas externas. (Ref. 1, 2 e 3)

Quando aplicamos algumas metodologias que fazem parte da ideia de Observabilidade, elas nos dão a habilidade de compreender fluxos, dados, montar estatíticas e, principalmente, compreender melhor os erros, tudo isso sem precisar de testes complexos ou implementações adicionais.

“Quanto mais observável for um sistema, mais rápido e precisamente você poderá identificar a causa raiz de um problema de desempenho, sem a necessidade de testes ou programação adicionais.” - (Ref. 4)

Como funciona a Observabilidade?

A observabilidade funciona coletando continuamento dados de desempenho para criar um registro completo e correlacionado de cada fluxo do sistema em tempo de execução. Quanto mais observável for o seu sistema, mais rápido e precisamento você poderá identificar e rastrear um problema de desempenho até suas origens. (Ref. 1 e 2)

Os principais conceitos da observabilidade, são:

Dados de Logs;
- Os logs registram eventos e erros com informações, levam também informações importantes como data e hora de execução e dados utilizados.
Métricas;
- As métricas são registros de dados quantitativos, servem principalmente para identificar o número de cadastros realizados, números de acessos a serviços e consumo de recursos.
Tracing distribuído;
- O Tracing distribuído serve para registrar de ponta a ponta cada operação realizada pela aplicação, marca do início ao fim das operações com um identificador único e registra eventos relevantes.
Mapeamento de dependências;
- Os mapas de dependência mostram como aplicações, serviços e componentes de infraestrutura estão conectados. (Ref. 5)
Detecção de anomalias.
- Uma plataforma de observabilidade correlaciona enormes quantidades de dados de telemetria em tempo real, o que fornece às equipes de DevOps, SRE e TI uma imagem contextual completa de qualquer evento ou problema. (Ref. 5)

Por que a observabilidade é importante? — Por que precisamos dela?

A observabilidade é importante porque permite que as equipes avaliem, monitorem e melhorem o desempenho de sistemas distribuídos. É muito mais eficaz do que os métodos de monitoramento tradicionais. Uma plataforma de observabilidade de ponta a ponta pode ajudar a romper silos e promover a colaboração. Os problemas podem ser diagnosticados de forma proativa, analisados e rastreados até suas origens. (Ref. 5)

Com a stack completa de observabilidade (Logs, Métricas e Traces), pode-se acompanhar o desempenho do seu ecossistema multinuvem em tempo real e com um rico histórico. É possível sintetizar dados de endpoints e serviços gerados por hardware, software, componentes de infraestrutura de nuvem, containers, open source, microsserviços e muito mais. (Ref. 5)

A observabilidade ajuda as organizações a:

Descobrir e analisar a importância dos incidentes de desempenho para os negócios
Aumentar a eficiência dos ciclos de vida de desenvolvimento de software
Acelerar a resolução de problemas e a análise de causa raiz
Melhorar as experiências do usuário final
Fortalecer a segurança das aplicações

(Ref. 5)

Ref. 1 - Observabilidade
Ref. 2 - O que é observabilidade?
Ref. 3 - What is Observability? | Grafana for Beginners
Ref. 4 - Grafana Fundamentals
Ref. 5 - O que é observabilidade?
Ref. 6 - Metrics, Logs and Traces: What To Observe and Why

A.N.:
Estou criando alguns posts como referência a estudos que venho realizando, sintam-se a vontade para acrescentar informações relevantes nos comentários.
Obrigado.

Forem: Diogo Antunes