Class: OpenCensus::Trace::SpanBuilder

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

Overview

Span represents a single span within a request trace.

Defined Under Namespace

Classes: AnnotationBuilder, LinkBuilder, MessageEventBuilder, PieceBuilder

Constant Summary collapse

TYPE_UNSPECIFIED =

The type of a message event or link is unknown.

:TYPE_UNSPECIFIED
SENT =

Indicates a sent message.

:SENT
RECEIVED =

Indicates a received message.

:RECEIVED
CHILD_LINKED_SPAN =

The linked span is a child of the current span.

:CHILD_LINKED_SPAN
PARENT_LINKED_SPAN =

The linked span is a parent of the current span.

:PARENT_LINKED_SPAN

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(span_context, sampled, skip_frames: 0) ⇒ SpanBuilder

Initializer.



356
357
358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/opencensus/trace/span_builder.rb', line 356

def initialize span_context, sampled, skip_frames: 0
  @context = span_context
  @sampled = sampled
  @name = ""
  @start_time = nil
  @end_time = nil
  @attributes = {}
  @annotations = []
  @message_events = []
  @links = []
  @status_code = nil
  @status_message = nil
  @stack_trace = caller_locations(skip_frames + 2)
end

Instance Attribute Details

#context ⇒ SpanContext (readonly)

The context that can build children of this span.

Returns:



41
42
43
 
# File 'lib/opencensus/trace/span_builder.rb', line 41

def context
  @context
end

#end_time ⇒ Time?

The end time of the span. On the client side, this is the time kept by the local machine where the span execution ends. On the server side, this is the time when the server application handler stops running.

In Ruby, this is represented by a Time object in UTC, or ‘nil` if the starting timestamp has not yet been populated.

Returns:

  • (Time, nil) 


116
117
118
 
# File 'lib/opencensus/trace/span_builder.rb', line 116

def end_time
  @end_time
end

#name ⇒ String, TruncatableString

A description of the span’s operation.

For example, the name can be a qualified method name or a file name and a line number where the operation is called. A best practice is to use the same display name at the same call point in an application. This makes it easier to correlate spans in different traces.

This field is required.

Returns:



91
92
93
 
# File 'lib/opencensus/trace/span_builder.rb', line 91

def name
  @name
end

#sampled ⇒ boolean

Sampling decision for this span. Generally this field is set when the span is first created. However, you can also change it after the fact.

Returns:

  • (boolean) 


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

def sampled
  @sampled
end

#start_time ⇒ Time?

The start time of the span. On the client side, this is the time kept by the local machine where the span execution starts. On the server side, this is the time when the server’s application handler starts running.

In Ruby, this is represented by a Time object in UTC, or ‘nil` if the starting timestamp has not yet been populated.

Returns:

  • (Time, nil) 


104
105
106
 
# File 'lib/opencensus/trace/span_builder.rb', line 104

def start_time
  @start_time
end

Instance Method Details

#finish! ⇒ Object

Finish this span by setting the end time to the current time. Raises an exception if the start time is not yet set, or the end time is already set.



142
143
144
145
146
147
 
# File 'lib/opencensus/trace/span_builder.rb', line 142

def finish!
  raise "Span not yet started" if start_time.nil?
  raise "Span already finished" unless end_time.nil?
  @end_time = Time.now.utc
  self
end

#finished? ⇒ boolean

Whether this span is finished (i.e. has both a start and end time)

Returns:

  • (boolean) 


123
124
125
 
# File 'lib/opencensus/trace/span_builder.rb', line 123

def finished?
  !start_time.nil? && !end_time.nil?
end

#parent_span_id ⇒ String

The span ID of the parent, as a 16-character hex string, or the empty string if this is a root span.

Returns:

  • (String) 


67
68
69
 
# File 'lib/opencensus/trace/span_builder.rb', line 67

def parent_span_id
  context.parent.span_id
end

