Module: Google::Cloud::Trace

Defined in:
lib/google/cloud/trace.rb,
lib/google/cloud/trace/span.rb,
lib/google/cloud/trace/rails.rb,
lib/google/cloud/trace/utils.rb,
lib/google/cloud/trace/project.rb,
lib/google/cloud/trace/service.rb,
lib/google/cloud/trace/version.rb,
lib/google/cloud/trace/label_key.rb,
lib/google/cloud/trace/span_kind.rb,
lib/google/cloud/trace/middleware.rb,
lib/google/cloud/trace/result_set.rb,
lib/google/cloud/trace/credentials.rb,
lib/google/cloud/trace/time_sampler.rb,
lib/google/cloud/trace/trace_record.rb,
lib/google/cloud/trace/notifications.rb,
lib/google/cloud/trace/async_reporter.rb,
lib/google/cloud/trace/faraday_middleware.rb,
lib/google/cloud/trace/v1/trace_service_client.rb

Overview

Trace

The Stackdriver Trace service collects and stores latency data from your application and displays it in the Google Cloud Platform Console, giving you detailed near-real-time insight into application performance.

The Stackdriver Trace Ruby library, google-cloud-trace, provides:

  • Easy-to-use trace instrumentation that collects and collates latency data for your Ruby application. If you just want latency trace data for your application to appear on the Google Cloud Platform Console, see the section on instrumenting your app.
  • An idiomatic Ruby API for querying, analyzing, and manipulating trace data in your Ruby application. For an introduction to the Trace API, see the section on the Trace API.

Instrumenting Your App

This library integrates with Rack-based web frameworks such as Ruby On Rails to provide latency trace reports for your application. Specifcally, it:

  • Provides a Rack middleware that automatically reports latency traces for http requests handled by your application, and measures the latency of each request as a whole.
  • Integrates with ActiveSupport::Notifications to add important latency-affecting events such as ActiveRecord queries to the trace.
  • Provides a simple API for your application code to define and measure latency-affecting processes specific to your application.

When this library is installed and configured in your running application, you can view your application's latency traces in real time by opening the Google Cloud Console in your web browser and navigating to the "Trace" section. It also integrates with Google App Engine Flexible and Google Container Engine to provide additional information for applications hosted in those environments.

Note that not all requests will have traces. By default, the library will sample about one trace every ten seconds per Ruby process, to prevent heavily used applications from reporting too much data. It will also omit certain requests used by Google App Engine for health checking. See TimeSampler for more details.

Using instrumentation with Ruby on Rails

To install application instrumentation in your Ruby on Rails app, add this gem, google-cloud-trace, to your Gemfile and update your bundle. Then add the following line to your config/application.rb file:

require "google/cloud/trace/rails"

This will install a Railtie that automatically integrates with the Rails framework, installing the middleware and the ActiveSupport integration for you. Your application traces, including basic request tracing, ActiveRecord query measurements, and view render measurements, should then start appearing in the Cloud Console.

See the Railtie class for more information, including how to customize your application traces.

Using instrumentation with Sinatra

To install application instrumentation in your Sinatra app, add this gem, google-cloud-trace, to your Gemfile and update your bundle. Then add the following lines to your main application Ruby file:

require "google/cloud/trace"
use Google::Cloud::Trace::Middleware

This will install the trace middleware in your application, providing basic request tracing for your application. You may measure additional processes such as database queries or calls to external services using other classes in this library. See the Middleware documentation for more information.

Using instrumentation with other Rack-based frameworks

To install application instrumentation in an app using another Rack-based web framework, add this gem, google-cloud-trace, to your Gemfile and update your bundle. Then add install the trace middleware in your middleware stack. In most cases, this means adding these lines to your config.ru Rack configuration file:

require "google/cloud/trace"
use Google::Cloud::Trace::Middleware

Some web frameworks have an alternate mechanism for modifying the middleware stack. Consult your web framework's documentation for more information.

The Stackdriver diagnostics suite

The trace library is part of the Stackdriver diagnostics suite, which also includes error reporting and log analysis. If you include the stackdriver gem in your Gemfile, this trace library will be included automatically. In addition, if you include the stackdriver gem in an application using Ruby On Rails, the Railtie will be installed automatically; you will not need to write any code to view latency traces for your appl. See the documentation for the "stackdriver" gem for more details.

Stackdriver Trace API

This library also includes an easy to use Ruby client for the Stackdriver Trace API. This API provides calls to report and modify application traces, as well as to query and analyze existing traces.

For further information on the trace API, see Project.

Querying traces using the API

Using the Stackdriver Trace API, your application can query and analyze its own traces and traces of other projects. Here is an example query for all traces in the past hour.

require "google/cloud/trace"
trace_client = Google::Cloud::Trace.new

traces = trace_client.list_traces Time.now - 3600, Time.now
traces.each do |trace|
  puts "Retrieved trace ID: #{trace.trace_id}"
end

Each trace is an object of type TraceRecord, which provides methods for analyzing tasks that took place during the request trace. See https://cloud.google.com/trace for more information on the kind of data you can capture in a trace.

Reporting traces using the API

Usually it is easiest to use this library's trace instrumentation features to collect and record application trace information. However, you may also use the trace API to update this data. Here is an example:

