Class: OpenCensus::Trace::Exporters::Stackdriver

Inherits:
Object
  • Object
show all
Defined in:
lib/opencensus/trace/exporters/stackdriver.rb,
lib/opencensus/trace/exporters/stackdriver/converter.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(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) ⇒ Stackdriver

Create a Stackdriver exporter.

Parameters:

  • project_id (String) (defaults to: nil) —

    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.

  • credentials (String, Hash, Google::Auth::Credentials) (defaults to: nil) —

    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.

  • scope (String, Array<String>) (defaults to: nil) —

    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.

  • timeout (Integer) (defaults to: nil) —

    The default timeout for API requests, in seconds. Optional.

  • client_config (Hash) (defaults to: nil) —

    An optional set of additional configuration values for the API connection.

  • max_queue (Integer) (defaults to: 1000) —

    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.

  • max_threads (Integer) (defaults to: 1) —

    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.

  • auto_terminate_time (Integer) (defaults to: 10) —

    The time in seconds allotted to complete any pending background requests when Ruby is exiting.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 66

def initialize \
    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
  @project_id = final_project_id 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
    credentials = final_credentials credentials, scope
    scope ||= Google::Cloud.configure.trace.scope
    timeout ||= Google::Cloud.configure.trace.timeout
    client_config ||= Google::Cloud.configure.trace.client_config
    @client_promise = create_client_promise \
      @executor, credentials, scope, client_config, timeout
  end
end

Instance Attribute Details

#project_id ⇒ String (readonly)

The project ID

Returns:

  • (String) 


100
101
102
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 100

def project_id
  @project_id
end

Instance Method Details

#export(spans) ⇒ Object

Export spans to Stackdriver asynchronously.

Parameters:

  • spans (Array<OpenCensus::Trace::Span>) —

    The captured spans to export to Stackdriver



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 108

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 ⇒ Object

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.



171
172
173
174
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 171

def kill
  @executor.kill
  self
end

#running? ⇒ boolean

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

Returns:

  • (boolean) 


130
131
132
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 130

def running?
  @executor.running?
end

#shutdown ⇒ Object

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.



160
161
162
163
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 160

def shutdown
  @executor.shutdown
  self
end

#shutdown? ⇒ boolean

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

Returns:

  • (boolean) 


140
141
142
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 140

def shutdown?
  @executor.shutdown?
end

#shuttingdown? ⇒ boolean

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.

Returns:

  • (boolean) 


151
152
153
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 151

def shuttingdown?
  @executor.shuttingdown?
end

#wait_for_termination(timeout = nil) ⇒ boolean

Wait for the exporter to finish shutting down.

Parameters:

  • timeout (Integer, nil) (defaults to: nil) —

    A timeout in seconds, or nil for no timeout.

Returns:

  • (boolean) —

    true if the exporter is shut down, or false if the wait timed out.



184
185
186
 
# File 'lib/opencensus/trace/exporters/stackdriver.rb', line 184

def wait_for_termination timeout = nil
  @executor.wait_for_termination timeout
end