README

这是一个Elastic.co的APM产品的PHP代理：https://elastic.ac.cn/solutions/apm。Laravel & Lumen包：https://github.com/philkra/elastic-apm-laravel

请注意 目前仅支持APM服务器的v1摄入API，v2正在计划中。

安装

推荐通过Composer安装代理。

运行以下composer命令

php composer.phar require hakantaskin/elastic-apm-php-agent

安装后，您需要引入Composer的自动加载器

require 'vendor/autoload.php';

使用

使用最小配置初始化代理

$agent = new \HT\Agent(array('appName' => 'demo'));

创建代理时，您可以直接注入共享上下文，如用户、标签和自定义。

$agent = new \HT\Agent(array('appName' => 'with-custom-context'), array(
  'user' => array(
    'id'    => 12345,
    'email' => 'email@acme.com',
  ),
  'tags' => array(
    // ... more key-values
  ),
  'custom' => array(
    // ... more key-values
  )
) );

捕获错误和异常

代理可以捕获所有从接口Throwable（https://php.ac.cn/manual/en/class.throwable.php）实现的错误和异常类型。

$agent->captureThrowable( new Exception() );

添加跨度

添加跨度（https://elastic.ac.cn/guide/en/apm/server/current/transactions.html#transaction-spans）非常简单。请参阅文档以满足您的具体需求。以下是一个添加MySQL跨度的示例。

$trxName = 'GET /some/transaction/name';

// create the agent
$agent = new \HT\Agent(array('appName' => 'Demo with Spans'));

// start a new transaction
$transaction = $agent->startTransaction($trxName);

// create a span
$spans = array();
$spans[] = array(
  'name' => 'Your Span Name. eg: ORM Query',
  'type' => 'db.mysql.query',
  'start' => 300, // when did tht query start, relative to the transaction start, in milliseconds
  'duration' => 23, // duration, in milliseconds
  'stacktrace' => array(
    array(
      'function' => "\\YourOrMe\\Library\\Class::methodCall()",
      'abs_path' => '/full/path/to/file.php',
      'filename' => 'file.php',
      'lineno' => 30,
      'library_frame' => false, // indicated whether this code is 'owned' by an (external) library or not
      'vars' => array(
        'arg1' => 'value',
        'arg2' => 'value2',
      ),
      'pre_context' => array( // lines of code leading to the context line
        '<?php',
        '',
        '// executing query below',
      ),
      'context_line' => '$result = mysql_query("select * from non_existing_table")', // source code of context line
      'post_context' => array(// lines of code after to the context line
        '',
        '$table = $fakeTableBuilder->buildWithResult($result);',
        'return $table;',
      ),
    ),
  ),
  'context' => array(
    'db' => array(
      'instance' => 'my_database', // the database name
      'statement' => 'select * from non_existing_table', // the query being executed
      'type' => 'sql',
      'user' => 'root', // the user executing the query (don't use root!)
    ),
  ),
);

// add the array of spans to the transaction
$transaction->setSpans($spans);

// Do some stuff you want to watch ...
sleep(1);

$agent->stopTransaction($trxName);

// send our transactions to te apm
$agent->send();

无最小元数据和上下文的交易

$trxName = 'Demo Simple Transaction';
$agent->startTransaction( $trxName );
// Do some stuff you want to watch ...
$agent->stopTransaction( $trxName );

具有元数据和上下文的交易

$trxName = 'Demo Transaction with more Data';
$agent->startTransaction( $trxName );
// Do some stuff you want to watch ...
$agent->stopTransaction( $trxName, array(
    'result' => '200',
    'type'   => 'demo'
) );
$agent->getTransaction( $trxName )->setUserContext( array(
    'id'    => 12345,
    'email' => "hello@acme.com",
 ) );
 $agent->getTransaction( $trxName )->setCustomContext( array(
    'foo' => 'bar',
    'bar' => array( 'foo1' => 'bar1', 'foo2' => 'bar2' )
) );
$agent->getTransaction( $trxName )->setTags( array( 'k1' => 'v1', 'k2' => 'v2' ) );

交易示例

此示例说明了如何监控对另一个Web服务的调用。

$agent = new \HT\Agent( array( 'appName' => 'example' ) );

$endpoint = 'https://acme.com/api/';
$payload  = array( 'foo' => 'bar' );
$trxName  = sprintf('POST %s', $endpoint);
$client   = new GuzzleHttp\Client();

// Start the Transaction
$agent->startTransaction( $trxName );

// Do the call via curl/Guzzle e.g.
$response = $client->request('POST', $endpoint, array(
    'json' => $payload
));

// Stop the Transaction tracing, attach the Status and the sent Payload
$agent->stopTransaction( $trxName, array(
    'status'  => $response->getStatusCode(),
    'payload' => $payload,
) );

// Send the collected Traces to the APM server
$agent->send();

配置

appName       : Name of this application, Required
appVersion    : Application version, Default: ''
serverUrl     : APM Server Endpoint, Default: 'http://127.0.0.1:8200'
secretToken   : Secret token for APM Server, Default: null
hostname      : Hostname to transmit to the APM Server, Default: gethostname()
active        : Activate the APM Agent, Default: true
timeout       : Guzzle Client timeout, Default: 5
apmVersion    : APM Server Intake API version, Default: 'v1'
env           : $_SERVER vars to send to the APM Server, empty set sends all. Keys are case sensitive, Default: []
cookies       : Cookies to send to the APM Server, empty set sends all. Keys are case sensitive, Default: []
httpClient    : Extended GuzzleHttp\Client Default: array()
backtraceLimit: Depth of a transaction backtrace, Default: unlimited

详细的GuzzleHttp\Client选项可以在此处找到。

扩展配置示例

$config = array(
    'appName'     => 'My WebApp',
    'appVersion'  => '1.0.42',
    'serverUrl'   => 'http://apm-server.example.com',
    'secretToken' => 'DKKbdsupZWEEzYd4LX34TyHF36vDKRJP',
    'hostname'    => 'node-24.app.network.com',
    'env'         => array('DOCUMENT_ROOT', 'REMOTE_ADDR'),
    'cookies'     => array('my-cookie'),
    'httpClient'  => array(
        'verify' => false,
        'proxy'  => 'tcp://:8125'
    ),
);
$agent = new \HT\Agent($config);

测试

vendor/bin/phpunit

知识库

禁用CLI的代理

如果您想为混合SAPI使用动态禁用代理，请使用以下代码片段。

'active' => PHP_SAPI !== 'cli'

针对Laravel APM提供者

'active' => PHP_SAPI !== 'cli' && env('ELASTIC_APM_ACTIVE', false)

感谢@jblotus，（philkra/elastic-apm-laravel#19）

hakantaskin / elastic-apm-php-agent

维护者

详细信息