require "google/cloud/trace"

trace_client = Google::Cloud::Trace.new

trace = Google::Cloud::Trace.new
trace.in_span "root_span" do
  # Do stuff...
end

trace_client.patch_traces trace

Defined Under Namespace

Modules: LabelKey, Notifications, V1 Classes: FaradayMiddleware, Middleware, Project, Railtie, ResultSet, Span, SpanKind, TimeSampler, TraceRecord

Constant Summary collapse

THREAD_KEY = 
:__stackdriver_trace_span__
VERSION = 
"0.27.2".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.trace| ... } ⇒ Stackdriver::Core::Configuration

Configure the Stackdriver Trace instrumentation Middleware.

See the Configuration Guide for full configuration parameters.

Yields:

Returns:

  • (Stackdriver::Core::Configuration) —

    The configuration object the Google::Cloud::ErrorReporting module uses.



355
356
357
358
359
 
# File 'lib/google/cloud/trace.rb', line 355

def self.configure
  yield Google::Cloud.configure.trace if block_given?

  Google::Cloud.configure.trace
end

.get ⇒ Google::Cloud::Trace::TraceSpan, ...

Retrieve the current trace span or trace object for the current thread. This data should previously have been set using set.

Examples:

require "google/cloud/trace"

trace_client = Google::Cloud::Trace.new
trace = trace_client.new_trace
Google::Cloud::Trace.set trace

# Later...
Google::Cloud::Trace.get.create_span "my_span"

Returns:



293
294
295
 
# File 'lib/google/cloud/trace.rb', line 293

def self.get
  Thread.current[THREAD_KEY]
end

.in_span(name, kind: Google::Cloud::Trace::SpanKind::UNSPECIFIED, labels: {}) ⇒ Object

Open a new span for the current thread, instrumenting the given block. The span is created within the current thread's trace context as set by set. The context is updated so any further calls within the block will create subspans. The new span is also yielded to the block.

Does nothing if there is no trace context for the current thread.

Examples:

require "google/cloud/trace"

trace_client = Google::Cloud::Trace.new
trace = trace_client.new_trace
Google::Cloud::Trace.set trace

Google::Cloud::Trace.in_span "my_span" do |span|
  span.labels["foo"] = "bar"
  # Do stuff...

  Google::Cloud::Trace.in_span "my_subspan" do |subspan|
    subspan.labels["foo"] = "sub-bar"
    # Do other stuff...
  end
end

Parameters:

  • name (String) —

    Name of the span to create

  • kind (Google::Cloud::Trace::SpanKind) —

    Kind of span to create. Optional.

  • labels (Hash{String => String}) —

    Labels for the span



328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/google/cloud/trace.rb', line 328

def self.in_span name, kind: Google::Cloud::Trace::SpanKind::UNSPECIFIED,
                 labels: {}
  parent = get
  if parent
    parent.in_span name, kind: kind, labels: labels do |child|
      set child
      begin
        yield child
      ensure
        set parent
      end
    end
  else
    yield nil
  end
end

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ Google::Cloud::Trace::Project

Creates a new object for connecting to the Stackdriver Trace service. Each call creates a new connection.

For more information on connecting to Google Cloud see the Authentication Guide.

Examples:

require "google/cloud/trace"

trace_client = Google::Cloud::Trace.new

traces = trace_client.list_traces Time.now - 3600, Time.now
traces.each do |trace|
  puts "Retrieved trace ID: #{trace.trace_id}"
end

Parameters:

  • project (String) —

    Project identifier for the Stackdriver Trace service.

  • keyfile (String, Hash) —

    Keyfile downloaded from Google Cloud: either the JSON data or the path to a readable file.

  • scope (String, Array<String>) —

    The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs. The default scope is https://www.googleapis.com/auth/cloud-platform

  • timeout (Integer) —

    Default timeout to use in requests. Optional.

Returns:



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/google/cloud/trace.rb', line 231

def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
             client_config: nil
  project ||= Google::Cloud::Trace::Project.default_project
  project = project.to_s # Always cast to a string
  fail ArgumentError, "project is missing" if project.empty?

  credentials =
    Google::Cloud::Trace::Credentials.credentials_with_scope keyfile,
                                                             scope

  Google::Cloud::Trace::Project.new(
    Google::Cloud::Trace::Service.new(
      project, credentials, timeout: timeout,
                            client_config: client_config))
end

.set(trace) ⇒ Object

Set the current trace span being measured for the current thread, or the current trace if no span is currently open. This may be used with web frameworks that assign a thread to each request, to track the trace instrumentation state for the request being handled. You may use get to retrieve the data.

Examples:

require "google/cloud/trace"

trace_client = Google::Cloud::Trace.new
trace = trace_client.new_trace
Google::Cloud::Trace.set trace

# Later...
Google::Cloud::Trace.get.create_span "my_span"

Parameters:



268
269
270
271
272
 
# File 'lib/google/cloud/trace.rb', line 268

def self.set trace
  trace_context = trace ? trace.trace_context : nil
  Stackdriver::Core::TraceContext.set trace_context
  Thread.current[THREAD_KEY] = trace
end