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/credentials.rb,
lib/google/cloud/trace/v2/credentials.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 (Alpha)

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.

Preview

TraceServiceClient

require "google/cloud/trace/v2"

trace_service_client = Google::Cloud::Trace::V2.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.2".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.



150
151
152
153
154
 
# File 'lib/google/cloud/trace.rb', line 150

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:



218
219
220
 
# File 'lib/google/cloud/trace.rb', line 218

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



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/google/cloud/trace.rb', line 253

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) 


88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/google/cloud/trace.rb', line 88

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:



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

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