#put_annotation(description, attributes = {}, time: nil) ⇒ Object

Add an event annotation with a timestamp.

Parameters:

  • description (String) —

    Description of the event

  • attributes (Hash) (defaults to: {}) —

    Key-value pairs providing additional properties of the event. Keys must be strings, and values are restricted to the same types as attributes (see #put_attribute).

  • time (Time, nil) (defaults to: nil) —

    Timestamp of the event. Optional, defaults to the current time.



179
180
181
182
183
184
 
# File 'lib/opencensus/trace/span_builder.rb', line 179

def put_annotation description, attributes = {}, time: nil
  time ||= Time.now.utc
  annotation = AnnotationBuilder.new time, description, attributes
  @annotations << annotation
  self
end

#put_attribute(key, value) ⇒ Object

Add an attribute to this span.

Attributes are key-value pairs representing properties of this span. You could, for example, add an attribute indicating the URL for the request being handled, the user-agent, the database query being run, the ID of the logged-in user, or any other relevant information.

Keys must be strings. Values may be String, TruncatableString, Integer, or Boolean. The valid integer range is 64-bit signed ‘(-2^63..2^63-1)`.

Parameters:



164
165
166
167
 
# File 'lib/opencensus/trace/span_builder.rb', line 164

def put_attribute key, value
  @attributes[key.to_s] = value
  self
end

#put_link(trace_id, span_id, type, attributes = {}) ⇒ Object

Add a pointer from the current span to another span, which may be in the same trace or in a different trace. For example, this can be used in batching operations, where a single batch handler processes multiple requests from different traces or when the handler receives a request from a different project.

Parameters:

  • trace_id (String) —

    The unique identifier for a trace. A 16-byte array expressed as 32 hex digits.

  • span_id (String) —

    The unique identifier for a span within a trace. An 8-byte array expressed as 16 hex digits.

  • type (Symbol) —

    The relationship of the current span relative to the linked span. Valid values are ‘SpanBuilder::CHILD_LINKED_SPAN`, `SpanBuilder::PARENT_LINKED_SPAN`, and `SpanBuilder::TYPE_UNSPECIFIED`.

  • attributes (String) (defaults to: {}) —

    Key-value pairs providing additional properties of the link. Keys must be strings, and values are restricted to the same types as attributes (see #put_attribute).



233
234
235
236
237
 
# File 'lib/opencensus/trace/span_builder.rb', line 233

def put_link trace_id, span_id, type, attributes = {}
  link = LinkBuilder.new trace_id, span_id, type, attributes
  @links << link
  self
end

#put_message_event(type, id, uncompressed_size, compressed_size: nil, time: nil) ⇒ Object

Add an event describing a message sent/received between spans.

Parameters:

  • type (Symbol) —

    The type of MessageEvent. Indicates whether the message was sent or received. Valid values are ‘SpanBuilder::SENT` `SpanBuilder::RECEIVED`, and `SpanBuilder::TYPE_UNSPECIFIED`.

  • id (Integer) —

    An identifier for the MessageEvent’s message that can be used to match SENT and RECEIVED events. For example, this field could represent a sequence ID for a streaming RPC. It is recommended to be unique within a Span. The valid range is 64-bit unsigned ‘(0..2^64-1)`

  • uncompressed_size (Integer) —

    The number of uncompressed bytes sent or received.

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

    The number of compressed bytes sent or received. Optional.

  • time (Time, nil) (defaults to: nil) —

    Timestamp of the event. Optional, defaults to the current time.



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

def put_message_event type, id, uncompressed_size,
                      compressed_size: nil, time: nil
  time ||= Time.now.utc
  message_event =
    MessageEventBuilder.new time, type, id, uncompressed_size,
                            compressed_size
  @message_events << message_event
  self
end

#set_status(code, message = "") ⇒ Object

Set the optional final status for the span.

Parameters:

  • code (Integer) —

    Status code as a 32-bit signed integer

  • message (String) (defaults to: "") —

    A developer-facing error message, which should be in English.



245
246
247
248
249
 
# File 'lib/opencensus/trace/span_builder.rb', line 245

def set_status code, message = ""
  @status_code = code
  @status_message = message
  self
end

#span_id ⇒ String

The span ID, as a 16-character hex string.

Returns:

  • (String) 


57
58
59
 
# File 'lib/opencensus/trace/span_builder.rb', line 57

def span_id
  context.span_id
end

#start! ⇒ Object

Start this span by setting the start time to the current time. Raises an exception if the start time is already set.



131
132
133
134
135
 
# File 'lib/opencensus/trace/span_builder.rb', line 131

def start!
  raise "Span already started" unless start_time.nil?
  @start_time = Time.now.utc
  self
end

#to_span(max_attributes: nil, max_stack_frames: nil, max_annotations: nil, max_message_events: nil, max_links: nil, max_string_length: nil, child_span_count: nil) ⇒ Span

Return a read-only version of this span

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.

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

    The number of child spans to declare, or ‘nil` to omit the `child_span_count` field.

Returns:



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/opencensus/trace/span_builder.rb', line 299

def to_span max_attributes: nil,
            max_stack_frames: nil,
            max_annotations: nil,
            max_message_events: nil,
            max_links: nil,
            max_string_length: nil,
            child_span_count: nil

  raise "Span must have start_time" unless @start_time
  raise "Span must have end_time" unless @end_time

  builder = PieceBuilder.new 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

  built_name = builder.truncatable_string name
  built_attributes = builder.convert_attributes @attributes
  dropped_attributes_count = @attributes.size - built_attributes.size
  built_stack_trace = builder.truncate_stack_trace @stack_trace
  dropped_frames_count = @stack_trace.size - built_stack_trace.size
  built_annotations = builder.convert_annotations @annotations
  dropped_annotations_count = @annotations.size - built_annotations.size
  built_message_events = builder.convert_message_events @message_events
  dropped_message_events_count =
    @message_events.size - built_message_events.size
  built_links = builder.convert_links @links
  dropped_links_count = @links.size - built_links.size
  built_status = builder.convert_status @status_code, @status_message
  same_process_as_parent_span = context.parent.same_process_as_parent

  Span.new trace_id, span_id, built_name, @start_time, @end_time,
           parent_span_id: parent_span_id,
           attributes: built_attributes,
           dropped_attributes_count: dropped_attributes_count,
           stack_trace: built_stack_trace,
           dropped_frames_count: dropped_frames_count,
           time_events: built_annotations + built_message_events,
           dropped_annotations_count: dropped_annotations_count,
           dropped_message_events_count: dropped_message_events_count,
           links: built_links,
           dropped_links_count: dropped_links_count,
           status: built_status,
           same_process_as_parent_span: same_process_as_parent_span,
           child_span_count: child_span_count
end

#trace_id ⇒ String

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

Returns:

  • (String) 


48
49
50
 
# File 'lib/opencensus/trace/span_builder.rb', line 48

def trace_id
  context.trace_id
end

#update_stack_trace(stack_trace = 0) ⇒ Object

Set the stack trace for this span. You may call this in one of three ways:

  • Pass in no argument to use the caller’s stack trace.

  • Pass in an integer to use the caller’s stack trace, but skip additional stack frames.

  • Pass in an explicit array of Thread::Backtrace::Location as returned from Kernel#caller_locations

Parameters:

  • stack_trace (Array<Thread::Backtrace::Location>, Integer) (defaults to: 0) 


263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/opencensus/trace/span_builder.rb', line 263

def update_stack_trace stack_trace = 0
  @stack_trace =
    case stack_trace
    when Integer
      caller_locations(stack_trace + 2)
    when Array
      stack_trace
    else
      raise ArgumentError, "Unknown stack trace type: #{stack_trace}"
    end
  self
end