elastic apm agent

Эластичный агент APM для PHP

Выпуск 6.2 упругой стека SAW до мониторинга производительности приложения. Агенты APM на нескольких языках были выпущены с ним, но каким -то образом PHP не был среди них ¯_ (ツ) _/¯ Эта библиотека добавляет этого агента APM, чтобы мы могли с радостью отправить наши измерения производительности приложения на эластичный сервер APM.

Внимание: Альфа

В настоящее время библиотека находится в альфа -фазе, что означает, что интерфейс все еще может измениться, и он не готов к производству. Я бы очень признателен, если вы попробуете текущую версию и сообщите о любых проблемах, с которыми вы сталкивались.

Установка

Добавьте библиотеку в ваше приложение с помощью композитора:

composer require techdeco/elastic-apm-agent

Это, однако, будет работать только в том случае, если у вас есть реализации следующих виртуальных пакетов (больше информации о каждом из них ниже):

• PHP-HTTP/Async-Client-внедрение
• PHP-HTTP/Message-Factory-внедрение
• PSR/LOG-внедрение

Это кажется немного хлопот для вас, может быть, даже немного лениво с нашей стороны - почему бы не позволить этому пакету просто выбрать один? - Но это дает вам наибольшую гибкость и минимальную вероятность конфликтов с пакетами, уже используемыми в вашем проекте.

Допустим, в вашем проекте нет ни одной из этих реализаций, и вы выбираете соответственно Guzle 6, сообщение PHP HTTP и монолог; Вы можете установить эту библиотеку с:

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

HTTP -клиентская зависимость

Чтобы отправить данные на сервер APM, агенту APM в этой библиотеке нуждается в HTTP -клиенте. Чтобы не заставить вас выбирать для конкретного HTTP-клиента, библиотека зависит от реализации php-http/async-client-implementation . Ваш проект должен обеспечить эту реализацию, для которой вы можете найти возможных кандидатов на сайте PHP-HTTP.

Зависимость от HTTP -сообщений зависит

То же самое касается того, что вы не заставляете вас выбирать для конкретной фабрики сообщений HTTP, которая оставляет ваш проект, чтобы обеспечить реализацию php-http/message-factory-implementation , для которого вы можете найти возможных кандидатов на сайте PHP-HTTP

Зависимость от регистрации PSR

А также для регистрации, этот пакет нуждается в реализации, чтобы клиент мог уведомить вас, когда дела идут вбок. Вы можете найти всю реализацию для psr/log-implemtation в Packagist. Если вы не знаете, какой из них выбрать, монолог отличный.

Конфигурация

Чтобы рассказать библиотеке, как подключиться к серверу APM, инициализируйте, по крайней мере, реализацию LoggerInterface и объекта ClientConfiguration и дайте его HttplugAsyncClient . HTTP Client and Message Factory являются необязательными; Если они не введены, клиент попытается их открыть.

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

Использование

Elastic отлично справилась с множеством языков и рамок. Эта библиотека надеется предоставить ту же услугу сообществу PHP. Вы можете либо использовать строительные блоки, предоставленные библиотекой в ​​самостоятельном решении, либо использовать удобные компоненты более высокого уровня, такие как промежуточное программное обеспечение.

DIY

APM -сервер Elastic принимает два типа событий: транзакции и ошибки. После того, как вы создали клиента, вы можете отправить соответственно A TechDeCoElasticApmAgentRequestTransaction или TechDeCoElasticApmAgentRequestError с этим клиентом на сервер APM. Чтобы создать эти два типа запросов, посетите пространство имен TechDeCoElasticApmAgentMessage для всех необходимых компонентов.

Имейте в виду, что все объекты запроса и сообщения являются неизменными, поэтому каждый вызов метода вернет новый экземпляр с помощью мутированного свойства. Обязательно работайте с этим новым экземпляром, а не с тем, в котором вы выполнили звонок.

 # 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!

Промежуточное программное обеспечение

Чтобы измерить время отклика и отчетность об ошибках (за исключением исключений), вы можете подключить промежуточное программное обеспечение для соответствия PSR-15 к своему приложению. Если вы хотите обогатить транзакцию, которую вы отправляете на сервер APM на основе запроса или ответа, реализуйте OpenTransactionRequestEnricher или OpenTransactionResponseEnricher и подключите промежуточное программное обеспечение.

