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 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:
Import the classes
Initialize the exporter
Start the tracer
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:
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 don't need to provide authentication credentials for instances running on Google Cloud Platform, provided Stackdriver Trace API access scope is enabled on that instance. However, we recommend setting the broadest possible access scope for your instance and then using Cloud Identity and Access Management to restrict access.
App Engine flexible environment
On App Engine flexible environment, the Stackdriver Trace API access scope is enabled by default, and the OpenCensus client library 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 Stackdriver exporter, and use
enable_stackdriver_integration
in runtime_config
section in your
app.yaml file as follows:
See also the exporter's configuration.
App Engine standard environment
On App Engine standard environment, the Stackdriver Trace API access scope is enabled by default, and the OpenCensus client library can be used without providing credentials or a project ID.
GKE
On GKE, add the trace.append
OAuth access scope when creating the cluster:
gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append
You cannot change the access scopes of a cluster after creation.
Compute Engine
For 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:
- Select Compute Engine default service account for Service account
- Select Allow full access to all Cloud APIs for Access Scopes
To use something other than the Compute Engine default service account see the Creating and enabling service accounts for instances and Running locally and elsewhere sections. The important thing is that the service account you use has the Cloud Trace Agent role.
Running locally and elsewhere
To run Trace outside of GCP, you must supply your GCP project ID and appropriate service account credentials directly to 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:
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.
Download the service account's key credentials file to your computer. For instructions, see Creating and managing service account keys.
Provide your GCP project ID and the location of the credentials file to the Trace using either parameters (
project_id
andkeyfile
) or environment variables (GOOGLE_CLOUD_PROJECT
andGOOGLE_APPLICATION_CREDENTIALS
).
Using environment variables
Define the environment variables where they are visible to the Trace. If they are visible more widely, they could interfere with existing authorizations for other applications.
Linux/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.