Class: OpenCensus::Stats::Exporters::Stackdriver

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

Overview

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

Constant Summary collapse

CUSTOM_OPENCENSUS_DOMAIN =

Default custom opencensus domain name

Returns:

  • (String) 
"custom.googleapis.com/opencensus".freeze
GLOBAL_RESOURCE_TYPE =

Default metric resouce type.

Returns:

  • (String) 
"global".freeze

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, metric_prefix: nil, resource_type: nil, resource_labels: nil, gcm_service_address: nil) ⇒ Stackdriver

Create a Stackdriver exporter.

Parameters:

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

    The project identifier for the Stackdriver Monitoring 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.

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

    Prefix for stackdriver metric. Default value set to CUSTOM_OPENCENSUS_DOMAIN

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

    Metric resource type. Default value set to GLOBAL_RESOURCE_TYPE

  • resource_labels (Hash<String,String>) (defaults to: nil) —

    Metric resource labels. Default value set to { "project_id" => project_id }

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

    Override for the Google Cloud Monitoring service hostname, or nil to leave as the default.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 110

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,
    metric_prefix: nil,
    resource_type: nil,
    resource_labels: nil,
    gcm_service_address: nil
  @project_id = project_id ||
                ENV["GOOGLE_CLOUD_PROJECT"] ||
                Google::Cloud.env.project_id
  @metric_prefix = metric_prefix || CUSTOM_OPENCENSUS_DOMAIN
  @resource_type = resource_type || GLOBAL_RESOURCE_TYPE
  @resource_labels = resource_labels || {
    "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
    @client_promise = create_client_promise \
      @executor, credentials, scope, timeout, gcm_service_address
  end

  @converter = Converter.new @project_id
  paths = Google::Cloud::Monitoring::V3::MetricService::Paths
  @project_path = paths.project_path project: @project_id
end

Instance Attribute Details

#metric_prefix ⇒ String (readonly)

Metric prefix

Returns:

  • (String) 


56
57
58
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 56

def metric_prefix
  @metric_prefix
end

#project_id ⇒ String (readonly)

The project ID

Returns:

  • (String) 


52
53
54
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 52

def project_id
  @project_id
end

#resource_labels ⇒ Hash<String,String> (readonly)

Metric resource labels

Returns:

  • (Hash<String,String>) 


64
65
66
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 64

def resource_labels
  @resource_labels
end

#resource_type ⇒ String (readonly)

Metric resource type

Returns:

  • (String) 


60
61
62
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 60

def resource_type
  @resource_type
end

Instance Method Details

#create_metric_descriptor(view) ⇒ Google::Api::MetricDescriptor

Create a metric descriptor

An error will be raised if there is already a metric descriptor created with the same name but it has a different aggregation or keys.

Parameters:

  • view (OpenCensus::Stats::View)

Returns:

  • (Google::Api::MetricDescriptor) 


245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 245

def create_metric_descriptor view
  metric_descriptor = @converter.convert_metric_descriptor(
    view,
    metric_prefix
  )
  paths = Google::Cloud::Monitoring::V3::MetricService::Paths
  metric_name = paths.metric_descriptor_path(
    project: project_id,
    metric_descriptor: metric_descriptor.type
  )

  @client_promise.execute
  descriptor_create_promise = @client_promise.then do |client|
    client.create_metric_descriptor name: metric_name,
                                    metric_descriptor: metric_descriptor
  end
  descriptor_create_promise.value!
end

#export(views_data) ⇒ Object

Export stats to Monitoring service asynchronously.

Parameters:

  • views_data (Array<OpenCensus::Stats::ViewData>) —

    The captured stats data



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 156

def export views_data
  raise "Exporter is no longer running" unless @executor.running?

  return if views_data.nil? || views_data.empty?

  @client_promise.execute
  export_promise = @client_promise.then do |client|
    export_as_batch(client, views_data)
  end
  export_promise.on_error do |reason|
    warn "Unable to export to Monitoring service 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.



219
220
221
222
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 219

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) 


178
179
180
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 178

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.



208
209
210
211
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 208

def shutdown
  @executor.shutdown
  self
end

#shutdown? ⇒ boolean

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

Returns:

  • (boolean) 


188
189
190
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 188

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) 


199
200
201
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 199

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.



232
233
234
 
# File 'lib/opencensus/stats/exporters/stackdriver.rb', line 232

def wait_for_termination timeout = nil
  @executor.wait_for_termination timeout
end