A Observabilidade no PHP com OpenTelemetry

Photo by Ben Griffiths on Unsplash

Nos últimos meses este seja o principal item no qual tenho trabalhado lá na Fretebras, como podemos melhorar nossas ferramentas de observabilidade tanto com material para que os times possam integrar de forma mais prática a telemetria, quanto com alternativas quando a aplicação legada não tem suporte as principais bibliotecas disponíveis no mercado. Hoje o foco dessa postagem é o PHP com OpenTelemetry, que é a principal linguagem da empresa ainda hoje, mesmo que ela não seja mais a linguagem da moda, alinhada com um bom framework (Laravel) e uma comunidade extremamente ativa é um canivete suíço quando se trata de velocidade de entrega.

Como usar no PHP?

Há mais de uma forma de utilizar o OpenTelemetry (Otel) no PHP, mas pelas experiências e testes que fiz essa ainda é a melhor opção que temos para utilizar o Otel dentro do ecossistema do PHP, que seria através da extensão do opentelemetry a qual pode ser instalada via pecl no servidor ou container que você esteja utilizando, abaixo mostro como pode ser feito

# Instala a extensão via pecl
pecl install opentelemetry

## Quando estiver utilizando via a imagem Docker do PHP, é necessário ativar a extensão após sua instalação
docker-ext-enable opentelemetry

# Para verificar que o mesmo foi instalado
php -m | grep opentelemetry

Após a instalação e ativação da extensão podemos fazer o próximo passo que é a instalação dos pacotes via composer. Nesta forma de integração vamos utilizar os pacotes mantidos pelo core team do Otel, o qual irá nós poupar bastante trabalho se fossemos realizar a integração manual. Para que possamos identificar o pacote que melhor se adeque a nossa necessidade, é necessário verificar alguns itens antes da instalação, sendo eles como:

• Qual banco de dados utilizamos?
• Aplicamos alguma das seguintes PSR (PSR-3, PSR-15, PSR-14, PSR-15)
• Qual método de exportação vamos utilizar, gRPC ou HTTP? Zipkin ou OTLP?

Com essas perguntas respondidas será possível definir a instalação de alguns pacotes como o open-telemetry/opentelemetry-auto-psr15 em que conseguimos instrumentar automaticamente toda implementação da PSR-15, outra muito importante é a open-telemetry/opentelemetry-auto-pdo onde temos a instrumentação das implementações do PDO (PHP Data Objects) de forma automática sem a necessidade de customizações para o seu funcionamento, e por fim, uma outra integração bastante relevante é a com o Exporter que desejamos usar para enviar as informações para o nosso Collector neste caso, se não utilizar o gRPC, acredito que a melhor seja open-telemetry/exporter-otlp que é bastante agnóstica ao serviço de Collector que utilizarmos. Abaixo o comando para realizar a instalação:

composer require open-telemetry/opentelemetry-auto-psr15 \\
	open-telemetry/opentelemetry-auto-pdo \\
	open-telemetry/exporter-otlp \\
	open-telemetry/gen-otlp-protobuf

Para o funcionamento real da extensão e dos pacotes instalados é necessário configurarmos as variáveis de ambiente que são utilizadas pela extensão e seus pacotes para identificar como enviar as informações, abaixo um exemplo das variáveis de ambiente:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_PROPAGATORS=baggage,tracecontext

E quando tenho um framework?

A instalação anterior tratava principalmente casos onde não temos nenhum Framework instalado em nossos projetos, o que não é algo muito recomendado atualmente tendo em vista a velocidade que uma comunidade de pessoas consegue tratar uma CVE (Common Vulnerabilities and Exposures) que possa atingir um grande framework como Laravel ou Symfony.

Como na Fretebras trabalhamos com Laravel, vou exemplificar como podemos fazer a instalação dos pacotes necessários para integrar ele de forma automática. Assim como os outros pacotes que mostrei antes é bastante simples, só é necessária a instalação de um pacote open-telemetry/opentelemetry-auto-laravel, neste pacote há bem mais ferramentas do que em outros pacotes que exemplifiquei por estarmos trabalhando em um framework.

composer require open-telemetry/opentelemetry-auto-laravel

Esse pacote inclui até o momento a instrumentação automática dos seguintes itens nativos do Laravel: Requests, Console/Command, Queue, Cache, ClientRequest, Exceptions, Log e as Queries, ufa acredito que seja quase tudo até o momento, mas, como um framework que está sempre se desenvolvendo pode ser que alguma funcionalidade muito nova ainda não tenha sua própria implementação dentro do pacote oficial, contudo, como o Otel é bastante flexível, ainda é possível fazer uma integração manual do seu pacote preferido.

Alguns pacotes famosos como mongodb/laravel-mongodb não funcionam automaticamente e necessitam de uma integração manual ou o uso do pacote open-telemetry/opentelemetry-auto-mongodb se quiser uma integração que não seja tão presa ao Laravel, mas ainda sim conseguir capturar as interações com o MongoDB sem maiores problemas.

Complementando seu conhecimento

Essa postagem foi mais para falar de uma forma mais ampla como podemos fazer para utilizar o OpenTelemetry no PHP, e consequentemente no framework mais famoso dele, o Laravel, entretanto isso é apenas uma pequena ponta de um grande Iceberg que é a Observabilidade no geral, quanto em aplicações PHP em que podemos ir para casos onde nossa aplicação gera métricas de uso e disponibilidade em tempo real utilizando o OpenTelemetry como agregador desses dados.

Como todo estudo ele nos gera diversas referências que estou listando aqui abaixo para complementar o conhecimento de quem leu até aqui:

• O guia oficial do OpenTelemetry para o PHP
• Uma postagem de instrumentação manual no Laravel (com ótimos exemplos de como podemos fazer isso manualmente)
• Pacote experimental da Spatie para o Laravel
• E um ótimo pacote da KeepSuite que re-implementa de maneira mais customizável o pacote oficial da Otel