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

Overview

Ruby Client for Stackdriver Trace API (Alpha)

Stackdriver Trace API: Send and retrieve trace data from Stackdriver Trace. Data is generated and available by default for all App Engine applications. Data from other applications can be written to Stackdriver Trace for display, reporting, and analysis.

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 the Stackdriver Trace API.
  3. Setup Authentication.

Installation

$ gem install google-cloud-trace

Next Steps

Defined Under Namespace

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

Constant Summary collapse

THREAD_KEY = 
:__stackdriver_trace_span__
VERSION = 
"0.28.0".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.



361
362
363
364
365
 
# File 'lib/google/cloud/trace.rb', line 361

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:



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

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



334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/google/cloud/trace.rb', line 334

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:



236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# 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 || Trace::Project.default_project_id)
  project_id = project_id.to_s # Always cast to a string
  fail ArgumentError, "project_id is missing" if project_id.empty?

  credentials ||= (keyfile || Trace::Credentials.default(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:



274
275
276
277
278
 
# File 'lib/google/cloud/trace.rb', line 274

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