Ruby 用の Cloud Trace の設定

ベータ版

このプロダクトまたは機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 一般提供前のプロダクトと機能は「現状のまま」ご利用いただけますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

Ruby 用 Cloud Trace ライブラリを使用して、Ruby 用 Cloud Trace アプリケーションを有効にできます。

ライブラリのインストール

1. Ruby 2.2 以降をインストールします。

2. Gemfile に Stackdriver gem を追加します。

   gem "stackdriver"

3. Bundler を使用して gem をインストールします。

   bundle install
   

ライブラリの有効化

Rails

Ruby on Rails を使用している場合、Bundler は起動時に、ライブラリをアプリケーションに自動的に読み込みます。

Rails でない場合

他の Rack ベースのアプリケーションでは、ライブラリが提供する Rack ミドルウェアを使用できます。

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

ライブラリの詳細について、あるいはライブラリに関する問題を報告するには、ライブラリのソースコード リポジトリをご覧ください。

クライアントの構成

Ruby 用 Cloud Trace ライブラリの動作をカスタマイズできます。設定可能なオプションのリストについては、ライブラリの構成をご覧ください。

カスタム トレーススパンの追加

Ruby 用 Cloud Trace ライブラリは、Rack アプリケーションが受け取るリクエストごとにトレース レコードを自動的に作成します。各リクエスト内にカスタム トレーススパンを追加することもできます。

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

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

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloud での実行

アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。

サポートされている Google Cloud 環境の一覧については、環境サポートをご覧ください。

次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。

• App Engine フレキシブル環境

• App Engine スタンダード環境

• Google Kubernetes Engine（GKE）

  注: Autopilot を使用している場合、または GKE クラスタで Workload Identity Federation for GKE を有効にする場合は、Workload Identity Federation for GKE を使用するようにアプリケーションを構成します。

• Compute Engine

• Cloud Run

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。

• Google Cloud Console を使用して環境のアクセス スコープを構成する方法については、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 エージェント ロールが含まれている必要があります。手順については、サービス アカウントの作成をご覧ください。

Ruby 用 Google Cloud クライアント ライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用してアプリケーションの認証情報を検索します。次のセクションでは、これらの認証情報と Google Cloud プロジェクト ID を設定する方法について説明します。

Google Cloud プロジェクト ID と認証情報の設定

このセクションでは、Google Cloud プロジェクト ID、認証情報、またはその両方を Ruby アプリケーションで設定するために使用できる 3 つの方法について説明します。

環境変数

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

インストゥルメンテーションの構成インターフェース

Ruby のもう 1 つの代替方法は、他のラックベース アプリケーションで使用する場合に、構成インターフェースを介してパラメータを指定することです。

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 エクスプローラ] に移動

このページは、検索バーを使用して見つけることもできます。

トラブルシューティング

Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。

リソース

• ソースコード
• GitHub 公開バグトラッカー
• スタック オーバーフロー