こんにちは。技術基盤部の磯野です。 先日に引き続きZipkinです。 今回は PHP + Symfony で動いている Webアプリケーションへのトレーサーの導入です。 前回の記事 → Zipkinを導入してみた(サーバー編) 構成 処理の流れ 処理の流れを追跡するためのリクエストヘッダ fluentdの設定 PHP(Symfony)側の実装 クライアントライブラリ Hoopak Apache Thrift ソースコード DI用設定ファイル(抜粋) イベントリスナクラス サービスコンテナクラス(イベントリスナにDIする用) 足りない機能を補充するためのラッパークラス WebAPI呼び出しのロギング追加 出力 構成 PHPは非同期に処理ができないので直接Zipkinサーバーにに投げるのではなくローカルのfluentdを利用してできるだけ短時間で処理が終わるようにしています。 画像のアプリケーション・フレームワーク → Zipkin Symfony2 Fluentd Sinatra 処理の流れ トレースデータの初期化(trace_id, span_idにユニークな値を設定する) Symfonyのイベントリスナのkernel.requestとkernel.responseをSubscribe kernel.requestイベントの通知時にリクエストの受付時刻(microtime)やURLなどを保存 WebAPI呼び出し時に処理の流れを追跡するための情報をリクエストヘッダに付与 WebAPI呼び出し処理の直前に送信時刻(microtime)やリクエスト先を保存 WebAPI呼び出し終了時に受信時刻(microtime)を保存し、API呼び出し開始時に保存した内容と一緒にローカルのfluentdにscribeで送信 kernel.responseイベントの通知時にレスポンス送信時刻(microtime)を保存し、kernel.requestで保存した内容と一緒にローカルのfluentdにscribeで送信 fluentdは順次Zipkinサーバーに転送 WebAPIが管理外のサービスの場合にはトレースデータの追跡情報をリクエストヘッダに付与せずに処理を行います。 なお、アプリケーションとWebAPIの呼び出しのトレースデータを別々にfluentdに流すようになっていますが、後述のライブラリの仕様です。 トレースするシステムが多い場合はまとめて送信するように改修した方がよさそうです。 処理の流れを追跡するためのリクエストヘッダ WebAPIの呼び出しのトレースデータは取得できますが、WebAPIからさらに別のWebAPIを呼ぶ場合には、一連の流れを認識するデータを持ちまわる必要があります。 そこで、HTTPヘッダにその流れを認識するために必要なデータを付与しています。 以下はそのHTTPヘッダとその説明です。 HTTP Header Type 説明 X-B3-TraceId 64 encoded bits *1 リクエストごとに共通のID、これで追跡情報を紐付ける X-B3-SpanId 64 encoded bits *1 計測ごとに一意に決まるID X-B3-ParentSpanId 64 encoded bits *1 直前のSpanId X-B3-Sampled Boolean (either “1” or “0”) *2 サンプリング対象かどうか X-B3-Flags a Long - *1 内部データは数値ですが、ヘッダに付与する際は16進数表現した文字列に変換します。 *2 rubygemsにあるzipkin-tracerが「X-B3-Sampled」を受け取る際に'true'(文字列)を要求するので文字列に変換します。 詳しくは以下URLの「HTTP Tracing」を参照してください。 http://zipkin.io/pages/instrumenting.html fluentdの設定 scribeで受け取りzipkinのscribe用のポートに転送するためのfluentdの設定はこんな感じです。 ※ 事前に fluent-plugin-scribe を導入しています。 <source> type scribe port 1463 </source> <match zipkin .**> type scribe host zipkinserver port 9410 field_ref message </match> PHP(Symfony)側の実装 続いてPHP(Symfony)側の実装です。 クライアントライブラリ まずはZipkinにトレースデータを送信するためのライブラリの導入をします。 Hoopak PHP用のライブラリは 公式 には存在しなかったので。GitHubで探しました。 1つしか見つからなかったのでこちらを利用しています。 https://github.com/Jimdo/hoopak This implementation might be incomplete and very naive とのことでちょっとドキドキですが、期待通りに動かなければ直せばいいだけなのでそのまま使います。 Apache Thrift HoopakはApache Thriftに依存しています。 https://thrift.apache.org/ 上記URLのページからダウンロードしてきたファイルを展開すると各言語用のライブラリが入っているのでPHP用を利用します。 ソースコード Symfonyをあまり理解せずに作っているので、使い方とか用語とか説明とか違ったらご指摘ください。 また、以下の3ファイルのrequireが必要なようなので事前にどこかでrequireしておいた方がいいです。 hoopak/gen-php/Scribe/Types.php hoopak/gen-php/Scribe/scribe.php hoopak/gen-php/Zipkin/Types.php DI用設定ファイル(抜粋) ExampleApp/Resources/config/services.yml parameters : zipkintracer.samplerate : 0.1 zipkintracer.service_name : webserver services : zipkin_tracer : scope : request class : ExampleApp\TracerService arguments : - @request - %zipkintracer.service_name% - %zipkintracer.samplerate% zipkin_event_listener : scope : request class : ExampleApp\TraceEventListener tags : - { name : kernel.event_subscriber } arguments : - @zipkin_tracer - @kernel - @request イベントリスナクラス <?php namespace ExampleApp; use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\Event\FilterResponseEvent; /** * Zipkinでのトレース用のイベントリスナ * リクエスト開始〜レスポンス直前の時間の計測を登録する。 **/ class TraceEventListener implements EventSubscriberInterface { /** * コンストラクタ * * @param ExampleApp\TraceService $trace * @param AppKernel $kernel * @param Request $request */ public function __construct ( $ tracer , $ kernel , $ request ) { $ this -> tracer = $ tracer ; $ this -> kernel = $ kernel ; $ this -> request = $ request ; } public static function getSubscribedEvents () { return array ( ' kernel.request ' => ' onKernelRequest ', ' kernel.response ' => ' onKernelResponse ', ) ; } public function onKernelRequest ( GetResponseEvent $ event ) { $ trace = $ this -> tracer -> getTrace () ; $ trace -> record ( \Hoopak\Annotation :: serverReceive ()) ; $ trace -> record ( \Hoopak\Annotation :: string ( ' server.env ', $ this -> kernel -> getEnvironment ())) ; $ trace -> record ( \Hoopak\Annotation :: string ( ' http.uri ', $ this -> request -> server -> get ( ' SCRIPT_URL ' ))) ; $ trace -> record ( \Hoopak\Annotation :: string ( ' http.query ', json_encode ( $ this -> request -> query -> all ()))) ; } public function onKernelResponse ( FilterResponseEvent $ event ) { $ trace = $ this -> tracer -> getTrace () ; $ trace -> record ( \Hoopak\Annotation :: serverSend ()) ; } } サービスコンテナクラス(イベントリスナにDIする用) <?php namespace ExampleApp; require_once ' hoopak/gen-php/Scribe/Types.php '; require_once ' hoopak/gen-php/Scribe/scribe.php '; require_once ' hoopak/gen-php/Zipkin/Types.php '; /** * Zipkinによるトレース用クラスの初期化処理&保持する * **/ class TracerService { private $ _tracer ; /** * コンストラクタ * * @param Request $request * @param float $samplerate Zipkinによるトレースをサンプリングするレートの指定 */ public function __construct ( $ request , $ service_name , $ samplerate = 1.0 ) { $ method = strtolower ( $ request -> server -> get ( ' REQUEST_METHOD ', ' GET ' )) ; $ tracer = new \Hoopak\ZipkinTracer ( new \Hoopak\ScribeClient ( ' localhost ', 1463 )) ; $ this -> _trace = new TraceWrapper ( $ method , null , null , null , $ samplerate , array ( $ tracer )) ; $ ipaddress = $ request -> server -> get ( ' SERVER_ADDR ' ) ; $ port = $ request -> server -> get ( ' SERVER_PORT ' ) ; $ this -> _trace -> setEndpoint ( new \Hoopak\Endpoint ( $ ipaddress , $ port , $ service_name )) ; } public function getTrace () { return $ this -> _trace; } } 足りない機能を補充するためのラッパークラス あとで整理してhoopak側に取り込んでプルリク出したいと思います。 <?php namespace ExampleApp; /** * Hoopak\TraceのWrapクラス * **/ class TraceWrapper { /** * @var Hoopak\Trace **/ private $ _trace ; /** * @var boolean * Hoopak\Traceエラー時に次回以降処理を転送しないためのフラグ * **/ private $ _error = false ; /** * @var array * \Hoopak\ScribeClientなどのインスタンスを持つ配列 **/ private $ _tracer = array () ; /** * @var \Hoopak\Endpoint **/ private $ _endpoint = null ; /** * トレースデータを取得するかどうか **/ public $ sampled = true ; /** * @var array APIサーバーに送信するZipkinヘッダの対応表 **/ private $ _headers = array ( ' traceId ' => ' X-B3-TraceId ', ' parentSpanId ' => ' X-B3-ParentSpanId ', ' spanId ' => ' X-B3-SpanId ', ' sampled ' => ' X-B3-Sampled ', #'flags' => 'X-B3-Flags' ) ; /** * コンストラクタ * * @param Hoopak\Trace */ public function __construct ( $ method , $ traceId = null , $ spanId = null , $ parentSpanId = null , $ samplerate = 1.0 , $ tracers = array ()) { if ( !$ traceId ) { $ traceId = $ this -> _id () ; } if ( !$ spanId ) { $ spanId = $ this -> _id () ; } $ this -> _tracers = $ tracers ; $ this -> _trace = new \Hoopak\Trace ( $ method , $ traceId , $ spanId , $ parentSpanId , $ tracers ) ; if ( $ samplerate < 1.0 ) { $ this -> sampled = ( $ samplerate == 0 ) ? false : ( $ samplerate > ( mt_rand () / mt_getrandmax ())) ; } } /** * @see \Hoopak\Trace::record() * sampled=falseの時は何もしない **/ public function record ( $ annotation ) { if ( !$ this -> sampled ) { return ; } $ this -> __call ( ' record ', array ( $ annotation )) ; } /** * @see \Hoopak\Trace::child() * \Hoopak\Trace::_id()が同一IDを返却する確率が高すぎるので、使わないように処理を上書き **/ public function child ( $ name ) { $ samplerate = $ this -> sampled ? 1.0 : 0.0 ; $ trace = new self ( $ name , $ this -> traceId, $ this -> _id () , $ this -> spanId, $ samplerate , $ this -> _tracers ) ; $ trace -> setEndpoint ( $ this -> _endpoint ) ; return $ trace ; } /** * @see \Hoopak\Trace::setEndpoint() * このクラスでもendpointを変数として保持する **/ public function setEndpoint ( $ endpoint ) { $ this -> _endpoint = $ endpoint ; $ this -> __call ( ' setEndpoint ', array ( $ endpoint )) ; } /** * Hoopak\Traceに処理を移譲するためのメソッド * 移譲先でエラーが発生した場合は、握りつぶす * * 個別のメソッドに関しては移譲先を参照 * @see hoopak/src/Hoopak/Trace.php * **/ public function __call ( $ name , $ arguments ) { if ( $ this -> _error ) { return ; } try { return call_user_func_array ( array ( $ this -> _trace, $ name ) , $ arguments ) ; } catch ( \ Exception $ e ) { $ message = " exception ' " . get_class ( $ e ) . " ' with message ' " . $ e -> getMessage () . " ' in " . $ e -> getFile () . " : " . $ e -> getLine () ; error_log ( $ message ) ; $ this -> _error = true ; } } /** * \Hoopak\Traceのパブリックなインスタンス変数を取得するためのメソッド * * 個別の変数に関しては以上先を参照 * @see hoopak/src/Hoopak/Trace.php **/ public function __get ( $ name ) { return $ this -> _trace ->$ name ; } /** * Zend\Http\Clientでのリクエストデータ、レスポンスデータを元にZipkinへのトレース登録とを行う。 * また、リクエストヘッダにZipkinのトレース情報転送用のヘッダを付与する。 * * @param string $name リクエスト送信先のサービス名称 * @param Zend\Http\Client $client * @param callable $block ( * @param ExampleApp\TracerWrapper * @return Zend\Http\Response * ) * @return Zend\Http\Response * **/ public function traceWithHTTPClient ( $ name , $ client , $ block ) { $ tracer = $ this -> _createChildHTTPTracer ( $ name , $ client ) ; $ tracer -> _prepareHTTPClient ( $ client ) ; $ tracer -> record ( \Hoopak\Annotation :: clientSend ()) ; $ httpResponse = $ block ( $ tracer ) ; $ tracer -> record ( \Hoopak\Annotation :: string ( ' http.status ', $ httpResponse -> getStatusCode ())) ; $ tracer -> record ( \Hoopak\Annotation :: clientReceive ()) ; return $ httpResponse ; } /** * Zend\Http\Clientのデータを元に子トレースインスタンスを作成し返却する。 * * @param string $name リクエスト先サービス名 * @param @param Zend\Http\Client $client * @return ExampleApp\TracerWrapper * **/ private function _createChildHTTPTracer ( $ name , $ client ) { $ uri = $ client -> getUri () ; $ query = $ client -> getRequest () -> getQuery () ; $ method = $ client -> getRequest () -> getMethod () ; $ trace = $ this -> child ( strtolower ( $ method )) ; $ serverAddress = \Hoopak\Annotation :: string ( ' sa ', ' 1 ' ) ; $ serverAddress -> endpoint = new \Hoopak\Endpoint ( $ uri -> getHost () , $ uri -> getPort () , $ name ) ; $ trace -> record ( $ serverAddress ) ; $ trace -> record ( \Hoopak\Annotation :: string ( ' http.uri ', $ uri -> getPath ())) ; $ trace -> record ( \Hoopak\Annotation :: string ( ' http.query ', json_encode ( $ query ))) ; return $ trace ; } /** * Zend\Http\Clientにトレースデータ転送に必要なリクエストヘッダを付与する * @param Zend\Http\Client $client * **/ private function _prepareHTTPClient ( \Zend\Http\Client $ client ) { foreach ( $ this -> _headers as $ key => $ value ) { $ headers [ $ value ] = $ this -> _getStringData ( $ key ) ; } $ client -> setHeaders ( $ headers ) ; } /** * * @param $key string key of data * @return string- **/ private function _getStringData ( $ key ) { $ value = $ this ->$ key ; switch ( gettype ( $ value )) { case ' integer ' : $ ret = sprintf ( " %016s ", dechex ( $ value )) ; break ; case ' boolean ' : $ ret = $ value ? ' true ' : ' false '; break ; default: $ ret = ( string ) $ value ; break ; } return $ ret ; } private function _id () { return ( int ) round ( microtime ( true ) * 1000 * 1000 ) ; } } WebAPI呼び出しのロギング追加 このようにWebAPIを呼び出している部分(Zend\Http\Client)があったら $response = $client- > send(); こんな感じに書き換える事でWebAPIへのリクエストのトレースが有効になります。 $tracer = $this- > container- > get('zipkin_tracer')- > getTracer(); $response = $tracer- > traceWithHTTPClient("webapi", $client, function($childTracer) use ($client) { return $client- > send(); }); 出力 以下の赤で囲った部分が今回の作業により記録されるようになります。 次回は、WebAPIサーバーへの導入(Ruby編)の予定です。