Class: OpenCensus::Trace::SpanContext

Inherits:
Object
  • Object
show all
Defined in:
lib/opencensus/trace/span_context.rb

Overview

SpanContext represents the context within which a span may be created. It includes the ID of the parent trace, the ID of the parent span, and sampling state.

Defined Under Namespace

Classes: TraceData

Constant Summary collapse

MAX_TRACE_ID =

Maximum integer value for a ‘trace_id`

0xffffffffffffffffffffffffffffffff
MAX_SPAN_ID =

Maximum integer value for a ‘span_id`

0xffffffffffffffff

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(trace_data, parent, span_id, same_process_as_parent) ⇒ SpanContext

Initialize a SpanContext object. This low-level constructor is used internally only. Generally, you should create a SpanContext using the ‘SpanContext.create_root` method.



287
288
289
290
291
292
 
# File 'lib/opencensus/trace/span_context.rb', line 287

def initialize trace_data, parent, span_id, same_process_as_parent
  @trace_data = trace_data
  @parent = parent
  @span_id = span_id
  @same_process_as_parent = same_process_as_parent
end

Instance Attribute Details

#parent ⇒ SpanContext? (readonly)

The parent of this context, or ‘nil` if this is a root context.

Returns:



80
81
82
 
# File 'lib/opencensus/trace/span_context.rb', line 80

def parent
  @parent
end

#same_process_as_parent ⇒ boolean? (readonly)

Whether the parent of spans created by this context is local, or ‘nil` if this context creates root spans or this information is unknown.

Returns:

  • (boolean, nil) 


145
146
147
 
# File 'lib/opencensus/trace/span_context.rb', line 145

def same_process_as_parent
  @same_process_as_parent
end

#span_id ⇒ String (readonly)

The span ID as a 16-character hex string, or the empty string if the context refers to the root of the trace.

Returns:

  • (String) 


137
138
139
 
# File 'lib/opencensus/trace/span_context.rb', line 137

def span_id
  @span_id
end

Class Method Details

.create_root(trace_context: nil, same_process_as_parent: nil) ⇒ SpanContext

Create a new root SpanContext object, given either a Trace-Context header value by itself, or an entire Rack environment. If a valid Trace-Context header can be obtained from either source, it is used to generate the SpanContext. Otherwise, a new root context with a unique ‘trace_id` and a root `span_id` of “” is used.

Parameters:

  • trace_context (TraceContextData) (defaults to: nil) —

    The request’s incoming trace context (optional)

  • same_process_as_parent (boolean, nil) (defaults to: nil) —

    Set to ‘true` if the parent span is local, `false` if it is remote, or `nil` if there is no parent span or this information is not available.

Returns:



60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/opencensus/trace/span_context.rb', line 60

def create_root trace_context: nil, same_process_as_parent: nil
  if trace_context
    trace_data = TraceData.new \
      trace_context.trace_id, trace_context.trace_options, {}
    new trace_data, nil, trace_context.span_id,
        same_process_as_parent
  else
    trace_id = rand 1..MAX_TRACE_ID
    trace_id = trace_id.to_s(16).rjust(32, "0")
    trace_data = TraceData.new trace_id, 0, {}
    new trace_data, nil, "", nil
  end
end

Instance Method Details

#build_contained_spans(max_attributes: nil, max_stack_frames: nil, max_annotations: nil, max_message_events: nil, max_links: nil, max_string_length: nil) ⇒ Array<Span>

Builds spans under this context, and returns an array of built ‘Span` objects. Builds only spans that are both finished and sampled, and ignores others. The order of the generated spans is undefined.

Does not build any ancestor spans. If you want the entire span tree built, call this method on the ‘#root` context.

Parameters:

  • max_attributes (Integer, nil) (defaults to: nil) —

    The maximum number of attributes to save, or ‘nil` to use the config value.

  • max_stack_frames (Integer, nil) (defaults to: nil) —

    The maximum number of stack frames to save, or ‘nil` to use the config value.

  • max_annotations (Integer, nil) (defaults to: nil) —

    The maximum number of annotations to save, or ‘nil` to use the config value.

  • max_message_events (Integer, nil) (defaults to: nil) —

    The maximum number of message events to save, or ‘nil` to use the config value.

  • max_links (Integer, nil) (defaults to: nil) —

    The maximum number of links to save, or ‘nil` to use the config value.

  • max_string_length (Integer, nil) (defaults to: nil) —

    The maximum length in bytes for truncated strings, or ‘nil` to use the config value.

Returns:

  • (Array<Span>) —

    Built Span objects



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/opencensus/trace/span_context.rb', line 261

def build_contained_spans max_attributes: nil,
                          max_stack_frames: nil,
                          max_annotations: nil,
                          max_message_events: nil,
                          max_links: nil,
                          max_string_length: nil
  sampled_span_builders = contained_span_builders.find_all do |sb|
    sb.finished? && sb.sampled
  end
  sampled_span_builders.map do |sb|
    sb.to_span max_attributes: max_attributes,
               max_stack_frames: max_stack_frames,
               max_annotations: max_annotations,
               max_message_events: max_message_events,
               max_links: max_links,
               max_string_length: max_string_length
  end
end

#contained_span_builders ⇒ Array<SpanBuilder>

