elastic apm agent

PHPの弾性APMエージェント

アプリケーションパフォーマンス監視の夜明けに弾力性のあるスタックソーの6.2をリリースします。いくつかの言語のAPMエージェントはそれでリリースされましたが、どういうわけかPHPはその中に¯_（ツ）_/¯このライブラリはそのAPMエージェントを追加して、アプリケーションのパフォーマンス測定を弾性APMサーバーに喜んで出荷できるようにします。

注意：アルファ

現在、ライブラリはアルファフェーズにあります。つまり、インターフェイスが変化し、生産の使用ができていない可能性があります。現在のバージョンを試してみて、出会った問題を報告していただければ幸いです。

インストール

作曲家と一緒にアプリケーションにライブラリを追加します。

composer require techdeco/elastic-apm-agent

ただし、これは、次の仮想パッケージの実装がインストールされている場合にのみ機能します（以下のそれぞれの詳細）：

• php-http/async-client-implementation
• php-http/message-factory-implementation
• psr/log-prementation

これはあなたにとって少し面倒なように思えます。たぶん私たちの側から少し怠zyなかもしれません - このパッケージに1つだけを選択してみませんか？ - しかし、それはあなたのプロジェクトで既に使用されているパッケージとの対立の最も柔軟性と最小限の可能性をあなたに提供します。

プロジェクトにこれらの実装のどれもなく、それぞれPHP HTTPのメッセージとモノログをGuzzle 6を選択するとしましょう。このライブラリをインストールできます。

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のすべての実装を見つけることができます。どちらを選ぶべきかわからないなら、モノログは優れたものです。

構成

Libraryに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サーバーは、トランザクションとエラーの2種類のイベントを摂取します。クライアントを作成したら、それぞれTechDeCoElasticApmAgentRequestTransactionまたはTechDeCoElasticApmAgentRequestError APMサーバーに送信できます。これら2つのタイプのリクエストを作成するには、必要なすべてのコンポーネントのTechDeCoElasticApmAgentMessage Namespaceをご覧ください。

すべてのリクエストとメッセージオブジェクトは不変であるため、メソッドへのすべての呼び出しが変異したプロパティを使用して新しいインスタンスを返すことに注意してください。電話をかけたものの代わりに、その新しいインスタンスを必ず操作してください。

 # 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を挿入します（ただし、Constant TransactionMiddleware::TRANSACTION_ATTRIBUTEを使用してそれを参照することをお勧めします）。

Span SとMarkイベントをOpenTransactionにマークすることができ、応答を行うと、ミドルウェアがそれらをピックアップして、トランザクションとともにAPMサーバーに送信します。これは、変更可能なビューオブジェクトの1つであるため、何かを変更するたびにリクエスト属性を交換する必要はありません。

エラー

Throwable SをAPMにキャッチして報告する場合は、ミドルウェアスタックにErrorMiddlewareも含めてください。 Throwableものをキャッチし、できるだけ理解しようとします。エラーをさらにコンテキストに与えるために、ミドルウェアのインスタンス化にContextオブジェクトを挿入できます。それを構築コンテキストのベースとして使用します。

濃縮

リクエストまたは応答からのデータでトランザクションを充実させたい場合があります。これを可能にするには、 OpenTransactionRequestEnrichmentMiddlewareとOpenTransactionRequestEnrichmentMiddlewareをそれぞれ接続し、それぞれOpenTransactionRequestEnricher sおよびOpenTransactionResponseEnricherの実装を注入して、 OpenTransactionに情報を追加します

このライブラリには、いくつかの濃縮物の実装も含まれています。

• RequestHeaderBlacklistEnricher ：名前がブラックリストにある場合を除き、 ContextでヘッダーをRequestに追加します。
• ResponseHeaderBlacklistEnricher ：名前がブラックリストにある場合を除き、 ContextのResponseにヘッダーを追加します。

組み合わせ

明らかに、2つのミドルウェアを組み合わせることができます。これを行うための推奨される方法は、最初にTransactionMiddlewareフックアップし、次にErrorMiddleware 、そして最後にOpenTransactionRequestEnrichmentMiddlewareとOpenTransactionRequestEnrichmentMiddlewareフックすることです。そうすれば、トランザクションが充実し、エラーはトランザクションと相関し、トランザクション期間は可能な限り現実的になります。

キャッシング

キャッシングコールを監視するには、PSR-6準拠のキャッシング層でキャッシング実装ライブラリを包みます。通話ごとにスパンが作成されます。

CacheItemPoolInterfaceのメソッドを呼び出す前に、 OpenTransactionを注入することを確認してください。以下のオープントランザクションセクションを参照してください。

httplugクライアント

外部HTTPサービスへの通話を監視するには、 HttpClientWrapperにHTTPlugクライアントを包みます。送信する各HTTPリクエストのスパンが作成されます。

ラッパーはX-Correlation-IDヘッダーをリクエストに追加します。ヘッダーにはUUIDが含まれており、インフラストラクチャ全体でカスケードHTTPリクエストを相関させる機会を提供します。このライブラリのミドルウェアはヘッダーをピックアップし、トランザクションのコンテキストのタグに相関IDを追加します。ヘッダーに相関IDが見つからない場合、新しいものが作成されます。

HttpClientInterfaceのメソッドを呼び出す前に、 OpenTransactionを注入することを確認してください。以下のオープントランザクションセクションを参照してください。

オープントランザクション

このライブラリの便利なクラスのいくつかは、機能する前にOpenTransactionを必要とします。これらすべてのクラスは、 OpenTransactionEnricherインターフェイスを実装します。コンストラクターでのOpenTransaction要求する代わりにセッターを使用することは意図的な選択でした。単に、それが当時存在しないという理由だけで、実行するためにはランタイム情報が必要です。

このライブラリのミドルウェアを使用する場合、 OpenTransactionを取得するか、リクエスト属性から取得するか、独自に作成して、 Clientを介してAPMサーバーに送信できるTransactionに後で変換することができます。