Class: OpenCensus::Trace::Integrations::FaradayMiddleware

Inherits:
Faraday::Middleware
  • Object
show all
Defined in:
lib/opencensus/trace/integrations/faraday_middleware.rb

Overview

# Faraday integration

This is a middleware for the Faraday HTTP client:

  • It wraps all outgoing requests in spans

  • It adds the trace context to outgoing requests.

Example:

conn = Faraday.new(url: "http://www.example.com") do |c|
  c.use OpenCensus::Trace::Integrations::FaradayMiddleware,
        span_name: "http request"
  c.adapter Faraday.default_adapter
end
conn.get "/"

## Configuring spans

By default, spans are added to the thread-local span context, as if by calling ‘OpenCensus::Trace.start_span`. If there is no span context, then no span is added and this middleware effectively disables itself.

You may also provide a span context, by passing it in the middleware options hash. For example:

conn = Faraday.new(url: "http://www.example.com") do |c|
  c.use OpenCensus::Trace::Integrations::FaradayMiddleware,
        span_context: my_span_context
  c.adapter Faraday.default_adapter
end

You may also override the span context for a particular request by including it in the options:

conn.get do |req|
  req.url "/"
  req.options.context = { span_context: my_span_context }
end

By default, all spans are given a default name. You may also override this by passing a ‘:span_name` in the middleware options hash and/or the request options.

## Trace context

This currently adds a header to each outgoing request, propagating the trace context for distributed tracing. By default, this uses the formatter in the current config.

You may provide your own implementation of the formatter by configuring it in the middleware options hash. For example:

conn = Faraday.new(url: "http://www.example.com") do |c|
  c.use OpenCensus::Trace::Integrations::FaradayMiddleware,
        formatter: OpenCensus::Trace::Formatters::CloudTrace.new
  c.adapter Faraday.default_adapter
end

You many also override the formatter for a particular request by including it in the options:

conn.get do |req|
  req.url "/"
  req.options.context = {
    formatter: OpenCensus::Trace::Formatters::CloudTrace.new
  }
end

Constant Summary collapse

DEFAULT_SPAN_NAME =

The default name for Faraday spans

"faraday_request".freeze

Instance Method Summary collapse

Constructor Details

#initialize(app, span_context: nil, span_name: nil, sampler: nil, formatter: nil) ⇒ FaradayMiddleware

Create a FaradayMiddleware.

Parameters:

  • app (#call) —

    Next item on the middleware stack.

  • span_context (SpanContext) (defaults to: nil) —

    The span context within which to create spans. Optional: If omitted, spans are created in the current thread-local span context.

  • span_name (String, #call) (defaults to: nil) —

    The name of the span to create. Can be a string or a callable that takes a faraday request env and returns a string. Optional: If omitted, uses ‘DEFAULT_SPAN_NAME`

  • sampler (#call) (defaults to: nil) —

    The sampler to use when creating spans. Optional: If omitted, uses the sampler in the current config.

  • formatter (#serialize, #header_name) (defaults to: nil) —

    The formatter to use when propagating span context. Optional: If omitted, use the formatter in the current config.



112
113
114
115
116
117
118
119
 
# File 'lib/opencensus/trace/integrations/faraday_middleware.rb', line 112

def initialize app, span_context: nil, span_name: nil, sampler: nil,
               formatter: nil
  @app = app
  @span_context = span_context || OpenCensus::Trace
  @span_name = span_name || DEFAULT_SPAN_NAME
  @sampler = sampler
  @formatter = formatter || OpenCensus::Trace.config.http_formatter
end

Instance Method Details

#call(request_env) ⇒ Object

Wraps an HTTP call with a span with the request/response info.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/opencensus/trace/integrations/faraday_middleware.rb', line 125

def call request_env
  span_context = request_env[:span_context] || @span_context
  if span_context == OpenCensus::Trace && !span_context.span_context
    return @app.call request_env
  end

  span_name = request_env[:span_name] || @span_name
  span_name = span_name.call request_env if span_name.respond_to? :call

  span = span_context.start_span span_name, sampler: @sampler
  start_request span, request_env
  @app.call(request_env).on_complete do |response_env|
    finish_request span, response_env
    span_context.end_span span
  end
end