设置 Ruby 版 Cloud Trace

您可以使用 Ruby 版 Cloud Trace 库为 Ruby 应用启用 Cloud Trace。

安装库

  1. 安装 Ruby 2.2+ 或更高版本。

  2. 将 Stackdriver gem 添加到 Gemfile:

    gem "stackdriver"
  3. 使用 bundler 安装 gem:

    bundle install
    

启用库

Rails

如果您正在使用 Ruby on Rails,Bundler 会在启动时自动将库加载到您的应用中。

非 Rails

其他基于 Rack 的应用可以使用库提供的 Rack Middleware:

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

如需了解更多信息或报告有关库的问题,请参阅库的源代码库

配置客户端

您可以自定义 Ruby 版 Cloud Trace 库的行为。如需查看可能的配置选项的列表,请参阅库的配置

添加自定义 Trace span

Ruby 版 Stackdriver Trace 库会自动为您的 Rack 应用收到的每个请求创建跟踪记录。您还可以在每个请求中添加自定义跟踪 span:

Google::Cloud::Trace.in_span "my_task" do |_span|
  # Insert task

  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
    # Insert subtask
  end
end

配置平台

您可以在 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 角色。如需查看说明,请参阅创建服务账号

Ruby 版 Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。以下部分介绍了如何设置这些凭据和 Google Cloud 项目 ID。

设置 Google Cloud 项目 ID 和凭据

本部分介绍了您在 Ruby 应用中设置 Google Cloud 项目 ID 和/或身份验证凭据时可使用的三种不同方法。

环境变量

如果您未明确设置 Google Cloud 项目 ID,则 google-cloud Ruby 库会自动确定是否设置了环境变量 GOOGLE_CLOUD_PROJECT;如果已设置,则该库会将 GOOGLE_CLOUD_PROJECT 的值用作您的 Google Cloud 项目 ID。如需了解详情,请参阅身份验证

如前所述,Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。您可以通过设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量来提供这些凭据:

Linux/macOS

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

Windows

命令窗口:

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"

Ruby on Rails 配置界面

如果您正在使用 Ruby on Rails,则可以通过 Ruby on Rails 配置界面提供参数:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Trace specific parameters
  config.google_cloud.trace.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.trace.keyfile    = "/path/to/service-account.json"
end

您还可以使用以下命令为所有 Stackdriver gem 设置共享配置:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

如果 Rails 在生产模式下运行,则默认启用 Trace。要在开发模式下启用 Trace,请添加以下内容:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_trace = true
end

插桩配置界面

在基于 Rack 的其他应用中使用时,请通过配置界面提供参数,将此作为 Ruby 的另一种替代方案:

require "google/cloud/trace"

Google::Cloud.configure do |config|
  # Stackdriver Trace specific parameters
  config.trace.project_id = "YOUR-PROJECT-ID"
  config.trace.keyfile    = "/path/to/service-account.json"
end

您还可以使用以下代码为所有 Stackdriver gem 设置共享配置:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

查看跟踪记录

在 Google Cloud 控制台的导航面板中,选择 Trace,然后选择 Trace 探索器

转到 Trace 探索器

问题排查

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

资源