opentelemetry-api 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 23c4a8602afe2513fff72ec29784b696ae41eccee8c3b25eb4cf48081856b22b
4
- data.tar.gz: 17507ad2d0dbb697e6f1bb8cbf133d0baa01234d7383d9bb726b0d5fb11c4cb3
3
+ metadata.gz: d9a70b684347cdc76e7cc5654e09ad01eb406cb415006b8f9418ff5c421521cf
4
+ data.tar.gz: 818b8c0cd95656898d0ce0eb4cf44d5fcc15ad7dd86e88b43b8aa1dc920dc05d
5
5
  SHA512:
6
- metadata.gz: 5c37bb2d8a469bda44a121bfca1218380553cbc66d24e8001df4c2e67d93f9b474335962095b77a28e6de3c53f34af98ea18b12a3335cdd45d0b04d50510b2be
7
- data.tar.gz: 3980934cdfdb34e96eb8215a9ebb26eb0b3d096be3e545837ee9d6595ff5e114ea680e692ccc7d0af2d89d8a4550e180671e4d92c5266b6a445c45fc991e0602
6
+ metadata.gz: 3823e1d3a42b7cf8fcab40b5d2eb42f1fa312639175f8b57fef4ea5452451d8b358439424dc8da1825dbbb61e38c9a987c5996144d927bf6cb883a38f9dbaba0
7
+ data.tar.gz: 24365bbb7500da52d4b07ae1a54996d86a4ee98db465f15fe9b93aef4d6911ca072b1f48b1c1977351f0326607c271536b2b2b1df98b4831c70912be5adf0e65
data/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Release History: opentelemetry-api
2
2
 
3
+ ### v0.15.0 / 2021-02-18
4
+
5
+ * ADDED: Add instrumentation config validation
6
+ * DOCS: Clarify nil attribute values not allowed
7
+
3
8
  ### v0.14.0 / 2021-02-03
4
9
 
5
10
  * BREAKING CHANGE: Replace getter and setter callables and remove rack specific propagators
@@ -59,10 +59,18 @@ module OpenTelemetry
59
59
  # convention for environment variable name is the library name, upcased with
60
60
  # '::' replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG}, and '_ENABLED' appended.
61
61
  # For example: OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED = false.
62
- class Base
62
+ class Base # rubocop:disable Metrics/ClassLength
63
63
  class << self
64
64
  NAME_REGEX = /^(?:(?<namespace>[a-zA-Z0-9_:]+):{2})?(?<classname>[a-zA-Z0-9_]+)$/.freeze
65
- private_constant :NAME_REGEX
65
+ VALIDATORS = {
66
+ array: ->(v) { v.is_a?(Array) },
67
+ boolean: ->(v) { v == true || v == false }, # rubocop:disable Style/MultipleComparison
68
+ callable: ->(v) { v.respond_to?(:call) },
69
+ integer: ->(v) { v.is_a?(Integer) },
70
+ string: ->(v) { v.is_a?(String) }
71
+ }.freeze
72
+
73
+ private_constant :NAME_REGEX, :VALIDATORS
66
74
 
67
75
  private :new # rubocop:disable Style/AccessModifierDeclarations
68
76
 
@@ -129,14 +137,30 @@ module OpenTelemetry
129
137
  @compatible_blk = blk
130
138
  end
131
139
 
140
+ # The option method is used to define default configuration options
141
+ # for the instrumentation library. It requires a name, default value,
142
+ # and a validation callable to be provided.
143
+ # @param [String] name The name of the configuration option
144
+ # @param default The default value to be used, or to used if validation fails
145
+ # @param [Callable, Symbol] validate Accepts a callable or a symbol that matches
146
+ # a key in the VALIDATORS hash. The supported keys are, :array, :boolean,
147
+ # :callable, :integer, :string.
148
+ def option(name, default:, validate:)
149
+ validate = VALIDATORS[validate] || validate
150
+ raise ArgumentError, "validate must be #{VALIDATORS.keys.join(', ')}, or a callable" unless validate.respond_to?(:call)
151
+
152
+ @options ||= []
153
+ @options << { name: name, default: default, validate: validate }
154
+ end
155
+
132
156
  def instance
133
157
  @instance ||= new(instrumentation_name, instrumentation_version, install_blk,
134
- present_blk, compatible_blk)
158
+ present_blk, compatible_blk, options)
135
159
  end
136
160
 
137
161
  private
138
162
 
139
- attr_reader :install_blk, :present_blk, :compatible_blk
163
+ attr_reader :install_blk, :present_blk, :compatible_blk, :options
140
164
 
