PHP SDK

Installing the SDK

The stubs of the PHP SDK can be installed through the Composer with the following command:

composer require instana/instana-php-sdk

The stubs ensure that when the PHP process is not monitored with Instana, all calls to the SDK APIs result in no-op, rather than errors.

Stubs of the PHP SDK to be used with your IDE are available on Packagist.

Example of SDK usage

$tracer = new \Instana\Tracer();

// sets the globaly service name without having to use the INSTANA_SERVICE_NAME variable
$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();
}

Creating custom ENTRY and EXIT spans

By using PHP tracing extension, you can create custom spans of ENTRY or EXIT type.

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

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

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

Setting tags

// get the tracer
$tracer = new \Instana\Tracer();
$entry_span = $tracer->createSpan('entry', \Instana\SPAN_ENTRY);
$entry_span->annotate('service', 'my service')

Setting parent span

When you create a new span with PHP SDK, you can set the ID of the parent span, which can be useful in continuation traces that are created by other system. The following example shows how the relevant code snippet must look:

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

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

Setting trace continuation

With the PHP tracing extension, you can set trace continuation through messaging systems. To do so, you need to inject the trace context of the publisher into the message and extract it on the consumer side.

// 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();

Setting trace continuation with Google Cloud Pub/Sub

The PHP tracing extension automatically creates EXIT spans for outgoing interactions with Google Cloud Pub/Sub.

For trace continuation, you need to manually wrap the code that consumes the Pub/Sub messages.

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);
}

Setting service name

When you create a span with PHP SDK, you can set INSTANA_SERVICE_NAME by using PHP-SDK functions manually. This value takes higher precedence than the INSTANA_SERVICE_NAME values set in the $__ENV and $_SERVER arrays. The following example shows how the relevant code snippet looks like:

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

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

Removing the SDK

When you remove the PHP tracing extension, you must also remove any manually added SDK code; otherwise, PHP fails script execution due to missing functions.