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/errors.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

Overview

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

See Stackdriver Trace Overview.

Defined Under Namespace

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

Constant Summary collapse

THREAD_KEY = 
:__stackdriver_trace_span__
VERSION = 
"0.44.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.
  • endpoint - (String) Override of the endpoint host name, or nil to use the default endpoint.
  • 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
  • on_error - (Proc) A Proc to be run when an error is encountered during the reporting of traces by the middleware. The Proc must take the error object as the single argument.

See the Configuration Guide for full configuration parameters.

Yields:

Returns:

  • (Google::Cloud::Config) —

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



154
155
156
157
158
 
# File 'lib/google/cloud/trace.rb', line 154

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:



231
232
233
 
# File 'lib/google/cloud/trace.rb', line 231

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) (defaults to: Google::Cloud::Trace::SpanKind::UNSPECIFIED) —

    Kind of span to create. Optional.

  • labels (Hash{String => String}) (defaults to: {}) —

    Labels for the span



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/google/cloud/trace.rb', line 266

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, endpoint: 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) (defaults to: nil) —

    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) (defaults to: nil) —

    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>) (defaults to: nil) —

    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) (defaults to: nil) —

    Default timeout to use in requests. Optional.

  • endpoint (String) (defaults to: nil) —

    Override of the endpoint host name. Optional. If the param is nil, uses the default endpoint.

  • project (String) (defaults to: nil) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) (defaults to: nil) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


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

def self.new project_id: nil,
             credentials: nil,
             scope: nil,
             timeout: nil,
             endpoint: nil,
             project: nil,
             keyfile: nil
  project_id    ||= project || default_project_id
  scope         ||= configure.scope
  timeout       ||= configure.timeout
  endpoint      ||= configure.endpoint
  credentials   ||= keyfile || default_credentials(scope: scope)

  credentials = resolve_credentials credentials, scope
  if credentials.respond_to? :project_id
    project_id ||= credentials.project_id
  end
  project_id = project_id.to_s # Always cast to a string
  raise ArgumentError, "project_id is missing" if project_id.empty?

  service = Trace::Service.new project_id, credentials, host: endpoint, timeout: timeout
  Trace::Project.new service
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:



206
207
208
209
210
 
# File 'lib/google/cloud/trace.rb', line 206

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