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
The context that can build children of this span.
@return [SpanContext]
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]
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]
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]
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
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 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
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
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
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
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
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.
@param [String] trace_id
The unique identifier for a trace. A 16-byte
array expressed as 32 hex digits.
@param [String] span_id
The unique identifier for a span within a trace.
An 8-byte array expressed as 16 hex digits.
@param [Symbol] type The relationship of the current span relative to
the linked span. Valid values are {OpenCensus::Trace::SpanBuilder::CHILD_LINKED_SPAN}, {OpenCensus::Trace::SpanBuilder::PARENT_LINKED_SPAN}, and {OpenCensus::Trace::SpanBuilder::TYPE_UNSPECIFIED}.
@param [Hash<String, (TruncatableString
, Integer, Float, Boolean)>]
attributes 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).
# 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
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
Sampling decision for this span.
@return [boolean]
# File lib/opencensus/trace/span_builder.rb, line 114 def sampled? context.sampled? end
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 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
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 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
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
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
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
# 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