Returns all SpanBuilder objects created by this context or any descendant context. The order of the returned spans is undefined.

Returns:



316
317
318
319
320
321
322
323
 
# File 'lib/opencensus/trace/span_context.rb', line 316

def contained_span_builders
  builders = @trace_data.span_map.values
  if root?
    builders
  else
    builders.find_all { |sb| contains? sb.context.parent }
  end
end

#contains?(context) ⇒ boolean

Returns true if this context equals or is an ancestor of the given context.

Returns:

  • (boolean) 


301
302
303
304
305
306
307
 
# File 'lib/opencensus/trace/span_context.rb', line 301

def contains? context
  until context.nil?
    return true if context == self
    context = context.parent
  end
  false
end

#end_span(span) ⇒ Object

Finish the given span, which must have been created by this span context.

Parameters:



219
220
221
222
223
224
 
# File 'lib/opencensus/trace/span_context.rb', line 219

def end_span span
  unless span.context.parent == self
    raise "The given span was not created by this context"
  end
  span.finish!
end

#in_span(name, kind: nil, skip_frames: 0, sampler: nil) ⇒ Object

Create a new span in this context. You must pass a name for the span. All other span attributes should be set using the SpanBuilder methods.

The span will be started automatically with the current timestamp. The SpanBuilder will then be passed to the block you provide. The span will be finished automatically at the end of the block.

Parameters:

  • name (String) —

    Name of the span

  • kind (Symbol) (defaults to: nil) —

    Kind of span. Defaults to unspecified.

  • sampler (Sampler) (defaults to: nil) —

    Span-scoped sampler. If not provided, defaults to the trace configuration’s default sampler.



203
204
205
206
207
208
209
210
211
 
# File 'lib/opencensus/trace/span_context.rb', line 203

def in_span name, kind: nil, skip_frames: 0, sampler: nil
  span = start_span name, kind: kind, skip_frames: skip_frames + 1,
                          sampler: sampler
  begin
    yield span
  ensure
    end_span span
  end
end

#root ⇒ SpanContext

The root context, which may be this context or one of its ancestors.

Returns:



96
97
98
99
100
101
102
 
# File 'lib/opencensus/trace/span_context.rb', line 96

def root
  root = self
  until (parent = root.parent).nil?
    root = parent
  end
  root
end

#root? ⇒ boolean

Returns true if this is a root span context

Returns:

  • (boolean) 


87
88
89
 
# File 'lib/opencensus/trace/span_context.rb', line 87

def root?
  parent.nil?
end

#sampled? ⇒ boolean

Whether the context (e.g. the parent span) has been sampled. This information may be used in sampling decisions for new spans.

Returns:

  • (boolean) 


153
154
155
156
157
158
159
160
 
# File 'lib/opencensus/trace/span_context.rb', line 153

def sampled?
  span = this_span
  if span
    span.sampled
  else
    trace_options & 0x01 != 0
  end
end

#start_span(name, kind: nil, skip_frames: 0, sampler: nil) ⇒ SpanBuilder

Create a new span in this context. You must pass a name for the span. All other span attributes should be set using the SpanBuilder methods. The span will be started automatically with the current timestamp. However, you are responsible for finishing the span yourself.

Parameters:

  • name (String) —

    Name of the span

  • kind (Symbol) (defaults to: nil) —

    Kind of span. Defaults to unspecified.

  • sampler (Sampler) (defaults to: nil) —

    Span-scoped sampler. If not provided, defaults to the trace configuration’s default sampler.

Returns:

  • (SpanBuilder) —

    A SpanBuilder object that you can use to set span attributes and create children.



177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/opencensus/trace/span_context.rb', line 177

def start_span name, kind: nil, skip_frames: 0, sampler: nil
  child_context = create_child
  sampler ||= OpenCensus::Trace.config.default_sampler
  sampled = sampler.call span_context: self
  span = SpanBuilder.new child_context, sampled,
                         skip_frames: skip_frames + 1
  span.name = name
  span.kind = kind if kind
  span.start!
  @trace_data.span_map[child_context.span_id] = span
end

#this_span ⇒ SpanBuilder?

Returns the span that defines this context; that is, the span that is the parent of spans created by this context. Returns ‘nil` if this context is the root and doesn’t correspond to an actual span, or if the corresponding span is remote.

Returns:

  • (SpanBuilder, nil) —

    The span defining this context.



234
235
236
 
# File 'lib/opencensus/trace/span_context.rb', line 234

def this_span
  get_span @span_id
end

#trace_context ⇒ TraceContextData

Returns the trace context for this span.

Returns:



109
110
111
 
# File 'lib/opencensus/trace/span_context.rb', line 109

def trace_context
  TraceContextData.new trace_id, @span_id, trace_options
end

#trace_id ⇒ String

The trace ID, as a 32-character hex string.

Returns:

  • (String) 


118
119
120
 
# File 'lib/opencensus/trace/span_context.rb', line 118

def trace_id
  @trace_data.trace_id
end

#trace_options ⇒ Integer

The original trace options byte used to create this span context.

Returns:

  • (Integer) 


127
128
129
 
# File 'lib/opencensus/trace/span_context.rb', line 127

def trace_options
  @trace_data.trace_options
end