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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#parent ⇒ SpanContext? (readonly)

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

Returns:



77
78
79
 
# File 'lib/opencensus/trace/span_context.rb', line 77

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) 


140
141
142
 
# File 'lib/opencensus/trace/span_context.rb', line 140

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) 


132
133
134
 
# File 'lib/opencensus/trace/span_context.rb', line 132

def span_id
  @span_id
end

#trace_options ⇒ Integer (readonly)

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

Returns:

  • (Integer) 


124
125
126
 
# File 'lib/opencensus/trace/span_context.rb', line 124

def trace_options
  @trace_options
end

Class Method Details

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

Create a new root SpanContext object, given either a traceparent header value by itself, or an entire Rack environment. If a valid traceparent 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:



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

def create_root trace_context: nil, same_process_as_parent: nil
  if trace_context
    trace_data = TraceData.new trace_context.trace_id, {}
    new trace_data, nil, trace_context.span_id,
        trace_context.trace_options, 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, {}
    new trace_data, nil, "", 0, 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



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

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

#end_span(span) ⇒ Object

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

Parameters:



222
223
224
225
226
227
 
# File 'lib/opencensus/trace/span_context.rb', line 222

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 OpenCensus::Trace::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:



206
207
208
209
210
211
212
213
214
 
# File 'lib/opencensus/trace/span_context.rb', line 206

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:



93
94
95
96
97
98
99
 
# File 'lib/opencensus/trace/span_context.rb', line 93

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) 


84
85
86
 
# File 'lib/opencensus/trace/span_context.rb', line 84

def root?
  parent.nil?
end

#sampled? ⇒ boolean

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

Returns:

  • (boolean) 


148
149
150
 
# File 'lib/opencensus/trace/span_context.rb', line 148

def sampled?
  trace_options & 0x01 != 0
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 OpenCensus::Trace::SpanBuilder methods. The span will be started automatically with the current timestamp. However, you are responsible for finishing the span yourself.

Parameters:

Returns:

  • (SpanBuilder) —

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



175
176
177
178
179
180
181
182
 
# File 'lib/opencensus/trace/span_context.rb', line 175

def start_span name, kind: nil, skip_frames: 0, sampler: nil
  child_context = create_child sampler
  span = SpanBuilder.new child_context, 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.



237
238
239
 
# File 'lib/opencensus/trace/span_context.rb', line 237

def this_span
  get_span @span_id
end

#trace_context ⇒ TraceContextData

Returns the trace context for this span.

Returns:



106
107
108
 
# File 'lib/opencensus/trace/span_context.rb', line 106

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) 


115
116
117
 
# File 'lib/opencensus/trace/span_context.rb', line 115

def trace_id
  @trace_data.trace_id
end