Cloud Trace API - Module Google::Cloud::Trace (v0.42.0)

Reference documentation and code samples for the Cloud Trace API module Google::Cloud::Trace.

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.

Methods

.configure

def self.configure() -> 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
  • 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
  • (Google::Cloud.configure.trace)
Returns
  • (Google::Cloud::Config) — The configuration object the Google::Cloud::Trace module uses.

.get

def self.get() -> Google::Cloud::Trace::TraceSpan, Google::Cloud::Trace::TraceRecord, nil

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

Returns
Example 
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"

.in_span

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

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

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
Example 
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

.new

def self.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.

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)
Example 
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

.set

def self.set(trace)

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 Trace.get to retrieve the data.

Parameter
Example 
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"

Constants

THREAD_KEY

value: :stackdriver_trace_span

VERSION

value: "0.42.0".freeze