141
165
  def infer_name
142
166
  @inferred_name ||= if (md = name.match(NAME_REGEX)) # rubocop:disable Naming/MemoizedInstanceVariableName
@@ -161,7 +185,7 @@ module OpenTelemetry
161
185
  alias installed? installed
162
186
 
163
187
  def initialize(name, version, install_blk, present_blk,
164
- compatible_blk)
188
+ compatible_blk, options)
165
189
  @name = name
166
190
  @version = version
167
191
  @install_blk = install_blk
@@ -169,6 +193,7 @@ module OpenTelemetry
169
193
  @compatible_blk = compatible_blk
170
194
  @config = {}
171
195
  @installed = false
196
+ @options = options
172
197
  end
173
198
 
174
199
  # Install instrumentation with the given config. The present? and compatible?
@@ -180,7 +205,7 @@ module OpenTelemetry
180
205
  return true if installed?
181
206
  return false unless installable?(config)
182
207
 
183
- @config = config unless config.nil?
208
+ @config = config_options(config)
184
209
  instance_exec(@config, &@install_blk)
185
210
  @tracer ||= OpenTelemetry.tracer_provider.tracer(name, version)
186
211
  @installed = true
@@ -225,6 +250,43 @@ module OpenTelemetry
225
250
 
226
251
  private
227
252
 
253
+ # The config_options method is responsible for validating that the user supplied
254
+ # config hash is valid.
255
+ # Unknown configuration keys are not included in the final config hash.
256
+ # Invalid configuration values are logged, and replaced by the default.
257
+ #
258
+ # @param [Hash] user_config The user supplied configuration hash
259
+ def config_options(user_config) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
260
+ @options ||= {}
261
+ user_config ||= {}
262
+ validated_config = @options.each_with_object({}) do |option, h|
263
+ option_name = option[:name]
264
+ config_value = user_config[option_name]
265
+
266
+ value = if config_value.nil?
267
+ option[:default]
268
+ elsif option[:validate].call(config_value)
269
+ config_value
270
+ else
271
+ OpenTelemetry.logger.warn(
272
+ "Instrumentation #{name} configuration option #{option_name} value=#{config_value} " \
273
+ "failed validation, falling back to default value=#{option[:default]}"
274
+ )
275
+ option[:default]
276
+ end
277
+
278
+ h[option_name] = value
279
+ rescue StandardError => e
280
+ OpenTelemetry.handle_error(exception: e, message: "Instrumentation #{name} unexpected configuration error")
281
+ h[option_name] = option[:default]
282
+ end
283
+
284
+ dropped_config_keys = user_config.keys - validated_config.keys
285
+ OpenTelemetry.logger.warn("Instrumentation #{name} ignored the following unknown configuration options #{dropped_config_keys}") unless dropped_config_keys.empty?
286
+
287
+ validated_config
288
+ end
289
+
228
290
  # Checks to see if this instrumentation is enabled by env var. By convention, the
229
291
  # environment variable will be the instrumentation name upper cased, with '::'
230
292
  # replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG} and _ENABLED appended.
@@ -51,6 +51,9 @@ module OpenTelemetry
51
51
  #
52
52
  # @param [String] key
53
53
  # @param [String, Boolean, Numeric, Array<String, Numeric, Boolean>] value
54
+ # Values must be non-nil and (array of) string, boolean or numeric type.
55
+ # Array values must not contain nil elements and all elements must be of
56
+ # the same basic type (string, numeric, boolean).
54
57
  #
55
58
  # @return [self] returns itself
56
59
  def set_attribute(key, value)
@@ -6,5 +6,5 @@
6
6
 
7
7
  module OpenTelemetry
8
8
  ## Current OpenTelemetry version
9
- VERSION = '0.14.0'
9
+ VERSION = '0.15.0'
10
10
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: opentelemetry-api
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.14.0
4
+ version: 0.15.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - OpenTelemetry Authors
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-02-03 00:00:00.000000000 Z
11
+ date: 2021-02-18 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: benchmark-ipsa
@@ -196,10 +196,10 @@ homepage: https://github.com/open-telemetry/opentelemetry-ruby
196
196
  licenses:
197
197
  - Apache-2.0
198
198
  metadata:
199
- changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.14.0/file.CHANGELOG.html
199
+ changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.15.0/file.CHANGELOG.html
200
200
  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/api
201
201
  bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
202
- documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.14.0
202
+ documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-api/v0.15.0
203
203
  post_install_message:
204
204
  rdoc_options: []
205
205
  require_paths: