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.

Constant Summary collapse

TYPE_UNSPECIFIED =

This value may be used as an event type or a link type, and indicates that the type is unknown.

Returns:

  • (Symbol) 
:TYPE_UNSPECIFIED
SENT =

An event type, indicating a sent message.

Returns:

  • (Symbol) 
:SENT
RECEIVED =

An event type, indicating a received message.

Returns:

  • (Symbol) 
:RECEIVED
CHILD_LINKED_SPAN =

A link type, indicating the linked span is a child of the current span.

Returns:

  • (Symbol) 
:CHILD_LINKED_SPAN
PARENT_LINKED_SPAN =

A link type, indicating the linked span is a parent of the current span.

Returns:

  • (Symbol) 
:PARENT_LINKED_SPAN
SPAN_KIND_UNSPECIFIED =

A span kind, indicating that the span is either neither a server nor a client, or is unknown.

Returns:

  • (Symbol) 
:SPAN_KIND_UNSPECIFIED
SERVER =

A span kind, indicating that the span covers server-side handling of an RPC or other remote network request.

Returns:

  • (Symbol) 
:SERVER
CLIENT =

A span kind, indicating that the span covers the client-side wrapper around an RPC or other remote request.

Returns:

  • (Symbol) 
:CLIENT

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#context ⇒ SpanContext (readonly)

The context that can build children of this span.

Returns:



79
80
81
 
# File 'lib/opencensus/trace/span_builder.rb', line 79

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) 


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

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 CLIENT, SERVER, and SPAN_KIND_UNSPECIFIED.

This field is required.

Returns:

  • (Symbol) 


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

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:



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

def name
  @name
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) 


157
158
159
 
# File 'lib/opencensus/trace/span_builder.rb', line 157

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.



195
196
197
198
199
200
 
# File 'lib/opencensus/trace/span_builder.rb', line 195

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) 


176
177
178
 
# File 'lib/opencensus/trace/span_builder.rb', line 176

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) 


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

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.



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

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, Float or Boolean. The valid integer range is 64-bit signed (-2^63..2^63-1).

Parameters:



217
218
219
220
 
# File 'lib/opencensus/trace/span_builder.rb', line 217

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 CHILD_LINKED_SPAN, PARENT_LINKED_SPAN, and TYPE_UNSPECIFIED.

  • attributes (Hash<String, (TruncatableString, Integer, Float, Boolean)>) (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).



290
291
292
293
294
 
# File 'lib/opencensus/trace/span_builder.rb', line 290

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 SENT, RECEIVED, and 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.



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

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

#sampled? ⇒ boolean Also known as: sampled

Sampling decision for this span.

Returns:

  • (boolean) 


114
115
116
 
# File 'lib/opencensus/trace/span_builder.rb', line 114

def sampled?
  context.sampled?
end

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

Set the optional final status for the span using an http status code.

Parameters:

  • code (Integer) —

    HTTP status code as a 32-bit signed integer

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

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



316
317
318
 
# File 'lib/opencensus/trace/span_builder.rb', line 316

def set_http_status code, message = ""
  set_status map_http_status(code), message
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.



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

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) 


95
96
97
 
# File 'lib/opencensus/trace/span_builder.rb', line 95

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.



184
185
186
187
188
 
# File 'lib/opencensus/trace/span_builder.rb', line 184

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:



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/opencensus/trace/span_builder.rb', line 368

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) 


86
87
88
 
# File 'lib/opencensus/trace/span_builder.rb', line 86

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) 


332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/opencensus/trace/span_builder.rb', line 332

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