Setting up Stackdriver Trace for PHP

You can enable Stackdriver Trace for PHP applications by using OpenCensus. OpenCensus is a set of instrumentation libraries for collecting trace and metric data that work with multiple backends. For the latest details about OpenCensus for PHP, along with additional documentation and examples, go to opencensus-php-exporter-stackdriver.

Installing the library

  1. Install the OpenCensus Stackdriver exporter composer package:

    composer require opencensus/opencensus-exporter-stackdriver

    The previous command also installs the OpenCensus and Trace composer packages.

  2. To use the framework integrations described in a later section on this page, install the OpenCensus extension:

    pecl install opencensus-alpha

  3. Add the following line to your php.ini file:

    extension=opencensus.so

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

    extension=opencensus.dll

Configuring the client

To enable the OpenCensus library for PHP, complete the following steps:

  1. Import the required classes:

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

  2. Initialize the StackdriverExporter object:

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

    If you are running on GCP infrastructure, then you don't need to set projectId to your GCP project ID. If you don't set this field, the client library for PHP automatically gathers this data from a GCP metadata server.

    If you aren't running on GCP infrastructure, then you must supply your GCP project ID to your application.

    Regardless of your infrastructure, for PHP, when you don't explicitly set the GCP project ID, the google-cloud PHP library, which is invoked by OpenCensus, automatically determines if the environment variable GOOGLE_CLOUD_PROJECT is set, and if so, the library uses the value of GOOGLE_CLOUD_PROJECT as your GCP project ID. For more information, see Authentication. To set the environment variable, do the following:

    Linux or macOS

    export GOOGLE_CLOUD_PROJECT=your-project-id

    Windows

    set GOOGLE_CLOUD_PROJECT=your-project-id

    PowerShell:

    $env:GOOGLE_CLOUD_PROJECT="your-project-id"

  3. Start the tracer:

    Tracer::start($exporter);

Create the exporter and start the tracer as early as possible in your application.

Customizations

You can customize the behavior of the Stackdriver Trace library for PHP. For a list of exporter configuration options, go to opencensus-php-exporter-stackdriver or to OpenCensus PHP API.

App Engine flexible environment lets you reduce the performance impact of reporting trace data by having the data sent by a background process. To enable background reporting, do the following:

  1. Modify the runtime_config section of your app.yaml file to specify the enable_stackdriver_integration flag:

    enable_stackdriver_integration: true

    This flag causes the PHP batch processing daemon, BatchRunner, to be spawned.

  2. Set the environment variable IS_BATCH_DAEMON_RUNNING to true.

  3. Include the async option with the value set to true in the clientConfig options passed to the OpenCensus StackdriverExporter. For more details, see StackdriverExporter.

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:

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

Framework integrations

The OpenCensus library provides useful integrations for web frameworks and functions. For more details, go to available integrations and examples for some frameworks.

Configuring your platform

You can use Trace on GCP and when your application runs outside of GCP.

Running on GCP

When your application is running on GCP, your application is automatically authenticated and you don't need to provide authentication credentials. However, you do need to ensure that your GCP platform has the Stackdriver Trace API access scope enabled.

For the following configurations, the default settings for the access scopes have the Stackdriver Trace API enabled:

  • App Engine flexible environment

  • App Engine standard environment

  • Google Kubernetes Engine

  • Compute Engine

If you use custom access scopes, then you must ensure that Stackdriver Trace API access scope enabled. For gcloud users, specify access scopes using the --scopes flag and include the trace.append Stackdriver Trace API access scope. For example, to create a GKE cluster with only the Stackdriver Trace API enabled, do the following:

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

Running locally and elsewhere

When your application is running outside of GCP, you must provide authentication credentials in the form of a service account to the client library. The service account must contain the Cloud Trace agent role. For instructions, see Creating a service account.

GCP client libraries use Application default credentials (ADC) to find your application's credentials. You provide these credentials by setting the GOOGLE_APPLICATION_CREDENTIALS environment variable:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Viewing the traces

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

Go to the Trace Viewer page

Resources

Was this page helpful? Let us know how we did:

Send feedback about...

This page
Documentation feedback
Stackdriver Trace
Product feedback
Need help? Visit our support page.