Сделка

TransactionMiddleware введите OpenTransaction в перенаправленный запрос под именем атрибута apm-transaction (но вы лучше ссылаетесь на него, используя Constant TransactionMiddleware::TRANSACTION_ATTRIBUTE ).

Вы можете добавить Span S и отметить события в OpenTransaction , и когда вы даете ответ, промежуточное программное обеспечение поднимет их и отправит их вместе с транзакцией на сервер APM. Это один из объектов представления, который является изменчивым, поэтому вам не нужно заменять атрибут запроса каждый раз, когда вы что -то меняете.

Ошибка

Если вы хотите поймать и сообщить Throwable S в APM, также включите в свой стек промежуточного программного обеспечения также ErrorMiddleware . Он поймает любые Throwable и попытается иметь как можно больше смысла. Чтобы дать ошибку еще больше контекста, вы можете ввести объект Context в экстремации промежуточного программного обеспечения. Он будет использовать это в качестве базы для контекста построения.

Обогащение

Иногда вы хотите обогатить транзакцию с помощью данных из запроса или ответа. Чтобы сделать это возможным, подключите OpenTransactionRequestEnrichmentMiddleware и OpenTransactionRequestEnrichmentMiddleware и введите ваши реализации соответственно OpenTransactionRequestEnricher S и OpenTransactionResponseEnricher , чтобы добавить информацию в OpenTransaction .

В эту библиотеку также включено несколько реализаций обогатителя:

• RequestHeaderBlacklistEnricher : добавляет заголовки к Request в Context за исключением случаев, когда их имя в черном списке.
• ResponseHeaderBlacklistEnricher : добавляет заголовки к Response в Context за исключением случаев, когда их имя находится в черном списке.

Комбинация

Очевидно, что два промежуточного программного обеспечения можно объединить. Рекомендуемый способ сделать это - сначала подключить TransactionMiddleware , а затем ErrorMiddleware и, наконец, OpenTransactionRequestEnrichmentMiddleware и OpenTransactionRequestEnrichmentMiddleware . Таким образом, транзакция будет обогащена, любая ошибка будет коррелировать с транзакцией, и продолжительность транзакции будет максимально реалистичной.

Кэширование

Чтобы отслеживать ваши вызовы кэширования, оберните библиотеку реализации кэширования в уровне кэширования PSR-6. Это создаст пролет для каждого вызова.

Прежде чем вызывать какие -либо методы CacheItemPoolInterface , убедитесь, что вы вводите OpenTransaction , см. В разделе «Открытая транзакция» ниже.

Httplug client

Чтобы отслеживать ваши вызовы на внешние услуги HTTP, оберните клиента HTTPLUG в HttpClientWrapper . Это создаст пролет для каждого HTTP -запроса, который вы отправляете.

Обертка добавит к запросу заголовок X-Correlation-ID прежде чем он его пересынет. Заголовок будет содержать UUID, и он даст вам возможность коррелировать каскадные HTTP -запросы на протяжении всей вашей инфраструктуры. Промежуточное программное обеспечение в этой библиотеке заберут заголовок и добавит идентификатор корреляции в теги контекста транзакции. Если в заголовке не может быть найдено никакого корреляционного идентификатора, будет создан новый.

Прежде чем вызывать какие -либо методы HttpClientInterface , убедитесь, что вы вводите OpenTransaction , см. В разделе Open Transaction ниже.

Открытая транзакция

Некоторые из удобных классов в этой библиотеке нуждаются в OpenTransaction , прежде чем они смогут функционировать. Все эти классы будут реализовать интерфейс OpenTransactionEnricher . Это был преднамеренный выбор для использования сеттера, вместо того, чтобы требовать от OpenTransaction в конструкторе, просто потому, что он не существует в то время, ему нужна информация о выполнении времени выполнения.

Вы можете получить OpenTransaction или получить его из атрибута запроса, если вы используете промежуточное программное обеспечение в этой библиотеке, либо вы можете создать свой собственный и конвертировать его в Transaction , которую вы можете отправить на сервер APM через Client .