You can enable Cloud 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
Install the OpenCensus Stackdriver exporter composer package:
composer require opencensus/opencensus-exporter-stackdriver
The previous command also installs the OpenCensus and Trace composer packages.
To use the framework integrations described in a later section on this page, install the OpenCensus extension:
pecl install opencensus-alpha
Add the following line to your
php.ini
file:extension=opencensus.so
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:
Import the required classes:
Initialize the
StackdriverExporter
object:If you are running on Google Cloud infrastructure, then you don't need to set
projectId
to your Google Cloud project ID. If you don't set this field, the client library for PHP automatically gathers this data from a Google Cloud metadata server.If you aren't running on Google Cloud infrastructure, then you must supply your Google Cloud project ID to your application.
Regardless of your infrastructure, for PHP, when you don't explicitly set the Google Cloud project ID, the
google-cloud
PHP library, which is invoked by OpenCensus, automatically determines if the environment variableGOOGLE_CLOUD_PROJECT
is set, and if so, the library uses the value ofGOOGLE_CLOUD_PROJECT
as your Google Cloud 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"
Start the tracer:
Create the exporter and start the tracer as early as possible in your application.
Customizations
You can customize the behavior of the Cloud 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:
Modify the
runtime_config
section of yourapp.yaml
file to specify theenable_stackdriver_integration
flag:This flag causes the PHP batch processing daemon,
BatchRunner
, to be spawned.Set the environment variable
IS_BATCH_DAEMON_RUNNING
totrue
.Include the
async
option with the value set totrue
in theclientConfig
options passed to the OpenCensusStackdriverExporter
. For more details, seeStackdriverExporter
.
Add custom Trace span
The Cloud 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. For more details, go to available integrations and examples for some frameworks.
Configure your platform
You can use Cloud Trace on Google Cloud and other platforms.
Running on Google Cloud
When your application is running on Google Cloud, you don't need to provide authentication credentials in the form of a service account to the client library. However, you do need to ensure that your Google Cloud platform has the Cloud Trace API access scope enabled.
For the following configurations, the default access-scope settings enable the Cloud Trace API:
- App Engine flexible environment
App Engine standard environment
Google Kubernetes Engine (GKE)
Compute Engine
If you use custom access scopes, then you must ensure that
Cloud Trace API access scope
is enabled. For gcloud
users, specify access scopes using the --scopes
flag
and include the trace.append
Cloud Trace API access scope.
For example, to create a GKE cluster with only
the Cloud 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
If your application is running outside of Google Cloud, then 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.
Google Cloud 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 Cloud Console Trace Viewer.
Troubleshooting
For information on troubleshooting issues with Cloud Trace, go to the Troubleshooting page.
Resources
- OpenCensus
- GitHub:
census-ecosystem/opencensus-php-exporter-stackdriver
- OpenCensus PHP API
- Source code
- GitHub issue tracker
- Stack Overflow