module OpenCensus::Trace
# OpenCensus
Trace
API
This is a Ruby implementation of OpenCensus
Trace
, providing a common API for latency trace tools.
Constants
- SPAN_CONTEXT_KEY
Internal key for storing the current
SpanContext
in the thread localContext
@private
- TraceContextData
Struct that holds parsed trace context data.
Attributes
Get the current configuration @private
Public Class Methods
Configure OpenCensus
Trace
. These configuration fields include parameters governing sampling, span creation, and exporting.
This configuration is also available as the `trace` subconfig under the main configuration `OpenCensus.configure`. If the OpenCensus
Railtie is installed in a Rails application, the configuration object is also exposed as `config.opencensus.trace`.
Generally, you should configure this once at process initialization, but it can be modified at any time.
Example:
OpenCensus::Trace.configure do |config| config.default_sampler = OpenCensus::Trace::Samplers::RateLimiting.new config.default_max_attributes = 16 end
Supported fields are:
-
`default_sampler` The default sampler to use. Must be a sampler, an object with a `call` method that takes a single options hash. See {OpenCensus::Trace::Samplers}. The initial value is an instance of {OpenCensus::Trace::Samplers::AlwaysSample}.
-
`exporter` The exporter to use. Must be an exporter, an object with an export method that takes an array of
Span
objects. See {OpenCensus::Trace::Exporters}. The initial value is a {OpenCensus::Trace::Exporters::Logger} that logs to STDOUT. -
`http_formatter` The trace context propagation formatter to use. Must be a formatter, an object with `serialize`, `deserialize`, `header_name`, and `rack_header_name` methods. See {OpenCensus::Trace::Formatters}. The initial value is a {OpenCensus::Trace::Formatters::TraceContext}.
-
`default_max_attributes` The maximum number of attributes to add to a span. Initial value is 32. Use 0 for no maximum.
-
`default_max_stack_frames` The maximum number of stack frames to represent in a span's stack trace. Initial value is 32. Use 0 for no maximum.
-
`default_max_annotations` The maximum number of annotations to add to a span. Initial value is 32. Use 0 for no maximum.
-
`default_max_message_events` The maximum number of message events to add to a span. Initial value is 128. Use 0 for no maximum.
-
`default_max_links` The maximum number of links to add to a span. Initial value is 128. Use 0 for no maximum.
-
`default_max_string_length` The maximum length of string fields. Initial value is 1024. Use 0 for no maximum.
# File lib/opencensus/trace/config.rb, line 105 def configure if block_given? yield @config else @config end end
Finish the given span, which must be the span that created the current thread-local SpanContext
. Also updates the thread-local SpanContext
so subsequent calls no longer create subspans of the finished span.
@param [SpanBuilder] span The expected currently active span to finish.
# File lib/opencensus/trace.rb, line 198 def end_span span context = span_context raise "No currently active span context" unless context unless span.equal? context.this_span raise "The given span doesn't match the currently active span" end span.finish! self.span_context = context.parent span end
Create a new span in this context. You must pass a name for the span. All other span attributes should be set using {OpenCensus::Trace::SpanBuilder} methods.
The span will be started automatically with the current timestamp. The SpanBuilder
will then be passed to the block you provide. The span will be finished automatically at the end of the block. Within the block, the thread-local SpanContext
will be updated so calls to `start_span` will create subspans.
@param [String] name Name of the span. Required. @param [Symbol] kind Kind of span. Optional. Defaults to unspecified.
Other allowed values are {OpenCensus::Trace::SpanBuilder::SERVER} and {OpenCensus::Trace::SpanBuilder::CLIENT}.
@param [Sampler,Boolean,nil] sampler Span-scoped sampler. Optional.
If provided, the sampler may be a sampler object as defined in the {OpenCensus::Trace::Samplers} module docs, or the values `true` or `false` as shortcuts for {OpenCensus::Trace::Samplers::AlwaysSample} or {OpenCensus::Trace::Samplers::NeverSample}, respectively. If no span-scoped sampler is provided, the local parent span's sampling decision is used. If there is no local parent span, the configured default sampler is used to make a sampling decision.
# File lib/opencensus/trace.rb, line 180 def in_span name, kind: nil, skip_frames: 0, sampler: nil span = start_span name, kind: kind, skip_frames: skip_frames + 1, sampler: sampler begin yield span ensure end_span span end end
Returns the current thread-local SpanContext
, which governs the behavior of the span creation class methods of OpenCensus::Trace
. Returns `nil` if there is no current SpanContext
.
@return [SpanContext, nil]
# File lib/opencensus/trace.rb, line 74 def span_context OpenCensus::Context.get SPAN_CONTEXT_KEY end
Sets the current thread-local SpanContext
, which governs the behavior of the span creation class methods of OpenCensus::Trace
.
@param [SpanContext] span_context
# File lib/opencensus/trace.rb, line 55 def span_context= span_context OpenCensus::Context.set SPAN_CONTEXT_KEY, span_context end
Starts tracing a request in the current thread, by creating a new SpanContext
and setting it as the current thread-local context. Generally you should call this when beginning the handling of a request. If there is a rack environment or a provided traceparent header, pass it in so the SpanContext
is constructed accordingly.
If you pass a block, this method will yield the SpanContext
to the block. When the block finishes, the span context will automatically be unset. If you do not pass a block, this method will return the SpanContext
. You must then call `unset_span_context` yourself at the end of the request
@param [TraceContextData] trace_context The request's incoming trace
context (optional)
@param [boolean, nil] same_process_as_parent Set to `true` if the parent
span is local, `false` if it is remote, or `nil` if there is no parent span or this information is not available.
# File lib/opencensus/trace.rb, line 97 def start_request_trace trace_context: nil, same_process_as_parent: nil span_context = SpanContext.create_root \ trace_context: trace_context, same_process_as_parent: same_process_as_parent self.span_context = span_context if block_given? begin yield span_context ensure unset_span_context end else span_context end end
Create a new span in the current thread-local context. You must pass a name for the span. All other span attributes should be set using {OpenCensus::Trace::SpanBuilder} methods.
The span will be started automatically with the current timestamp. However, you are responsible for finishing the span yourself. Furthermore, the current thread-local SpanContext
will be updated so subsequent calls to `start_span` will create spans within the new span.
You should always match `start_span` calls with a corresponding call to `end_span`, which finishes the span and updates the SpanContext
accordingly. If you want this done automatically, consider using the `in_span` method.
Will throw an exception if there is no current SpanContext
.
@param [String] name Name of the span. Required. @param [Symbol] kind Kind of span. Optional. Defaults to unspecified.
Other allowed values are {OpenCensus::Trace::SpanBuilder::SERVER} and {OpenCensus::Trace::SpanBuilder::CLIENT}.
@param [Sampler,Boolean,nil] sampler Span-scoped sampler. Optional.
If provided, the sampler may be a sampler object as defined in the {OpenCensus::Trace::Samplers} module docs, or the values `true` or `false` as shortcuts for {OpenCensus::Trace::Samplers::AlwaysSample} or {OpenCensus::Trace::Samplers::NeverSample}, respectively. If no span-scoped sampler is provided, the local parent span's sampling decision is used. If there is no local parent span, the configured default sampler is used to make a sampling decision.
@return [SpanBuilder] A SpanBuilder
object that you can use to
set span attributes and create children.
# File lib/opencensus/trace.rb, line 146 def start_span name, kind: nil, skip_frames: 0, sampler: nil context = span_context raise "No currently active span context" unless context span = context.start_span name, kind: kind, skip_frames: skip_frames + 1, sampler: sampler self.span_context = span.context span end
Unsets the current thread-local SpanContext
, disabling span creation class methods of OpenCensus::Trace
# File lib/opencensus/trace.rb, line 63 def unset_span_context OpenCensus::Context.unset SPAN_CONTEXT_KEY end