elastic apm agent

Agente APM elástico para PHP

A liberação 6.2 da pilha elástica viu ao amanhecer do monitoramento de desempenho do aplicativo. Os agentes da APM em vários idiomas foram liberados com ele, mas de alguma forma o PHP não estava entre eles ¯_ (ツ) _/¯ Esta biblioteca acrescenta que o agente APM, para que possamos enviar com prazer nossas medições de desempenho de aplicativos ao servidor APM elástico.

Atenção: Alpha

Atualmente, a biblioteca está na fase alfa, o que significa que a interface ainda pode mudar e não está pronta para o uso da produção. Eu apreciaria muito se você experimentar a versão atual e relatar quaisquer problemas que encontrar.

Instalação

Adicione a biblioteca ao seu aplicativo com o Composer:

composer require techdeco/elastic-apm-agent

Isso só funcionará se você tiver implementações dos seguintes pacotes virtuais instalados (mais informações sobre cada uma delas abaixo):

• PHP-HTTP/ASYNC-Client-Implementação
• PHP-HTTP/Implementação de Faculdade de Mensagem
• PSR/LOG-AMPLEMENTAÇÃO

Parece um pouco de aborrecimento para você, talvez até um pouco preguiçoso do nosso lado - por que não deixar esse pacote apenas escolher um? - Mas fornece a maior flexibilidade e uma chance mínima de conflitos com pacotes já usados ​​em seu projeto.

Digamos que você não tenha nenhuma dessas implementações em seu projeto e escolhe respectivamente o Guzzle 6, a mensagem e o monólogo do PHP HTTP; Você pode instalar esta biblioteca com:

composer require techdeco/elastic-apm-agent 
                 php-http/guzzle6-adapter 
                 php-http/message 
                 monolog/monolog

Dependência do cliente HTTP

Para enviar dados para o servidor APM, o agente APM nesta biblioteca precisa de um cliente HTTP. Para não forçá-lo a uma opção para um cliente HTTP específico, a biblioteca depende de uma implementação da php-http/async-client-implementation . Seu projeto precisa fornecer essa implementação, para a qual você pode encontrar possíveis candidatos no site PHP-HTTP.

Dependência da fábrica de mensagens http

O mesmo vale para não forçá-lo a uma opção para uma fábrica de mensagens HTTP específica, que deixa seu projeto para fornecer uma implementação de php-http/message-factory-implementation , para a qual você pode encontrar possíveis candidatos no site php-http

PSR Logger dependência

E também para registro, este pacote precisa de uma implementação para que o cliente possa notificá -lo quando as coisas vão de lado. Você pode encontrar toda a implementação para psr/log-implemtation no Packagist. Se você não sabe qual escolher, o Monolog é excelente.

Configuração

Para informar à biblioteca como se conectar ao servidor APM, inicialize pelo menos uma implementação do LoggerInterface e um objeto ClientConfiguration e dê -o ao HttplugAsyncClient . O cliente HTTP e a fábrica de mensagens são opcionais; Se eles não forem injetados, o cliente tentará descobri -los.

 $ config         = ( new ClientConfiguration ( ' http://foo.bar ' ))-> authenticatedByToken ( ' alloy ' );
$ httpClient     = . . . # Implementation of php-http/async-client-implementation
$ requestFactory = . . . # implementation of php-http/message-factory-implementation 
$ logger         = . . . # implementation of psr/log-implementation
$ client         = new HttplugAsyncClient ( $ logger , $ config , $ httpClient , $ requestFactory );

Uso

Elastic fez um ótimo trabalho integrando perfeitamente com muitos idiomas e estruturas. Esta biblioteca espera fornecer o mesmo serviço à comunidade PHP. Você pode optar por usar os blocos de construção fornecidos pela biblioteca em uma solução faça você mesmo ou usar os componentes de conveniência de nível superior, como o middleware.

DIY

O servidor APM da Elastic ingere dois tipos de eventos: transações e erros. Depois de criar o cliente, você pode enviar respectivamente um TechDeCoElasticApmAgentRequestTransaction ou TechDeCoElasticApmAgentRequestError com esse cliente para o servidor APM. Para criar esses dois tipos de solicitações, consulte o espaço de nome TechDeCoElasticApmAgentMessage para todos os componentes necessários.

Esteja ciente de que todos os objetos de solicitação e mensagem são imutáveis ​​para que todas as chamadas para um método retornem uma nova instância com uma propriedade mutada. Certifique -se de trabalhar com essa nova instância, em vez da que você executou a chamada.

 # Bad example
