stackdriver-core - Class Stackdriver::Core::TraceContext (v1.5.0)

Reference documentation and code samples for the stackdriver-core class Stackdriver::Core::TraceContext.

A Stackdriver trace context links the current request into a performance trace, and communicates tracing options between related requests. This functionality is used by the Stackdriver diagnostics libraries (including google-cloud-trace, google-cloud-logging, and other rubygems) that integrate with the tracing service.

Most applications will not need to use the TraceContext class directly. The Stackdriver libraries use it internally to store and propagate context information.

Inherits

Object

Methods

.get

def self.get() -> TraceContext, nil

Returns the current thread's trace context, or nil if no trace context has been set.

Returns

(TraceContext, nil)

Example

require "stackdriver/core"

ctx = Stackdriver::Core::TraceContext.new
Stackdriver::Core::TraceContext.set ctx
same_ctx = Stackdriver::Core::TraceContext.get

.parse_rack_env

def self.parse_rack_env(env) -> TraceContext

Obtains a TraceContext from the given Rack environment. This should be used by any service that wants to obtain the TraceContext for a Rack request. If a new trace context is generated in the process, it is memoized into the Rack environment so subsequent services will get the same context.

Specifically, the following steps are attempted in order:

Attempts to use any memoized context previously obtained.
Attempts to parse the trace context header.
Creates a new trace context with a random trace ID.

Furthermore, if a block is given, it is provided with an opportunity to modify the trace context. The current trace context and the Rack environment is passed to the block, and its result is used as the final trace context. The final context is memoized back into the Rack environment.

Parameter

env (Hash) — The Rack environment hash

Returns

(TraceContext)

Example

require "stackdriver/core"

class MyMiddleware
  def initialize app
    @app = app
  end

  def call env
    ctx = Stackdriver::Core::TraceContext.parse_rack_env env
    do_something_with ctx
    @app.call env
  end
end

.parse_string

def self.parse_string(str) -> TraceContext, nil

Attempts to parse the given string as a trace context representation. Expects the form <traceid>[/<spanid>][;o=<options>], which is the form used in the trace context header. Returns either the parsed trace context, or nil if the string was malformed.

Parameter

str (String) — The string to parse.

Returns

(TraceContext, nil)

Example

require "stackdriver/core"

str = "0123456789abcdef0123456789abcdef/12345;o=1"
ctx = Stackdriver::Core::TraceContext.parse_string str

.set

def self.set(trace_context) -> TraceContext, nil

Set the current thread's trace context, and returns the context.

Parameter

trace_context (TraceContext, nil) — The trace context to set for the current thread. May be nil.

Returns

(TraceContext, nil) — The context set.

Example

require "stackdriver/core"

ctx = Stackdriver::Core::TraceContext.new
Stackdriver::Core::TraceContext.set ctx
same_ctx = Stackdriver::Core::TraceContext.get

#==

def ==(other) -> Boolean

Alias Of: #eql?

Standard value equality check for this object.

Parameter

other (Object) — An object to compare with.

Returns

(Boolean)

#capture_stack?

def capture_stack?() -> Boolean, nil

Returns true if the context wants to capture stack traces, false if the context does not, or nil if the context does not specify a sampling decision.

Returns

(Boolean, nil)

#eql?

def eql?(other) -> Boolean

Aliases

Standard value equality check for this object.

Parameter

other (Object) — An object to compare with.

Returns

(Boolean)

#hash

def hash() -> Integer

Generate standard hash code for this object.

Returns

(Integer)

#initialize

def initialize(trace_id: nil, is_new: nil, span_id: nil, sampled: nil, capture_stack: false) -> TraceContext

Create a new TraceContext instance.

Parameters

trace_id (String) (defaults to: nil) — The trace ID as a hex string. If nil or omitted, a new random Trace ID will be generated, and this TraceContext will be marked as new.
is_new (Boolean) (defaults to: nil) — Whether this trace context should be flagged as newly created. Optional: if unset, will reflect whether a new trace_id was generated when this object was created.
span_id (Integer) (defaults to: nil) — The context parent span ID as a 64-bit int. If nil or omitted, the context will specify no parent span.
sampled (Boolean) (defaults to: nil) — Whether the context has decided to sample this trace or not, or nil if the context does not specify a sampling decision.
capture_stack (Boolean) (defaults to: false) — Whether the the context has decided to capture stack traces. Ignored if sampled is not true.

Returns

(TraceContext) — a new instance of TraceContext

Example

require "stackdriver/core"

trace_id = "0123456789abcdef0123456789abcdef"
ctx = Stackdriver::Core::TraceContext.new trace_id: trace_id,
                                          sampled: true

#new?

def new?() -> Boolean

Returns true if this trace includes a newly generated trace_id.

Returns

(Boolean)

#sampled?

def sampled?() -> Boolean, nil

Returns true if the context wants to sample, false if the context wants explicitly to disable sampling, or nil if the context does not specify.

Returns

(Boolean, nil)

#span_id

def span_id() -> Integer, nil

The span ID, as a 64-bit integer, or nil if no span ID is present in the context.

Returns

(Integer, nil)

#to_s

def to_s() -> String

Alias Of: #to_string

Returns a string representation of this trace context, in the form <traceid>[/<spanid>][;o=<options>]. This form is suitable for setting the trace context header.

Returns

(String)

#to_string

def to_string() -> String

Aliases

#to_s

Returns a string representation of this trace context, in the form <traceid>[/<spanid>][;o=<options>]. This form is suitable for setting the trace context header.

Returns

(String)

#trace_id

def trace_id() -> String

The trace ID, as a hex string.

Returns

(String)

#with

def with(trace_id: UNCHANGED, is_new: UNCHANGED, span_id: UNCHANGED, sampled: UNCHANGED, capture_stack: UNCHANGED) -> TraceContext

Returns a new TraceContext instance that is identical to this instance except for the given changes. All parameters are optional. See #initialize for more details on each parameter.

Parameters

trace_id (String) (defaults to: UNCHANGED) — New trace ID.
is_new (Boolean) (defaults to: UNCHANGED) — New setting for newness indicator.
span_id (Integer) (defaults to: UNCHANGED) — New parent span ID.
sampled (Boolean) (defaults to: UNCHANGED) — New sampling decision.
capture_stack (Boolean) (defaults to: UNCHANGED) — New stack capture decision.

Returns

(TraceContext)

Example

require "stackdriver/core"

trace_id = "0123456789abcdef0123456789abcdef"
orig_ctx = Stackdriver::Core::TraceContext.new trace_id: trace_id,

sampled_ctx = orig_ctx.with sampled: true