设置 PHP 版 Cloud Trace

您可以使用 OpenCensus 为 PHP 应用启用 Cloud Trace。OpenCensus 是一组用于收集兼容多个后端的跟踪记录数据和指标数据的插桩库。有关 PHP 版 OpenCensus 的最新详情以及其他文档和示例，请参阅 opencensus-php-exporter-stackdriver。

安装库

  1. 安装 OpenCensus Stackdriver 导出器 Composer 软件包：

    composer require opencensus/opencensus-exporter-stackdriver

    上一个命令还会安装 OpenCensus 和 Trace Composer 软件包。

  2. 如需使用本页稍后部分所述的框架集成，请安装 OpenCensus 扩展程序：

    pecl install opencensus-alpha

  3. 将以下行添加到 php.ini 文件中：

    extension=opencensus.so

  4. 如果您使用的是 Windows 系统，请将 DLL 文件从 pecl 下载页面下载到 PHP 安装的扩展目录中，并将以下代码行添加到您的 php.ini 文件中：

    extension=opencensus.dll

配置客户端

如需启用 PHP 版 OpenCensus 库，请完成以下步骤：

  1. 导入必需类：

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

  2. 初始化 StackdriverExporter 对象：

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

    如果您是在 Google Cloud 基础架构上运行，则无需将 projectId 设置为您的 Google Cloud 项目 ID。如果您未设置此字段，则 PHP 版客户端库会自动从 Google Cloud 元数据服务器收集此数据。

    如果您未在 Google Cloud 基础架构上运行，则必须向应用提供 Google Cloud 项目 ID。

    无论您的基础架构是什么，当您未明确设置 Google Cloud 项目 ID 时，OpenCensus 调用的 google-cloud PHP 库都会自动确定是否设置了环境变量 GOOGLE_CLOUD_PROJECT；如果已设置，则该库会将 GOOGLE_CLOUD_PROJECT 的值用作您的 Google Cloud 项目 ID。如需了解详情，请参阅身份验证。如需设置此环境变量，请执行以下操作：

    Linux 或 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. 启动跟踪器：

    Tracer::start($exporter);

创建导出器，并尽早在应用中启动跟踪器。

自定义设置

您可以自定义 PHP 版 Cloud Trace 库的行为。如需查看导出器配置选项列表，请转到 opencensus-php-exporter-stackdriver 或 OpenCensus PHP API。

借助 App Engine 柔性环境，您可以通过在后台进程中发送报告跟踪记录数据来降低该数据对性能的影响。如需启用后台报告，请执行以下操作：

  1. 修改 app.yaml 文件的 runtime_config 部分以指定 enable_stackdriver_integration 标志：

    enable_stackdriver_integration: true

    此标志会衍生 PHP 批处理守护程序 BatchRunner。

  2. 将环境变量 IS_BATCH_DAEMON_RUNNING 设置为 true。

  3. 在传递给 OpenCensus StackdriverExporter 的 clientConfig 选项中添加 async 选项并将值设置为 true。如需了解详情，请访问 StackdriverExporter。

添加自定义 Trace span

PHP 版 Cloud Trace 库会自动为每个 HTTP 请求创建跟踪记录。您还可以在该请求中添加自定义 Trace span：

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

框架集成

OpenCensus 库为网络框架和功能提供了有用的集成。如需了解详情，请转到可用集成和某些框架的示例。

配置平台

您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

在 Google Cloud 上运行

当您的应用在 Google Cloud 上运行时，您无需向客户端库提供服务账号形式的身份验证凭据。但是，您需要确保 Google Cloud Platform 已启用 Cloud Trace API 访问权限范围。

如需查看受支持的 Google Cloud 环境的列表，请参阅环境支持。

对于以下配置，默认的访问权限范围设置会启用 Cloud Trace API：

  • App Engine 柔性环境

  • App Engine 标准环境

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

如果您使用自定义访问权限范围，则必须确保已启用 Cloud Trace API 访问权限范围：

  • 如需了解如何使用 Google Cloud 控制台为环境配置访问权限范围，请参阅配置 Google Cloud 项目。

  • 对于 gcloud 用户，请使用 --scopes 标志指定访问权限范围，并添加 trace.append Cloud Trace API 访问权限范围。例如，如需创建仅启用了 Cloud Trace API 的 GKE 集群，请执行以下操作：

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

在本地和其他位置运行

如果您的应用在 Google Cloud 之外运行，则必须向客户端库提供服务账号形式的身份验证凭据。该服务账号必须包含 Cloud Trace Agent 角色。如需查看说明，请参阅创建服务账号。

Google Cloud 客户端库使用应用默认凭据 (ADC) 查找应用的凭据。

您可以通过以下三种方式之一提供这些凭据：

  • 运行：gcloud auth application-default login

  • 将服务帐号放置在操作系统的默认路径中。下面列出了 Windows 和 Linux 的默认路径：

    • Windows：%APPDATA%/gcloud/application_default_credentials.json

    • Linux：$HOME/.config/gcloud/application_default_credentials.json

  • 将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号的路径：

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"

查看跟踪记录

在 Google Cloud 控制台中，选择 Trace，然后选择  概览，或点击以下按钮：

转到 Trace 概览

问题排查

如需了解如何排查 Cloud Trace 的问题，请转到“问题排查”页面。

资源