$ error = new Error (...);
$ error -> onSystem (...); // New instance is in the wind
$ error -> inProcess (...) // New instance is in the wind

# Good example
$ error = new Error (...);
$ error = $ error -> onSystem (...)-> inProcess (...); // Got it!

Middleware

Para medir o tempo de resposta e relatar erros (capturando exceções), você pode conectar o middleware compatível com o PSR-15 ao seu aplicativo. Se você deseja enriquecer a transação que você envia ao servidor APM com base na solicitação ou resposta, implemente o OpenTransactionRequestEnricher ou OpenTransactionResponseEnricher e conecte o middleware.

Transação

O TransactionMiddleware injetará uma OpenTransaction na solicitação encaminhada sob o nome do atributo apm-transaction (mas você é melhor referência a ele usando o constante TransactionMiddleware::TRANSACTION_ATTRIBUTE ).

Você pode adicionar Span s e marcar eventos à OpenTransaction e, quando você dá uma resposta, o middleware os pega e os envia junto com a transação para o servidor APM. Este é um dos objetos de visualização que é mutável , para que você não precise substituir o atributo de solicitação toda vez que mudar algo.

Erro

Se você deseja capturar e reportar o Throwable do APM, inclua também o ErrorMiddleware na pilha de middleware. Ele pegará qualquer Throwable e tentará fazer o máximo de sentido possível. Para dar o erro ainda mais contexto, você pode injetar objeto Context na instanciação do middleware. Ele usará isso como base para o contexto de construção.

Enriquecimento

Às vezes, você deseja enriquecer a transação com dados da solicitação ou resposta. Para tornar isso possível, conecte o OpenTransactionRequestEnrichmentMiddleware e OpenTransactionRequestEnrichmentMiddleware e injete suas implementações de OpenTransactionRequestEnricher e OpenTransactionResponseEnricher para adicionar informações OpenTransaction

Existem algumas implementações enriquecedoras incluídas nesta biblioteca também:

• RequestHeaderBlacklistEnricher : adiciona cabeçalhos à Request no Context exceto quando o nome está em uma lista negra.
• ResponseHeaderBlacklistEnricher : adiciona cabeçalhos à Response no Context exceto quando o nome está em uma lista negra.

Combinação

Obviamente, os dois middleware podem ser combinados. A maneira recomendada de fazer isso é conectar primeiro TransactionMiddleware , depois o ErrorMiddleware e, finalmente, o OpenTransactionRequestEnrichmentMiddleware e OpenTransactionRequestEnrichmentMiddleware . Dessa forma, a transação será enriquecida, qualquer erro será correlacionado com a transação e a duração da transação será o mais realista possível.

Cache

Para monitorar suas chamadas de cache, envolva sua biblioteca de implementação de cache na camada de cache compatível com PSR-6. Ele criará um período para cada chamada.

Antes de chamar qualquer método do CacheItemPoolInterface , certifique -se de injetar uma OpenTransaction , consulte a seção de transação aberta abaixo.

Cliente httplug

Para monitorar suas chamadas para serviços HTTP externos, envolva seu cliente httplug no HttpClientWrapper . Ele criará uma extensão para cada solicitação HTTP que você enviar.

O invólucro adicionará o cabeçalho X-Correlation-ID à solicitação antes de encaminhá-la. O cabeçalho conterá um UUID e oferece a oportunidade de correlacionar solicitações HTTP em cascata durante toda a sua infraestrutura. O middleware nesta biblioteca pegará o cabeçalho e adicionará o ID de correlação às tags do contexto da transação. Se nenhum ID de correlação puder ser encontrado no cabeçalho, um novo será criado.

Antes de chamar quaisquer métodos do HttpClientInterface , certifique -se de injetar uma OpenTransaction , consulte a seção de transação aberta abaixo.

Transação aberta

Várias das classes de conveniência nesta biblioteca precisam de uma OpenTransaction antes que possam funcionar. Todas essas classes implementarão a interface OpenTransactionEnricher . Foi uma opção deliberada usar um setter em vez de exigir a OpenTransaction no construtor, simplesmente porque não existe naquele momento, ele precisa de informações de tempo de execução para serem criadas.

Você pode obter o OpenTransaction obtê -lo de um atributo de solicitação se usar o middleware nesta biblioteca ou criar o seu próprio e convertê -lo posteriormente em uma Transaction que você pode enviar para o servidor APM através do Client .