PHP SDK

安裝 SDK

PHP SDK 的 Stub 可以透過 Composer 使用下列指令來安裝:

composer require instana/instana-php-sdk

Stub 可確保當未使用 Instana 來監視 PHP 程序時，對 SDK API 的所有呼叫都會導致 no-op，而不是錯誤。

Packagist上提供要與 IDE 搭配使用之 PHP SDK 的 Stub。

SDK 用法範例

$tracer = new \Instana\Tracer();
$tracer->setServiceName('my-service');
$span = $tracer->createSpan('foo');
$span->annotate('function', 'doSomething');
try {
    doSomething();
} catch (\Exception $e) {
    $tracer->logException($e);
    $span->markError();
} finally {
    $span->stop();
}

建立自訂 ENTRY 和 EXIT 跨距

透過使用 PHP 追蹤延伸，您可以建立 ENTRY 或 EXIT 類型的自訂跨距。

// get the tracer
$tracer = new \Instana\Tracer();

$entry_span = $tracer->createSpan('entry', \Instana\SPAN_ENTRY);

$exit_span = $tracer->createSpan('exit', \Instana\SPAN_EXIT);

設定母項跨距

當您使用 PHP SDK 建立新的跨距時，您可以設定母項跨距的 ID ，這在其他系統所建立的連續追蹤中可能很有用。 下列範例顯示相關程式碼 Snippet 必須如何外觀:

// get the tracer
$tracer = new \Instana\Tracer();

$span = $tracer->createSpan('entry', \Instana\SPAN_INTERMEDIATE, $parentId);

設定追蹤接續

使用 PHP 追蹤延伸，您可以透過傳訊系統來設定追蹤接續。 如果要這麼做，您需要將發佈者的追蹤環境定義注入訊息中，並在消費者端擷取它。

// get the tracer
$tracer = new \Instana\Tracer();

// GENERIC: an artificial message you want to send to your queue
$message = ['task' => 'convert-image'];

// retrieve the current trace context
$context = $tracer->getActiveContext();

// GENERIC: inject the current active context into your message, so you can retrieve it in the worker later
$attributes = $message['X-INSTANA-S'] = $context->getSpanId();
$attributes = $message['X-INSTANA-T'] = $context->getTraceId();

// send your message to the queue
$queue->publish($message);

// get the tracer
$tracer = new \Instana\Tracer();

// GENERIC: pull your message from the queue
$message = $queue->pull();

// GENERIC: extract trace context so we can continue the trace, assumes it's always present
$messageContext = new \Instana\TraceContext($message['X-INSTANA-T'], $message['X-INSTANA-S']);

// continue the trace that published the message
$tracer->continueTrace($messageContext);

// OPTIONAL: Create a span to wrap the unit of work
$span = $tracer->createSpan('work');
$span->annotate('job', 'my-important-job');

// do the actual work

// stop the optional span started above
$span->stop();

使用 Google Cloud Pub/Sub 設定追蹤接續

PHP 追蹤延伸會自動建立 EXIT 跨距，以用於與 Google Cloud Pub/Sub的送出互動。

若要繼續追蹤，您需要手動包裝耗用「發佈/訂閱」訊息的程式碼。

use Google\Cloud\PubSub\PubSubClient;

$tracer = new \Instana\Tracer();

$pubSub = new PubSubClient([
    'projectId' => $myProjectname
]);

$topic = $pubSub->topic($myTopicName);
$subscription = $pubSub->subscription($mySubscriptionName, $myTopicName);

$messages = $subscription->pull();
foreach ($messages as $message) {
    $attributes = $message->attributes();

    // extract the trace continouation headers from your message, assumes it's always present
    $messageContext = new \Instana\TraceContext($attributes['x-instana-t'], $attributes['x-instana-s']);

    // continue the trace that published the message
    $tracer->continueTrace($messageContext);

    // convert the current span
    $span = $tracer->getEntrySpan();
    $span->asGCPubSubReceive($project, 'php-consumer');

    // OPTIONAL: Create a span to wrap the unit of work
    $span = $tracer->createSpan('work');
    $span->annotate('job', 'my-important-job');

    // do the actual work

    // stop the optional span started above
    $span->stop();

    $subscription->acknowledge($message);
}

設定服務名稱

當您使用 PHP SDK 建立文字段時，可以手動使用 PHP-SDK 函數來設定 INSTANA_SERVICE_NAME 。 此值的優先順序高於 $__ENV 和 $_SERVER 陣列中設定的 INSTANA_SERVICE_NAME 值。 下列範例顯示相關程式碼 Snippet 的外觀:

//get the tracer
$tracer = new \Instana\Tracer();

Instana\Tracer::setServiceName(“MY_SERVICE_NAME”);

移除 SDK

當您移除 PHP 追蹤延伸時，也必須移除任何手動新增的 SDK 程式碼; 否則， PHP 會因遺漏函數而無法執行 Script。