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/samplers/max_qps.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/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

Constant Summary collapse

SPAN_CONTEXT_KEY =

Internal key for storing the current SpanContext in the thread local Context

:__span_context__

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.config ⇒ Object (readonly)

Get the current configuration



115
116
117
 
# File 'lib/opencensus/trace/config.rb', line 115

def config
  @config
end

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::AlwaysSample.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 a Probability sampler with a default rate.

  • ‘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 Logger exporter 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::Formatter. The initial value is a TraceContext formatter.

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



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

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.



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/opencensus/trace.rb', line 178

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 the 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:

  • name (String) —

    Name of the span

  • kind (Symbol) (defaults to: nil) —

    Kind of span. Defaults to unspecified.

  • sampler (Sampler) (defaults to: nil) —

    Span-scoped sampler. If not provided, defaults to the trace configuration’s default sampler.



160
161
162
163
164
165
166
167
168
 
# File 'lib/opencensus/trace.rb', line 160

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:



72
73
74
 
# File 'lib/opencensus/trace.rb', line 72

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:



53
54
55
 
# File 'lib/opencensus/trace.rb', line 53

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



95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/opencensus/trace.rb', line 95

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
  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 the 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:

  • name (String) —

    Name of the span

  • kind (Symbol) (defaults to: nil) —

    Kind of span. Defaults to unspecified.

  • sampler (Sampler) (defaults to: nil) —

    Span-scoped sampler. If not provided, defaults to the trace configuration’s default sampler.

Returns:

  • (SpanBuilder) —

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



134
135
136
137
138
139
140
141
142
 
# File 'lib/opencensus/trace.rb', line 134

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



61
62
63
 
# File 'lib/opencensus/trace.rb', line 61

def unset_span_context
  OpenCensus::Context.unset SPAN_CONTEXT_KEY
end