class OpenCensus::Trace::Exporters::Stackdriver

The Stackdriver exporter for OpenCensus Trace exports captured spans to a Google Stackdriver project. It calls the Stackdriver Trace API in a background thread pool.

Attributes

project_id[R]

The project ID @return [String]

Public Class Methods

new(\ project_id: nil, credentials: nil, scope: nil, timeout: nil, client_config: nil, max_queue: 1000, max_threads: 1, auto_terminate_time: 10, mock_client: nil) click to toggle source

Create a Stackdriver exporter.

@param [String] project_id The project identifier for the Stackdriver

Trace service you are connecting to. If you are running on Google
Cloud hosting (e.g. Compute Engine, Kubernetes Engine, or App
Engine), this parameter is optional and will default to the
hosting project. Otherwise, it is required.

@param [String, Hash, Google::Auth::Credentials] credentials The

Stackdriver API credentials, which can be a path to a keyfile as
a String, the contents of a keyfile as a Hash, or a
Google::Auth::Credentials object. If you are running on Google
Cloud hosting (e.g. Compute Engine, Kubernetes Engine, or App
Engine), this parameter is optional and will default to the
credentials provided by the hosting project. Otherwise, it is
required.

@param [String, Array<String>] scope The OAuth 2.0 scopes controlling

the set of resources and operations the API client can access.
Optional. Most applications can leave this set to the default.

@param [Integer] timeout The default timeout for API requests, in

seconds. Optional.

@param [Hash] client_config Unused. @param [Integer] max_queue The maximum number of API requests that

can be queued for background operation. If the queue exceeds this
value, additional requests will be run in the calling thread
rather than in the background. Set to 0 to allow the queue to
grow indefinitely. Default is 1000.

@param [Integer] max_threads The maximum number of threads that can

be spun up to handle API requests. Default is 1. If set to 0,
backgrounding will be disabled and all requests will run in the
calling thread.

@param [Integer] auto_terminate_time The time in seconds allotted to

complete any pending background requests when Ruby is exiting.
# File lib/opencensus/trace/exporters/stackdriver.rb, line 72
def initialize \
    project_id: nil,
    credentials: nil,
    scope: nil,
    timeout: nil,
    client_config: nil, # rubocop:disable Lint/UnusedMethodArgument
    max_queue: 1000,
    max_threads: 1,
    auto_terminate_time: 10,
    mock_client: nil
  @project_id = project_id ||
                ENV["GOOGLE_CLOUD_PROJECT"] ||
                Google::Cloud.env.project_id
  @executor = create_executor max_threads, max_queue
  if auto_terminate_time
    terminate_at_exit! @executor, auto_terminate_time
  end

  if mock_client
    @client_promise =
      Concurrent::Promise.fulfill mock_client, executor: @executor
  else
    @client_promise = create_client_promise \
      @executor, credentials, scope, timeout
  end
end

Public Instance Methods

export(spans) click to toggle source

Export spans to Stackdriver asynchronously.

@param [Array<OpenCensus::Trace::Span>] spans The captured spans to

export to Stackdriver
# File lib/opencensus/trace/exporters/stackdriver.rb, line 111
def export spans
  raise "Exporter is no longer running" unless @executor.running?

  return nil if spans.nil? || spans.empty?

  @client_promise.execute
  export_promise = @client_promise.then do |client|
    export_as_batch(client, spans)
  end
  export_promise.on_error do |reason|
    warn "Unable to export to Stackdriver because: #{reason}"
  end

  nil
end
kill() click to toggle source

Begin shutting down the exporter forcefully. After this operation is performed, the exporter will no longer accept export requests, and will finish any currently running export requests, but will cancel all requests that are still pending in the queue.

# File lib/opencensus/trace/exporters/stackdriver.rb, line 174
def kill
  @executor.kill
  self
end
running?() click to toggle source

Returns true if this exporter is running and will accept further export requests. Returns false once the exporter begins shutting down.

@return [boolean]

# File lib/opencensus/trace/exporters/stackdriver.rb, line 133
def running?
  @executor.running?
end
shutdown() click to toggle source

Begin shutting down the exporter gracefully. After this operation is performed, the exporter will no longer accept export requests, but will finish any pending requests in the background.

# File lib/opencensus/trace/exporters/stackdriver.rb, line 163
def shutdown
  @executor.shutdown
  self
end
shutdown?() click to toggle source

Returns true if this exporter has finished shutting down and all pending spans have been sent.

@return [boolean]

# File lib/opencensus/trace/exporters/stackdriver.rb, line 143
def shutdown?
  @executor.shutdown?
end
shuttingdown?() click to toggle source

Returns true if this exporter has begun shutting down and is no longer accepting export requests, but is still running queued requests in the background.

@return [boolean]

# File lib/opencensus/trace/exporters/stackdriver.rb, line 154
def shuttingdown?
  @executor.shuttingdown?
end
wait_for_termination(timeout = nil) click to toggle source

Wait for the exporter to finish shutting down.

@param [Integer, nil] timeout A timeout in seconds, or nil for no

timeout.

@return [boolean] true if the exporter is shut down, or false if the

wait timed out.
# File lib/opencensus/trace/exporters/stackdriver.rb, line 187
def wait_for_termination timeout = nil
  @executor.wait_for_termination timeout
end

Private Instance Methods

create_client_promise(executor, credentials, scopes, timeout) click to toggle source

Create the client promise. We create the client lazily so grpc doesn't get initialized until we actually need it. This is important because if it is intialized too early, before a fork, it can go into a bad state.

# File lib/opencensus/trace/exporters/stackdriver.rb, line 209
def create_client_promise executor, credentials, scopes, timeout
  Concurrent::Promise.new executor: executor do
    Google::Cloud::Trace::V2::TraceService::Client.new do |config|
      config.credentials = credentials if credentials
      config.scope = scopes if scopes
      config.timeout = timeout if timeout
      config.lib_name = "opencensus"
      config.lib_version = OpenCensus::Stackdriver::VERSION
    end
  end
end
create_executor(max_threads, max_queue) click to toggle source

Create the executor

# File lib/opencensus/trace/exporters/stackdriver.rb, line 194
def create_executor max_threads, max_queue
  if max_threads >= 1
    Concurrent::ThreadPoolExecutor.new \
      min_threads: 1, max_threads: max_threads,
      max_queue: max_queue, fallback_policy: :caller_runs,
      auto_terminate: false
  else
    Concurrent::ImmediateExecutor.new
  end
end
export_as_batch(client, spans) click to toggle source

Export a list of spans in a single batch write, in the current thread

# File lib/opencensus/trace/exporters/stackdriver.rb, line 233
def export_as_batch client, spans
  converter = Converter.new project_id
  span_protos = Array(spans).map { |span| converter.convert_span span }
  client.batch_write_spans name: "projects/#{project_id}",
                           spans: span_protos
end
terminate_at_exit!(executor, timeout) click to toggle source

Set up an at_exit hook that shuts the exporter down.

# File lib/opencensus/trace/exporters/stackdriver.rb, line 222
def terminate_at_exit! executor, timeout
  at_exit do
    executor.shutdown
    unless executor.wait_for_termination timeout
      executor.kill
      executor.wait_for_termination timeout
    end
  end
end