class OpenCensus::Trace::SpanBuilder

Span represents a single span within a request trace.

Constants

AnnotationBuilder

Internal structure for holding annotations.

@private

CHILD_LINKED_SPAN

A link type, indicating the linked span is a child of the current span. @return [Symbol]

CLIENT

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

LinkBuilder

Internal structure for holding links.

@private

MessageEventBuilder

Internal structure for holding message events.

@private

PARENT_LINKED_SPAN

A link type, indicating the linked span is a parent of the current span. @return [Symbol]

RECEIVED

An event type, indicating a received message. @return [Symbol]

SENT

An event type, indicating a sent message. @return [Symbol]

SERVER

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

SPAN_KIND_UNSPECIFIED

A span kind, indicating that the span is either neither a server nor a client, or is unknown. @return [Symbol]

TYPE_UNSPECIFIED

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

Attributes

context[R]

The context that can build children of this span.

@return [SpanContext]

end_time[RW]

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.

@return [Time, nil]

kind[RW]

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

This field is required.

@return [Symbol]

name[RW]

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.

@return [String, TruncatableString]

start_time[RW]

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.

@return [Time, nil]

Public Class Methods

new(span_context, skip_frames: 0) click to toggle source

Initializer.

@private

# File lib/opencensus/trace/span_builder.rb, line 426
def initialize span_context, skip_frames: 0
  @context = span_context
  @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

Public Instance Methods

finish!() click to toggle source

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.

# 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?() click to toggle source

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

@return [boolean]

# File lib/opencensus/trace/span_builder.rb, line 176
def finished?
  !start_time.nil? && !end_time.nil?
end
parent_span_id() click to toggle source

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

@return [String]

# File lib/opencensus/trace/span_builder.rb, line 105
def parent_span_id
  context.parent.span_id
end
put_annotation(description, attributes = {}) click to toggle source

Add an event annotation with a timestamp.

@param [String] description Description of the event @param [Hash] attributes 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).

@param [Time, nil] time Timestamp of the event. Optional, defaults to

the current time.
# 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) click to toggle source

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

@param [String, Symbol] key @param [String, TruncatableString, Integer, Float, Boolean] value

# File lib/opencensus/trace/span_builder.rb, line 217
def put_attribute key, value
  @attributes[key.to_s] = value
  self
end
put_message_event(type, id, uncompressed_size, compressed_size: nil, time: nil) click to toggle source

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

@param [Symbol] type The type of MessageEvent. Indicates whether the

message was sent or received. Valid values are
{OpenCensus::Trace::SpanBuilder::SENT},
{OpenCensus::Trace::SpanBuilder::RECEIVED}, and
{OpenCensus::Trace::SpanBuilder::TYPE_UNSPECIFIED}.

@param [Integer] id 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)`

@param [Integer] uncompressed_size The number of uncompressed bytes

sent or received.

@param [Integer, nil] compressed_size The number of compressed bytes

sent or received. Optional.

@param [Time, nil] time Timestamp of the event. Optional, defaults to

the current time.
# 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()
Alias for: sampled?
sampled?() click to toggle source

Sampling decision for this span.

@return [boolean]

# File lib/opencensus/trace/span_builder.rb, line 114
def sampled?
  context.sampled?
end
Also aliased as: sampled
set_http_status(code, message = "") click to toggle source

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

@param [Integer] code HTTP status code as a 32-bit signed integer @param [String] message A developer-facing error message, which should

be in English.
# 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 = "") click to toggle source

Set the optional final status for the span.

@param [Integer] code Status code as a 32-bit signed integer @param [String] message A developer-facing error message, which should

be in English.
# File lib/opencensus/trace/span_builder.rb, line 303
def set_status code, message = ""
  @status_code = code
  @status_message = message
  self
end
span_id() click to toggle source

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

@return [String]

# File lib/opencensus/trace/span_builder.rb, line 95
def span_id
  context.span_id
end
start!() click to toggle source

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

# 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) click to toggle source

Return a read-only version of this span

@param [Integer, nil] max_attributes The maximum number of attributes

to save, or `nil` to use the config value.

@param [Integer, nil] max_stack_frames The maximum number of stack

frames to save, or `nil` to use the config value.

@param [Integer, nil] max_annotations The maximum number of annotations

to save, or `nil` to use the config value.

@param [Integer, nil] max_message_events The maximum number of message

events to save, or `nil` to use the config value.

@param [Integer, nil] max_links The maximum number of links to save,

or `nil` to use the config value.

@param [Integer, nil] max_string_length The maximum length in bytes for

truncated strings, or `nil` to use the config value.

@param [Integer, nil] child_span_count The number of child spans to

declare, or `nil` to omit the `child_span_count` field.

@return [Span]

# 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() click to toggle source

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

@return [String]

# File lib/opencensus/trace/span_builder.rb, line 86
def trace_id
  context.trace_id
end
update_stack_trace(stack_trace = 0) click to toggle source

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`

@param [Array<Thread::Backtrace::Location>, Integer] stack_trace

# 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

Private Instance Methods

map_http_status(http_status) click to toggle source
# File lib/opencensus/trace/span_builder.rb, line 648
def map_http_status http_status
  case http_status
  when 200..399 then Status::OK
  when 400 then Status::INVALID_ARGUMENT
  when 401 then Status::UNAUTHENTICATED
  when 403 then Status::PERMISSION_DENIED
  when 404 then Status::NOT_FOUND
  when 429 then Status::RESOURCE_EXHAUSTED
  when 501 then Status::UNIMPLEMENTED
  when 503 then Status::UNAVAILABLE
  when 504 then Status::DEADLINE_EXCEEDED
  else Status::UNKNOWN
  end
end