elastic apm agent

PHP的弹性APM代理

弹性堆栈的第6.2版锯到应用程序性能监控的曙光。使用了几种语言的APM代理，但其中以某种方式不在其中php是_（ツ）_/é该库中添加了APM代理，因此我们可以很乐意将应用程序性能测量运送到Elastic APM服务器上。

注意：alpha

目前，该库处于Alpha阶段，这意味着接口可能仍会更改，并且还没有准备好生产使用。如果您尝试当前版本并报告遇到的任何问题，我将非常感谢。

安装

使用Composer将库添加到您的应用程序中：

composer require techdeco/elastic-apm-agent

但是，仅当您安装了以下虚拟软件包的实现时，这才能起作用（以下每个软件包）：

• PHP-HTTP/异步 - 晶体实践
• php-http/message-factory-implentation
• PSR/对数实现

这对您来说似乎有些麻烦，甚至从我们这边有些懒惰 - 为什么不让这个包装选择一个呢？ - 但是，它为您提供了与项目中已经使用的软件包发生冲突最大的冲突。

假设您在项目中没有这些实现，并且您可以分别选择Guzzle 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记录仪依赖性

而且，对于记录，此软件包需要实现，以便客户在侧面发生时通知您。您可以在Packagist找到所有用于psr/log-implemtation的实现。如果您不知道要选择哪一个，那么独白是一个很好的选择。

配置

要告诉库如何连接到APM服务器，请至少初始化LoggerInterface和ClientConfiguration对象的实现，然后将其提供给HttplugAsyncClient 。 HTTP客户端和消息工厂是可选的；如果未注入，客户将尝试发现它们。

 $ 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

Elastic的APM服务器摄入了两种类型的事件：交易和错误。创建客户端后，您可以分别发送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将在属性名称apm-transaction下向转发请求注入OpenTransaction （但是您可以使用常量的TransactionMiddleware::TRANSACTION_ATTRIBUTE更好地引用它。

您可以将Span S和标记事件添加到OpenTransaction ，当您给出响应时，中间件将拾取它们，并将其与交易一起发送到APM服务器。这是可变的视图对象之一，因此您无需每次更改某些内容时都替换请求属性。

错误

如果您想捕获并将其Throwable到APM，也可以在中间件堆栈中包含ErrorMiddleware 。它将捕捉到任何Throwable ，并尝试使其尽可能多地了解。为了给出更多错误的上下文，您可以在中间件实例化上注入Context对象。它将以此为基础建筑环境。

丰富

有时您想通过请求或响应的数据来丰富交易。为了使之成为可能，请连接OpenTransactionRequestEnrichmentMiddleware和OpenTransactionRequestEnrichmentMiddleware ，并分别注入您的OpenTransactionRequestEnricher和OpenTransactionResponseEnricher OpenTransaction实现

该库中还包含了一些浓度实现：

• RequestHeaderBlacklistEnricher ：在Context标题添加到Request中，除非他们的名称在黑名单中。
• ResponseHeaderBlacklistEnricher ：在Context标题添加到Response中，除非他们的名称在黑名单中。

组合

显然，这两个中间件可以组合。推荐的方法是首先连接TransactionMiddleware ，然后是ErrorMiddleware ，最后是OpenTransactionRequestEnrichmentMiddleware和OpenTransactionRequestEnrichmentMiddleware 。这样，交易将得到丰富，任何错误都将与交易相关，交易持续时间将尽可能现实。

缓存

要监视您的缓存电话，请在符合PSR-6的缓存层中包装您的缓存实现库。它将为每个调用创建一个跨度。

在调用CacheItemPoolInterface的任何方法之前，请确保注入OpenTransaction ，请参阅下面的“开放事务”部分。

httplug客户端

要监视您对外部HTTP服务的呼叫，请将您的HTTPLUG客户端包装在HttpClientWrapper中。它将为您发送的每个HTTP请求创建一个跨度。

包装器将在请求转发之前，将X-Correlation-ID标头添加到请求。标题将包含一个UUID，它使您有机会在整个基础架构中将级联的HTTP请求相关联。该库中的中间件将拾取标题，并将相关ID添加到交易上下文的标签中。如果在标题中找不到相关ID，则将创建一个新的。

在调用HttpClientInterface的任何方法之前，请确保注入OpenTransaction ，请参阅下面的“开放事务”部分。

开放交易

该库中的几个便利性课程需要使用OpenTransaction才能运行。所有这些类将实现OpenTransactionEnricher接口。它是一个故意的选择，而不是仅仅因为当时不存在构造函数中的OpenTransaction ，它需要创建运行时信息。

如果您使用此库中的中间件，则可以从请求属性中获取OpenTransaction ，或者可以创建自己的中间件，然后将其转换为可以通过Client发送到APM服务器的Transaction 。