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 =

Fallback span name

Returns:

  • (String) 
"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 the request path as recommended in the OpenCensus spec.

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



116
117
118
119
120
121
122
123
 
# File 'lib/opencensus/trace/integrations/faraday_middleware.rb', line 116

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