Setting Up Stackdriver Trace for PHP

Alpha

This is an alpha release of the Stackdriver Trace library for PHP. These libraries might be changed in backward-incompatible ways and are not recommended for production use. They are not subject to any SLA or deprecation policy.

Stackdriver Trace can be enabled for PHP applications using the Stackdriver Trace library for PHP and the OpenCensus library for PHP.

Installing the library

Install the OpenCensus Stackdriver exporter composer package with the following command (this will also install OpenCensus and Stackdriver Trace composer packages):

composer require opencensus/opencensus-exporter-stackdriver

We recommend that you also install the OpenCensus extension with the following command:

pecl install opencensus-alpha

You also need to add the following line to your php.ini:

extension=opencensus.so

If you're on Windows, download the DLL file from pecl download page to your extension directory of your PHP installation and add the following line to your php.ini:

extension=opencensus.dll

The opencensus extension is required if you want to use the framework integrations described below.

Enabling the library

To enable the Stackdriver Trace library for PHP, complete the following steps:

1. Import the classes

   trace/trace-sample.php

   View on GitHub Feedback

   use OpenCensus\Trace\Exporter\StackdriverExporter;
   use OpenCensus\Trace\Tracer;
   

2. Initialize the exporter

   trace/trace-sample.php

   View on GitHub Feedback

   $exporter = new StackdriverExporter([
       'clientConfig' => [
           'projectId' => $projectId
       ]
   ]);

3. Start the tracer

   trace/trace-sample.php

   View on GitHub Feedback

   Tracer::start($exporter);

Put the code at the top of the script to get the best result.

Configuring the client

You can customize the behavior of the Stackdriver Trace library for PHP. See the exporter's configuration and the tracer's configuration for a list of possible configuration options.

Add Custom Trace Span

The Stackdriver Trace library for PHP automatically creates a trace record for each HTTP request. You can also add custom trace spans within the request:

trace/trace-sample.php

View on GitHub Feedback

Tracer::inSpan(
    ['name' => 'slow_function'],
    function () {
        sleep(1);
    }
);

Framework integrations

The OpenCensus library provides useful integrations for web frameworks and functions. See available integrations and examples for some frameworks for more details.

Running on Google Cloud Platform

You do not need to provide authentication credentials for instances running on Google Cloud Platform, as long as the Stackdriver Trace API access scope is enabled on that instance.

App Engine flexible environment

On Google App Engine, the Stackdriver Trace API access scope is enabled by default, and the Stackdriver Trace library for PHP can be used without providing credentials or a project ID.

App Engine flexible environment provides a performance optimization for reporting the trace data in a background process. Use async option when initializing the StackdriverExporter, and use enable_stackdriver_integration in runtime_config section in your app.yaml file as follows:

appengine/flexible/logging/app.yaml

View on GitHub Feedback

enable_stackdriver_integration: true

See also the exporter's configuration.

Kubernetes Engine

On Google Kubernetes Engine, you must explicitly add the trace.append OAuth scope when creating the cluster:

gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append

Compute Engine

For Google Compute Engine VM instances, you need to explicitly enable the trace.append Stackdriver Trace API access scope for each VM instance. When creating a new instance through the Google Cloud Platform Console, select the following values in the Identity and API access section of the Create an instance panel:

1. Select Compute Engine default service account for Service account
2. Select Allow full access to all Cloud APIs for Access Scopes

To use something other than the Compute Engine default service account, see the docs for Creating and Enabling Service Accounts for Instances and the Running locally and elsewhere section below. Most importantly, the service account you use should have the Cloud Trace Agent role.

Running locally and elsewhere

To run the Stackdriver Trace outside of Google Cloud Platform, you must supply your GCP project ID and appropriate service account credentials directly to Stackdriver Trace. This applies to running the library on your own workstation, on your datacenter's computers, or on the VM instances of another cloud provider. Here are the steps involved:

1. Create a new service account in your GCP project. It must contain at least the Cloud Trace Agent role. For instructions, see Creating a service account.

2. Download the service account's key credentials file to your computer. For instructions, see Creating and managing service account keys.

3. Provide your GCP project ID and the location of the credentials file to the Stackdriver Trace using either parameters (project_id and keyfile) or environment variables (GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS). These methods are shown below:

Define the environment variables where they are visible to the Stackdriver Trace. If they are visible more widely, they could interfere with existing authorizations for other applications.

Linux or macOS

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Windows

Command window:

set GOOGLE_CLOUD_PROJECT=your-project-id
set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Powershell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Viewing the traces

After deployment, you can view the traces in the GCP Console Trace Viewer.

Go to the Trace Viewer page