Module: Google::Cloud::Trace

Defined in:
lib/google/cloud/trace.rb,
lib/google/cloud/trace/v2.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/v1/doc/overview.rb,
lib/google/cloud/trace/v2/doc/overview.rb,
lib/google/cloud/trace/faraday_middleware.rb,
lib/google/cloud/trace/v1/trace_service_client.rb,
lib/google/cloud/trace/v2/trace_service_client.rb

Overview

Ruby Client for Stackdriver Trace API (Beta)

Stackdriver Trace API: Sends application trace data to Stackdriver Trace for viewing. Trace data is collected for all App Engine applications by default. Trace data from other applications can be provided using this API.

Quick Start

In order to use this library, you first need to go through the following steps:

  1. Select or create a Cloud Platform project.
  2. Enable billing for your project.
  3. Enable the Stackdriver Trace API.
  4. Setup Authentication.

Installation

$ gem install google-cloud-trace

Preview

TraceServiceClient

require "google/cloud/trace"

trace_service_client = Google::Cloud::Trace.new
formatted_name = Google::Cloud::Trace::V2::TraceServiceClient.project_path(project_id)
spans = []
trace_service_client.batch_write_spans(formatted_name, spans)

Next Steps

Defined Under Namespace

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

Constant Summary collapse

THREAD_KEY = 
:__stackdriver_trace_span__
VERSION = 
"0.33.0".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.trace| ... } ⇒ Google::Cloud::Config

Configure the Stackdriver Trace instrumentation Middleware.

The following Stackdriver Trace configuration parameters are supported:

  • project_id - (String) Project identifier for the Stackdriver Trace service you are connecting to. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • timeout - (Integer) Default timeout to use in requests.
  • client_config - (Hash) A hash of values to override the default behavior of the API client.
  • capture_stack - (Boolean) Whether to capture stack traces for each span. Default: false
  • sampler - (Proc) A sampler Proc makes the decision whether to record a trace for each request. Default: Google::Cloud::Trace::TimeSampler
  • span_id_generator - (Proc) A generator Proc that generates the name String for new TraceRecord. Default: random numbers
  • notifications - (Array) An array of ActiveSupport notification types to include in traces. Rails-only option. Default: Google::Cloud::Trace::Railtie::DEFAULT_NOTIFICATIONS
  • max_data_length - (Integer) The maximum length of span properties recorded with ActiveSupport notification events. Rails-only option. Default: Google::Cloud::Trace::Notifications::DEFAULT_MAX_DATA_LENGTH

See the Configuration Guide for full configuration parameters.

Yields:

Returns:

  • (Google::Cloud::Config) —

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



298
299
300
301
302
 
# File 'lib/google/cloud/trace.rb', line 298

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:



366
367
368
 
# File 'lib/google/cloud/trace.rb', line 366

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



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/google/cloud/trace.rb', line 401

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_id: nil, credentials: nil, scope: nil, timeout: nil, client_config: nil, project: nil, keyfile: 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_id (String) —

    Project identifier for the Stackdriver Trace service you are connecting to. If not present, the default project for the credentials is used.

  • credentials (String, Hash, Google::Auth::Credentials) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

  • 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.

  • project (String) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/google/cloud/trace.rb', line 236

def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
             client_config: nil, project: nil, keyfile: nil
  project_id ||= (project || default_project_id)
  project_id = project_id.to_s # Always cast to a string
  raise ArgumentError, "project_id is missing" if project_id.empty?

  scope ||= configure.scope
  timeout ||= configure.timeout
  client_config ||= configure.client_config

  credentials ||= (keyfile || default_credentials(scope: scope))
  unless credentials.is_a? Google::Auth::Credentials
    credentials = Trace::Credentials.new credentials, scope: scope
  end

  Trace::Project.new(
    Trace::Service.new(
      project_id, 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:



341
342
343
344
345
 
# File 'lib/google/cloud/trace.rb', line 341

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