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
SPAN_KIND_UNSPECIFIED =

The span kind is unspecified

:SPAN_KIND_UNSPECIFIED
SERVER =

Indicates that the span covers server-side handling of an RPC or other remote network request.

:SERVER
CLIENT =

Indicates that the span covers the client-side wrapper around an RPC or other remote request.

:CLIENT

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

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

Initializer.



384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/opencensus/trace/span_builder.rb', line 384

def initialize span_context, sampled, skip_frames: 0
  @context = span_context
  @sampled = sampled
  @name = ""
  @kind = SPAN_KIND_UNSPECIFIED
  @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:



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

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) 


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

def end_time
  @end_time
end

#kind ⇒ Symbol

The kind of span. Can be used to specify additional relationships between spans in addition to a parent/child relationship. Valid values are ‘SpanBuilder::CLIENT`, `SpanBuilder::SERVER`, and `SpanBuilder::SPAN_KIND_UNSPECIFIED`.

This field is required.

Returns:

  • (Symbol) 


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

def kind
  @kind
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:



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

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) 


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

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) 


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

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.



169
170
171
172
173
174
 
# File 'lib/opencensus/trace/span_builder.rb', line 169

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) 


150
151
152
 
# File 'lib/opencensus/trace/span_builder.rb', line 150

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) 


82
83
84
 
# File 'lib/opencensus/trace/span_builder.rb', line 82

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.



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

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:



191
192
193
194
 
# File 'lib/opencensus/trace/span_builder.rb', line 191

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



260
261
262
263
264
 
# File 'lib/opencensus/trace/span_builder.rb', line 260

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.



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

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.



272
273
274
275
276
 
# File 'lib/opencensus/trace/span_builder.rb', line 272

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) 


72
73
74
 
# File 'lib/opencensus/trace/span_builder.rb', line 72

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.



158
159
160
161
162
 
# File 'lib/opencensus/trace/span_builder.rb', line 158

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:



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/opencensus/trace/span_builder.rb', line 326

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,
           kind: @kind,
           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) 


63
64
65
 
# File 'lib/opencensus/trace/span_builder.rb', line 63

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) 


290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/opencensus/trace/span_builder.rb', line 290

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