Class: Google::Cloud::Trace::Railtie

Inherits:
Rails::Railtie
  • Object
show all
Defined in:
lib/google/cloud/trace/rails.rb

Overview

Rails integration for Stackdriver Trace

This Railtie is a drop-in Stackdriver Trace instrumentation plugin for Ruby on Rails applications. If present, it automatically instruments your Rails app to record performance traces and cause them to appear on your Stackdriver console.

Installation

To install this plugin, the gem google-cloud-trace must be in your Gemfile. You also must add the following line to your application.rb file:

require "google/cloud/trace/rails"

If you include the stackdriver gem in your Gemfile, the above is done for you automatically, and you do not need to edit your application.rb.

Configuration

The following Rails configuration options are recognized.

config.google_cloud.use_trace = true | false

Normally, tracing is activated when RAILS_ENV is set to production and credentials are available. You can override this and enable tracing in other environments by setting use_trace explicitly.

config.google_cloud.keyfile = "path/to/file"

If your application is running on Google Cloud Platform, it will automatically use credentials available to your project. However, if you are running an application locally or on a different hosting provider, you may provide a path to your credentials file using this configuration.

config.google_cloud.project_id = "my-project-id"

If your application is running on Google Cloud Platform, it will automatically select the project under which it is running. However, if you are running an application locally or on a different hosting provider, or if you want to log traces to a different project than you are using to host your application, you may provide the project ID.

config.google_cloud.trace.notifications = ["event1", "event2"]

By default, this Railtie subscribes to ActiveSupport notifications emitted by ActiveRecord queries, rendering, and emailing functions. See DEFAULT_NOTIFICATIONS. If you want to customize the list of notification types, edit the notifications configuration.

config.google_cloud.trace.max_data_length = 1024

The maximum length of span properties recorded with ActiveSupport notification events. Any property value larger than this length is truncated.

config.google_cloud.trace.capture_stack = true | false

Whether to capture the call stack with each trace span. Default is false.

Measuring custom functionality

To add a custom measurement to a request trace, use the classes provided in this library. Below is an example to get you started.

class MyController < ApplicationController
  def index
    Google::Cloud::Trace.in_span "Sleeping on the job!" do
      sleep rand
    end
    render plain: "Hello World!"
  end
end

Constant Summary collapse

DEFAULT_NOTIFICATIONS =

The default list of ActiveSupport notification types to include in traces.

[
  "sql.active_record",
  "render_template.action_view",
  "send_file.action_controller",
  "send_data.action_controller",
  "deliver.action_mailer"
].freeze

Class Method Summary collapse

Class Method Details

.project_id(config) ⇒ String

Return the effective project ID for this app, given a Rails config.

Parameters:

  • config (Rails::Railtie::Configuration) —

    The Rails.application.config

Returns:

  • (String) —

    The project ID, or nil if not found.



193
194
195
196
197
198
199
 
# File 'lib/google/cloud/trace/rails.rb', line 193

def self.project_id config
  config.google_cloud.trace.project_id ||
    config.google_cloud.project_id ||
    ENV["TRACE_PROJECT"] ||
    ENV["GOOGLE_CLOUD_PROJECT"] ||
    Google::Cloud.env.project_id
end

.use_trace?(config) ⇒ Boolean

Determine whether to use Stackdriver Trace or not.

Returns true if valid GCP project_id and keyfile are provided and either Rails is in "production" environment or config.google_cloud.use_trace is explicitly true. Otherwise false.

Parameters:

  • config (Rails::Railtie::Configuration) —

    The Rails.application.config

Returns:

  • (Boolean) —

    Whether to use Stackdriver Trace



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/google/cloud/trace/rails.rb', line 155

def self.use_trace? config
  gcp_config = config.google_cloud

  # Return false if config.google_cloud.use_trace is
  # explicitly false
  return false if gcp_config.key?(:use_trace) &&
                  !gcp_config.use_trace

  # Try authenticate authorize client API. Return false if unable to
  # authorize.
  keyfile = gcp_config.trace.keyfile || gcp_config.keyfile
  begin
    Google::Cloud::Trace::Credentials.credentials_with_scope keyfile
  rescue Exception => e
    STDOUT.puts "Note: Google::Cloud::Trace is disabled because " \
      "it failed to authorize with the service. (#{e.message})"
    return false
  end

  if project_id(config).to_s.empty?
    STDOUT.puts "Note: Google::Cloud::Trace is disabled because " \
      "the project ID could not be determined."
    return false
  end

  # Otherwise return true if Rails is running in production or
  # config.google_cloud.use_trace is explicitly true
  Rails.env.production? ||
    (gcp_config.key?(:use_trace) && gcp_config.use_trace)
end