Module: OpenCensus::Trace

Defined in:
lib/opencensus/trace.rb,
lib/opencensus/trace/link.rb,
lib/opencensus/trace/span.rb,
lib/opencensus/trace/config.rb,
lib/opencensus/trace/status.rb,
lib/opencensus/trace/samplers.rb,
lib/opencensus/trace/exporters.rb,
lib/opencensus/trace/annotation.rb,
lib/opencensus/trace/formatters.rb,
lib/opencensus/trace/time_event.rb,
lib/opencensus/trace/integrations.rb,
lib/opencensus/trace/span_builder.rb,
lib/opencensus/trace/span_context.rb,
lib/opencensus/trace/message_event.rb,
lib/opencensus/trace/exporters/multi.rb,
lib/opencensus/trace/exporters/logger.rb,
lib/opencensus/trace/formatters/binary.rb,
lib/opencensus/trace/integrations/rails.rb,
lib/opencensus/trace/trace_context_data.rb,
lib/opencensus/trace/truncatable_string.rb,
lib/opencensus/trace/samplers/probability.rb,
lib/opencensus/trace/samplers/never_sample.rb,
lib/opencensus/trace/formatters/cloud_trace.rb,
lib/opencensus/trace/samplers/always_sample.rb,
lib/opencensus/trace/samplers/rate_limiting.rb,
lib/opencensus/trace/formatters/trace_context.rb,
lib/opencensus/trace/integrations/rack_middleware.rb,
lib/opencensus/trace/integrations/faraday_middleware.rb

Overview

OpenCensus Trace API

This is a Ruby implementation of OpenCensus Trace, providing a common API for latency trace tools.

Defined Under Namespace

Modules: Exporters, Formatters, Integrations, Samplers Classes: Annotation, Link, MessageEvent, Span, SpanBuilder, SpanContext, Status, TimeEvent, TraceContextData, TruncatableString

Class Method Summary collapse

Class Method Details

.configure ⇒ Object

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


105
106
107
108
109
110
111
 
# File 'lib/opencensus/trace/config.rb', line 105

def configure
  if block_given?
    yield @config
  else
    @config
  end
end

.end_span(span) ⇒ Object

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.

Parameters:

  • span (SpanBuilder) —

    The expected currently active span to finish.



198
199
200
201
202
203
204
205
206
207
 
# 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

.in_span(name, kind: nil, skip_frames: 0, sampler: nil) ⇒ Object

Create a new span in this context. You must pass a name for the span. All other span attributes should be set using 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.

Parameters:



180
181
182
183
184
185
186
187
188
 
# 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

.span_context ⇒ SpanContext?

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.

Returns:



74
75
76
 
# File 'lib/opencensus/trace.rb', line 74

def span_context
  OpenCensus::Context.get SPAN_CONTEXT_KEY
end

.span_context=(span_context) ⇒ Object

Sets the current thread-local SpanContext, which governs the behavior of the span creation class methods of OpenCensus::Trace.

Parameters:



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

def span_context= span_context
  OpenCensus::Context.set SPAN_CONTEXT_KEY, span_context
end

.start_request_trace(trace_context: nil, same_process_as_parent: nil) ⇒ Object

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

Parameters:

  • trace_context (TraceContextData) (defaults to: nil) —

    The request's incoming trace context (optional)

  • same_process_as_parent (boolean, nil) (defaults to: nil) —

    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.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# 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

.start_span(name, kind: nil, skip_frames: 0, sampler: nil) ⇒ SpanBuilder

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

Parameters:

Returns:

  • (SpanBuilder) —

    A SpanBuilder object that you can use to set span attributes and create children.



146
147
148
149
150
151
152
153
154
 
# 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

.unset_span_context ⇒ Object

Unsets the current thread-local SpanContext, disabling span creation class methods of OpenCensus::Trace



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

def unset_span_context
  OpenCensus::Context.unset SPAN_CONTEXT_KEY
end