opentelemetry-api 0.3.0 → 0.7.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 +4 -4
- data/.yardopts +2 -2
- data/CHANGELOG.md +19 -0
- data/LICENSE +1 -1
- data/{OVERVIEW.md → README.md} +0 -0
- data/lib/opentelemetry.rb +11 -11
- data/lib/opentelemetry/baggage.rb +16 -0
- data/lib/opentelemetry/{correlation_context → baggage}/builder.rb +2 -2
- data/lib/opentelemetry/{correlation_context → baggage}/manager.rb +8 -3
- data/lib/opentelemetry/baggage/propagation.rb +57 -0
- data/lib/opentelemetry/baggage/propagation/context_keys.rb +27 -0
- data/lib/opentelemetry/{correlation_context/propagation/text_extractor.rb → baggage/propagation/text_map_extractor.rb} +14 -14
- data/lib/opentelemetry/baggage/propagation/text_map_injector.rb +55 -0
- data/lib/opentelemetry/context/propagation/composite_propagator.rb +8 -12
- data/lib/opentelemetry/instrumentation.rb +2 -2
- data/lib/opentelemetry/instrumentation/{adapter.rb → base.rb} +54 -53
- data/lib/opentelemetry/instrumentation/registry.rb +32 -32
- data/lib/opentelemetry/trace.rb +13 -16
- data/lib/opentelemetry/trace/propagation/trace_context.rb +11 -11
- data/lib/opentelemetry/trace/propagation/trace_context/{text_extractor.rb → text_map_extractor.rb} +5 -4
- data/lib/opentelemetry/trace/propagation/trace_context/{text_injector.rb → text_map_injector.rb} +4 -5
- data/lib/opentelemetry/trace/propagation/trace_context/trace_parent.rb +9 -5
- data/lib/opentelemetry/trace/span.rb +10 -18
- data/lib/opentelemetry/trace/span_context.rb +25 -1
- data/lib/opentelemetry/trace/status.rb +7 -65
- data/lib/opentelemetry/trace/tracer.rb +20 -28
- data/lib/opentelemetry/trace/util/http_to_status.rb +4 -23
- data/lib/opentelemetry/version.rb +1 -1
- metadata +15 -17
- data/lib/opentelemetry/correlation_context.rb +0 -16
- data/lib/opentelemetry/correlation_context/propagation.rb +0 -57
- data/lib/opentelemetry/correlation_context/propagation/context_keys.rb +0 -27
- data/lib/opentelemetry/correlation_context/propagation/text_injector.rb +0 -55
- data/lib/opentelemetry/internal.rb +0 -22
- data/lib/opentelemetry/trace/event.rb +0 -46
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 9aa5a0850640df96314f3fd539394f878d899b47e1a95e725abc6c0afd6b5a68
|
4
|
+
data.tar.gz: c64e3676eb965f77f64a14dd5b515128644d79e8337df46c49ddf652496c8384
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: e72ba6591aa9c38b2036c1c27994f280d331fca28817d19fba52991f4477afde6f1bbca040eeb8d4049f084e63ca1e7666f1ff7eed86a1ce43fd79995b4d0fa4
|
7
|
+
data.tar.gz: 903010838dae911df19e9f06dc41080bce7640eb7caab03b6b4c9ca36a9a65105f9b58ef68f3bb5258e66d30015286cb8b9d18ca9ae600c9e31b124412ce2872
|
data/.yardopts
CHANGED
data/CHANGELOG.md
CHANGED
@@ -1 +1,20 @@
|
|
1
1
|
# Release History: opentelemetry-api
|
2
|
+
|
3
|
+
### v0.7.0 / 2020-10-07
|
4
|
+
|
5
|
+
* FIXED: Safely navigate span variable during error cases
|
6
|
+
* DOCS: Standardize toplevel docs structure and readme
|
7
|
+
* DOCS: Fix param description in TextMapInjector for Baggage
|
8
|
+
|
9
|
+
### v0.6.0 / 2020-09-10
|
10
|
+
|
11
|
+
* ADDED: Add support for OTEL_LOG_LEVEL env var
|
12
|
+
* Documented array valued attributes [#343](https://github.com/open-telemetry/opentelemetry-ruby/pull/343)
|
13
|
+
* Renamed CorrelationContext to Baggage [#338](https://github.com/open-telemetry/opentelemetry-ruby/pull/338)
|
14
|
+
* Renamed Text* to TextMap* (propagators) [#335](https://github.com/open-telemetry/opentelemetry-ruby/pull/335)
|
15
|
+
* Fixed exception semantic conventions (`span.record_error` -> `span.record_exception`) [#333](https://github.com/open-telemetry/opentelemetry-ruby/pull/333)
|
16
|
+
* Removed support for lazy event creation [#329](https://github.com/open-telemetry/opentelemetry-ruby/pull/329)
|
17
|
+
* `name:` named parameter to `span.add_event` becomes first positional argument
|
18
|
+
* `Event` class removed from API
|
19
|
+
* Added `hex_trace_id` and `hex_span_id` helpers to `SpanContext` [#332](https://github.com/open-telemetry/opentelemetry-ruby/pull/332)
|
20
|
+
* Added `CorrelationContext::Manager.values` method to return correlations as a `Hash` [#323](https://github.com/open-telemetry/opentelemetry-ruby/pull/323)
|
data/LICENSE
CHANGED
@@ -186,7 +186,7 @@
|
|
186
186
|
same "printed page" as the copyright notice for easier
|
187
187
|
identification within third-party archives.
|
188
188
|
|
189
|
-
Copyright
|
189
|
+
Copyright 2020 OpenTelemetry Authors
|
190
190
|
|
191
191
|
Licensed under the Apache License, Version 2.0 (the "License");
|
192
192
|
you may not use this file except in compliance with the License.
|
data/{OVERVIEW.md → README.md}
RENAMED
File without changes
|
data/lib/opentelemetry.rb
CHANGED
@@ -8,9 +8,8 @@ require 'logger'
|
|
8
8
|
|
9
9
|
require 'opentelemetry/error'
|
10
10
|
require 'opentelemetry/context'
|
11
|
-
require 'opentelemetry/
|
12
|
-
|
13
|
-
require 'opentelemetry/instrumentation'
|
11
|
+
require 'opentelemetry/baggage'
|
12
|
+
require_relative './opentelemetry/instrumentation'
|
14
13
|
require 'opentelemetry/metrics'
|
15
14
|
require 'opentelemetry/trace'
|
16
15
|
require 'opentelemetry/version'
|
@@ -23,9 +22,12 @@ require 'opentelemetry/version'
|
|
23
22
|
module OpenTelemetry
|
24
23
|
extend self
|
25
24
|
|
26
|
-
attr_writer :tracer_provider, :meter_provider, :
|
25
|
+
attr_writer :tracer_provider, :meter_provider, :baggage, :logger
|
27
26
|
|
28
|
-
|
27
|
+
# @return [Object, Logger] configured Logger or a default STDOUT Logger.
|
28
|
+
def logger
|
29
|
+
@logger ||= Logger.new(STDOUT, level: ENV['OTEL_LOG_LEVEL'] || Logger::INFO)
|
30
|
+
end
|
29
31
|
|
30
32
|
# @return [Object, Trace::TracerProvider] registered tracer provider or a
|
31
33
|
# default no-op implementation of the tracer provider.
|
@@ -45,17 +47,15 @@ module OpenTelemetry
|
|
45
47
|
@instrumentation_registry ||= Instrumentation::Registry.new
|
46
48
|
end
|
47
49
|
|
48
|
-
# @return [Object,
|
49
|
-
#
|
50
|
+
# @return [Object, Baggage::Manager] registered
|
51
|
+
# baggage manager or a default no-op implementation of the
|
50
52
|
# manager.
|
51
|
-
def
|
52
|
-
@
|
53
|
+
def baggage
|
54
|
+
@baggage ||= Baggage::Manager.new
|
53
55
|
end
|
54
56
|
|
55
57
|
# @return [Context::Propagation::Propagation] an instance of the propagation API
|
56
58
|
def propagation
|
57
59
|
@propagation ||= Context::Propagation::Propagation.new
|
58
60
|
end
|
59
|
-
|
60
|
-
self.logger = Logger.new(STDOUT)
|
61
61
|
end
|
@@ -0,0 +1,16 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Copyright 2019 OpenTelemetry Authors
|
4
|
+
#
|
5
|
+
# SPDX-License-Identifier: Apache-2.0
|
6
|
+
|
7
|
+
require 'opentelemetry/baggage/builder'
|
8
|
+
require 'opentelemetry/baggage/manager'
|
9
|
+
require 'opentelemetry/baggage/propagation'
|
10
|
+
|
11
|
+
module OpenTelemetry
|
12
|
+
# The Baggage module provides functionality to record and propagate
|
13
|
+
# baggage in a distributed trace
|
14
|
+
module Baggage
|
15
|
+
end
|
16
|
+
end
|
@@ -5,8 +5,8 @@
|
|
5
5
|
# SPDX-License-Identifier: Apache-2.0
|
6
6
|
|
7
7
|
module OpenTelemetry
|
8
|
-
module
|
9
|
-
# No op implementation of
|
8
|
+
module Baggage
|
9
|
+
# No op implementation of Baggage::Builder
|
10
10
|
class Builder
|
11
11
|
def set_value(key, value); end
|
12
12
|
|
@@ -5,11 +5,12 @@
|
|
5
5
|
# SPDX-License-Identifier: Apache-2.0
|
6
6
|
|
7
7
|
module OpenTelemetry
|
8
|
-
module
|
9
|
-
# No op implementation of
|
8
|
+
module Baggage
|
9
|
+
# No op implementation of Baggage::Manager
|
10
10
|
class Manager
|
11
11
|
NOOP_BUILDER = Builder.new
|
12
|
-
|
12
|
+
EMPTY_VALUES = {}.freeze
|
13
|
+
private_constant(:NOOP_BUILDER, :EMPTY_VALUES)
|
13
14
|
|
14
15
|
def build(context: Context.current)
|
15
16
|
yield NOOP_BUILDER
|
@@ -24,6 +25,10 @@ module OpenTelemetry
|
|
24
25
|
nil
|
25
26
|
end
|
26
27
|
|
28
|
+
def values(context: Context.current)
|
29
|
+
EMPTY_VALUES
|
30
|
+
end
|
31
|
+
|
27
32
|
def remove_value(key, context: Context.current)
|
28
33
|
context
|
29
34
|
end
|
@@ -0,0 +1,57 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Copyright 2019 OpenTelemetry Authors
|
4
|
+
#
|
5
|
+
# SPDX-License-Identifier: Apache-2.0
|
6
|
+
|
7
|
+
require 'opentelemetry/baggage/propagation/context_keys'
|
8
|
+
require 'opentelemetry/baggage/propagation/text_map_injector'
|
9
|
+
require 'opentelemetry/baggage/propagation/text_map_extractor'
|
10
|
+
|
11
|
+
module OpenTelemetry
|
12
|
+
module Baggage
|
13
|
+
# The Baggage::Propagation module contains injectors and
|
14
|
+
# extractors for sending and receiving baggage over the wire
|
15
|
+
module Propagation
|
16
|
+
extend self
|
17
|
+
|
18
|
+
TEXT_MAP_EXTRACTOR = TextMapExtractor.new
|
19
|
+
TEXT_MAP_INJECTOR = TextMapInjector.new
|
20
|
+
RACK_EXTRACTOR = TextMapExtractor.new(
|
21
|
+
baggage_key: 'HTTP_BAGGAGE'
|
22
|
+
)
|
23
|
+
RACK_INJECTOR = TextMapInjector.new(
|
24
|
+
baggage_key: 'HTTP_BAGGAGE'
|
25
|
+
)
|
26
|
+
|
27
|
+
private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR, :RACK_INJECTOR,
|
28
|
+
:RACK_EXTRACTOR
|
29
|
+
|
30
|
+
# Returns an extractor that extracts context using the W3C Baggage
|
31
|
+
# format
|
32
|
+
def text_map_injector
|
33
|
+
TEXT_MAP_INJECTOR
|
34
|
+
end
|
35
|
+
|
36
|
+
# Returns an injector that injects context using the W3C Baggage
|
37
|
+
# format
|
38
|
+
def text_map_extractor
|
39
|
+
TEXT_MAP_EXTRACTOR
|
40
|
+
end
|
41
|
+
|
42
|
+
# Returns an extractor that extracts context using the W3C Baggage
|
43
|
+
# format with Rack normalized keys (upcased and prefixed with
|
44
|
+
# HTTP_)
|
45
|
+
def rack_injector
|
46
|
+
RACK_INJECTOR
|
47
|
+
end
|
48
|
+
|
49
|
+
# Returns an injector that injects context using the W3C Baggage
|
50
|
+
# format with Rack normalized keys (upcased and prefixed with
|
51
|
+
# HTTP_)
|
52
|
+
def rack_extractor
|
53
|
+
RACK_EXTRACTOR
|
54
|
+
end
|
55
|
+
end
|
56
|
+
end
|
57
|
+
end
|
@@ -0,0 +1,27 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Copyright 2019 OpenTelemetry Authors
|
4
|
+
#
|
5
|
+
# SPDX-License-Identifier: Apache-2.0
|
6
|
+
|
7
|
+
module OpenTelemetry
|
8
|
+
module Baggage
|
9
|
+
module Propagation
|
10
|
+
# The ContextKeys module contains the keys used to index baggage
|
11
|
+
# in a {Context} instance
|
12
|
+
module ContextKeys
|
13
|
+
extend self
|
14
|
+
|
15
|
+
BAGGAGE_KEY = Context.create_key('baggage')
|
16
|
+
private_constant :BAGGAGE_KEY
|
17
|
+
|
18
|
+
# Returns the context key that baggage are indexed by
|
19
|
+
#
|
20
|
+
# @return [Context::Key]
|
21
|
+
def baggage_key
|
22
|
+
BAGGAGE_KEY
|
23
|
+
end
|
24
|
+
end
|
25
|
+
end
|
26
|
+
end
|
27
|
+
end
|
@@ -7,41 +7,41 @@
|
|
7
7
|
require 'cgi'
|
8
8
|
|
9
9
|
module OpenTelemetry
|
10
|
-
module
|
10
|
+
module Baggage
|
11
11
|
module Propagation
|
12
|
-
# Extracts
|
13
|
-
class
|
12
|
+
# Extracts baggage from carriers in the W3C Baggage format
|
13
|
+
class TextMapExtractor
|
14
14
|
include Context::Propagation::DefaultGetter
|
15
15
|
|
16
|
-
# Returns a new
|
16
|
+
# Returns a new TextMapExtractor that extracts context using the specified
|
17
17
|
# header key
|
18
18
|
#
|
19
|
-
# @param [String]
|
19
|
+
# @param [String] baggage_key The baggage header
|
20
20
|
# key used in the carrier
|
21
|
-
# @return [
|
22
|
-
def initialize(
|
23
|
-
@
|
21
|
+
# @return [TextMapExtractor]
|
22
|
+
def initialize(baggage_key: 'baggage')
|
23
|
+
@baggage_key = baggage_key
|
24
24
|
end
|
25
25
|
|
26
|
-
# Extract remote
|
26
|
+
# Extract remote baggage from the supplied carrier.
|
27
27
|
# If extraction fails, the original context will be returned
|
28
28
|
#
|
29
29
|
# @param [Carrier] carrier The carrier to get the header from
|
30
|
-
# @param [Context] context The context to be updated with extracted
|
30
|
+
# @param [Context] context The context to be updated with extracted baggage
|
31
31
|
# @param [optional Callable] getter An optional callable that takes a carrier and a key and
|
32
32
|
# returns the value associated with the key. If omitted the default getter will be used
|
33
33
|
# which expects the carrier to respond to [] and []=.
|
34
34
|
# @yield [Carrier, String] if an optional getter is provided, extract will yield the carrier
|
35
35
|
# and the header key to the getter.
|
36
|
-
# @return [Context] context updated with extracted
|
36
|
+
# @return [Context] context updated with extracted baggage, or the original context
|
37
37
|
# if extraction fails
|
38
38
|
def extract(carrier, context, &getter)
|
39
39
|
getter ||= default_getter
|
40
|
-
header = getter.call(carrier, @
|
40
|
+
header = getter.call(carrier, @baggage_key)
|
41
41
|
|
42
42
|
entries = header.gsub(/\s/, '').split(',')
|
43
43
|
|
44
|
-
|
44
|
+
baggage = entries.each_with_object({}) do |entry, memo|
|
45
45
|
# The ignored variable below holds properties as per the W3C spec.
|
46
46
|
# OTel is not using them currently, but they might be used for
|
47
47
|
# metadata in the future
|
@@ -50,7 +50,7 @@ module OpenTelemetry
|
|
50
50
|
memo[k] = v
|
51
51
|
end
|
52
52
|
|
53
|
-
context.set_value(ContextKeys.
|
53
|
+
context.set_value(ContextKeys.baggage_key, baggage)
|
54
54
|
rescue StandardError
|
55
55
|
context
|
56
56
|
end
|
@@ -0,0 +1,55 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Copyright 2019 OpenTelemetry Authors
|
4
|
+
#
|
5
|
+
# SPDX-License-Identifier: Apache-2.0
|
6
|
+
|
7
|
+
require 'cgi'
|
8
|
+
|
9
|
+
module OpenTelemetry
|
10
|
+
module Baggage
|
11
|
+
module Propagation
|
12
|
+
# Injects baggage using the W3C Baggage format
|
13
|
+
class TextMapInjector
|
14
|
+
include Context::Propagation::DefaultSetter
|
15
|
+
|
16
|
+
# Returns a new TextMapInjector that injects context using the specified
|
17
|
+
# header key
|
18
|
+
#
|
19
|
+
# @param [String] baggage_key The baggage header
|
20
|
+
# key used in the carrier
|
21
|
+
# @return [TextMapInjector]
|
22
|
+
def initialize(baggage_key: 'baggage')
|
23
|
+
@baggage_key = baggage_key
|
24
|
+
end
|
25
|
+
|
26
|
+
# Inject in-process baggage into the supplied carrier.
|
27
|
+
#
|
28
|
+
# @param [Carrier] carrier The carrier to inject baggage into
|
29
|
+
# @param [Context] context The context to read baggage from
|
30
|
+
# @param [optional Callable] getter An optional callable that takes a carrier and a key and
|
31
|
+
# returns the value associated with the key. If omitted the default getter will be used
|
32
|
+
# which expects the carrier to respond to [] and []=.
|
33
|
+
# @yield [Carrier, String] if an optional getter is provided, inject will yield the carrier
|
34
|
+
# and the header key to the getter.
|
35
|
+
# @return [Object] carrier with injected baggage
|
36
|
+
def inject(carrier, context, &setter)
|
37
|
+
return carrier unless (baggage = context[ContextKeys.baggage_key]) && !baggage.empty?
|
38
|
+
|
39
|
+
setter ||= default_setter
|
40
|
+
setter.call(carrier, @baggage_key, encode(baggage))
|
41
|
+
|
42
|
+
carrier
|
43
|
+
end
|
44
|
+
|
45
|
+
private
|
46
|
+
|
47
|
+
def encode(baggage)
|
48
|
+
baggage.inject(+'') do |memo, (k, v)|
|
49
|
+
memo << CGI.escape(k.to_s) << '=' << CGI.escape(v.to_s) << ','
|
50
|
+
end.chop!
|
51
|
+
end
|
52
|
+
end
|
53
|
+
end
|
54
|
+
end
|
55
|
+
end
|
@@ -38,12 +38,10 @@ module OpenTelemetry
|
|
38
38
|
# @return [Object] carrier
|
39
39
|
def inject(carrier, context = Context.current, &setter)
|
40
40
|
@injectors.inject(carrier) do |memo, injector|
|
41
|
-
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
carrier
|
46
|
-
end
|
41
|
+
injector.inject(memo, context, &setter)
|
42
|
+
rescue => e # rubocop:disable Style/RescueStandardError
|
43
|
+
OpenTelemetry.logger.warn "Error in CompositePropagator#inject #{e.message}"
|
44
|
+
carrier
|
47
45
|
end
|
48
46
|
end
|
49
47
|
|
@@ -63,12 +61,10 @@ module OpenTelemetry
|
|
63
61
|
# carrier
|
64
62
|
def extract(carrier, context = Context.current, &getter)
|
65
63
|
@extractors.inject(context) do |ctx, extractor|
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
ctx
|
71
|
-
end
|
64
|
+
extractor.extract(carrier, ctx, &getter)
|
65
|
+
rescue => e # rubocop:disable Style/RescueStandardError
|
66
|
+
OpenTelemetry.logger.warn "Error in CompositePropagator#extract #{e.message}"
|
67
|
+
ctx
|
72
68
|
end
|
73
69
|
end
|
74
70
|
end
|
@@ -5,11 +5,11 @@
|
|
5
5
|
# SPDX-License-Identifier: Apache-2.0
|
6
6
|
|
7
7
|
require 'opentelemetry/instrumentation/registry'
|
8
|
-
require 'opentelemetry/instrumentation/
|
8
|
+
require 'opentelemetry/instrumentation/base'
|
9
9
|
|
10
10
|
module OpenTelemetry
|
11
11
|
# The instrumentation module contains functionality to register and install
|
12
|
-
# instrumentation
|
12
|
+
# instrumentation
|
13
13
|
module Instrumentation
|
14
14
|
end
|
15
15
|
end
|
@@ -6,20 +6,20 @@
|
|
6
6
|
|
7
7
|
module OpenTelemetry
|
8
8
|
module Instrumentation
|
9
|
-
# The
|
10
|
-
# instrumentation
|
11
|
-
# include a subclass of +Instrumentation::
|
9
|
+
# The Base class holds all metadata and configuration for an
|
10
|
+
# instrumentation. All instrumentation packages should
|
11
|
+
# include a subclass of +Instrumentation::Base+ that will register
|
12
12
|
# it with +OpenTelemetry.instrumentation_registry+ and make it available for
|
13
13
|
# discovery and installation by an SDK.
|
14
14
|
#
|
15
|
-
# A typical subclass of
|
15
|
+
# A typical subclass of Base will provide an install block, a present
|
16
16
|
# block, and possibly a compatible block. Below is an
|
17
17
|
# example:
|
18
18
|
#
|
19
19
|
# module OpenTelemetry
|
20
|
-
# module
|
20
|
+
# module Instrumentation
|
21
21
|
# module Sinatra
|
22
|
-
# class
|
22
|
+
# class Instrumentation < OpenTelemetry::Instrumentation::Base
|
23
23
|
# install do |config|
|
24
24
|
# # install instrumentation, either by library hook or applying
|
25
25
|
# # a monkey patch
|
@@ -39,27 +39,27 @@ module OpenTelemetry
|
|
39
39
|
# end
|
40
40
|
# end
|
41
41
|
#
|
42
|
-
# The
|
43
|
-
# class. In this example, they'd be 'OpenTelemetry::
|
44
|
-
# OpenTelemetry::
|
45
|
-
# the +
|
42
|
+
# The instrumentation name and version will be inferred from the namespace of the
|
43
|
+
# class. In this example, they'd be 'OpenTelemetry::Instrumentation::Sinatra' and
|
44
|
+
# OpenTelemetry::Instrumentation::Sinatra::VERSION, but can be explicitly set using
|
45
|
+
# the +instrumentation_name+ and +instrumetation_version+ methods if necessary.
|
46
46
|
#
|
47
|
-
# All subclasses of OpenTelemetry::Instrumentation::
|
47
|
+
# All subclasses of OpenTelemetry::Instrumentation::Base are automatically
|
48
48
|
# registered with OpenTelemetry.instrumentation_registry which is used by
|
49
49
|
# SDKs for instrumentation discovery and installation.
|
50
50
|
#
|
51
|
-
# Instrumentation libraries can use the
|
51
|
+
# Instrumentation libraries can use the instrumentation subclass to easily gain
|
52
52
|
# a reference to its named tracer. For example:
|
53
53
|
#
|
54
|
-
# OpenTelemetry::
|
54
|
+
# OpenTelemetry::Instrumentation::Sinatra.instance.tracer
|
55
55
|
#
|
56
|
-
# The
|
57
|
-
# by environment variable and local configuration. An
|
56
|
+
# The instrumention class establishes a convention for disabling an instrumentation
|
57
|
+
# by environment variable and local configuration. An instrumentation disabled
|
58
58
|
# by environment variable will take precedence over local config. The
|
59
59
|
# convention for environment variable name is the library name, upcased with
|
60
|
-
# '::' replaced by underscores, and '_ENABLED' appended.
|
61
|
-
#
|
62
|
-
class
|
60
|
+
# '::' replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG}, and '_ENABLED' appended.
|
61
|
+
# For example: OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED = false.
|
62
|
+
class Base
|
63
63
|
class << self
|
64
64
|
NAME_REGEX = /^(?:(?<namespace>[a-zA-Z0-9_:]+):{2})?(?<classname>[a-zA-Z0-9_]+)$/.freeze
|
65
65
|
private_constant :NAME_REGEX
|
@@ -70,67 +70,67 @@ module OpenTelemetry
|
|
70
70
|
OpenTelemetry.instrumentation_registry.register(subclass)
|
71
71
|
end
|
72
72
|
|
73
|
-
# Optionally set the name of this instrumentation
|
73
|
+
# Optionally set the name of this instrumentation. If not
|
74
74
|
# explicitly set, the name will default to the namespace of the class,
|
75
75
|
# or the class name if it does not have a namespace. If there is not
|
76
76
|
# a namespace, or a class name, it will default to 'unknown'.
|
77
77
|
#
|
78
|
-
# @param [String]
|
79
|
-
def
|
80
|
-
if
|
81
|
-
@
|
78
|
+
# @param [String] instrumentation_name The full name of the instrumentation package
|
79
|
+
def instrumentation_name(instrumentation_name = nil)
|
80
|
+
if instrumentation_name
|
81
|
+
@instrumentation_name = instrumentation_name
|
82
82
|
else
|
83
|
-
@
|
83
|
+
@instrumentation_name ||= infer_name || 'unknown'
|
84
84
|
end
|
85
85
|
end
|
86
86
|
|
87
|
-
# Optionally set the version of this
|
87
|
+
# Optionally set the version of this instrumentation. If not explicitly set,
|
88
88
|
# the version will default to the VERSION constant under namespace of
|
89
89
|
# the class, or the VERSION constant under the class name if it does not
|
90
90
|
# have a namespace. If a VERSION constant cannot be found, it defaults
|
91
91
|
# to '0.0.0'.
|
92
92
|
#
|
93
|
-
# @param [String]
|
94
|
-
def
|
95
|
-
if
|
96
|
-
@
|
93
|
+
# @param [String] instrumentation_version The version of the instrumentation package
|
94
|
+
def instrumentation_version(instrumentation_version = nil)
|
95
|
+
if instrumentation_version
|
96
|
+
@instrumentation_version = instrumentation_version
|
97
97
|
else
|
98
|
-
@
|
98
|
+
@instrumentation_version ||= infer_version || '0.0.0'
|
99
99
|
end
|
100
100
|
end
|
101
101
|
|
102
|
-
# The install block for this
|
102
|
+
# The install block for this instrumentation. This will be where you install
|
103
103
|
# instrumentation, either by framework hook or applying a monkey patch.
|
104
104
|
#
|
105
|
-
# @param [Callable] blk The install block for this
|
106
|
-
# @yieldparam [Hash] config The
|
105
|
+
# @param [Callable] blk The install block for this instrumentation
|
106
|
+
# @yieldparam [Hash] config The instrumentation config will be yielded to the
|
107
107
|
# install block
|
108
108
|
def install(&blk)
|
109
109
|
@install_blk = blk
|
110
110
|
end
|
111
111
|
|
112
|
-
# The present block for this
|
112
|
+
# The present block for this instrumentation. This block is used to detect if
|
113
113
|
# target library is present on the system. Typically this will involve
|
114
114
|
# checking to see if the target gem spec was loaded or if expected
|
115
115
|
# constants from the target library are present.
|
116
116
|
#
|
117
|
-
# @param [Callable] blk The present block for this
|
117
|
+
# @param [Callable] blk The present block for this instrumentation
|
118
118
|
def present(&blk)
|
119
119
|
@present_blk = blk
|
120
120
|
end
|
121
121
|
|
122
|
-
# The compatible block for this
|
122
|
+
# The compatible block for this instrumentation. This check will be run if the
|
123
123
|
# target library is present to determine if it's compatible. It's not
|
124
124
|
# required, but a common use case will be to check to target library
|
125
125
|
# version for compatibility.
|
126
126
|
#
|
127
|
-
# @param [Callable] blk The compatibility block for this
|
127
|
+
# @param [Callable] blk The compatibility block for this instrumentation
|
128
128
|
def compatible(&blk)
|
129
129
|
@compatible_blk = blk
|
130
130
|
end
|
131
131
|
|
132
132
|
def instance
|
133
|
-
@instance ||= new(
|
133
|
+
@instance ||= new(instrumentation_name, instrumentation_version, install_blk,
|
134
134
|
present_blk, compatible_blk)
|
135
135
|
end
|
136
136
|
|
@@ -171,11 +171,11 @@ module OpenTelemetry
|
|
171
171
|
@installed = false
|
172
172
|
end
|
173
173
|
|
174
|
-
# Install
|
174
|
+
# Install instrumentation with the given config. The present? and compatible?
|
175
175
|
# will be run first, and install will return false if either fail. Will
|
176
176
|
# return true if install was completed successfully.
|
177
177
|
#
|
178
|
-
# @param [Hash] config The config for this
|
178
|
+
# @param [Hash] config The config for this instrumentation
|
179
179
|
def install(config = {})
|
180
180
|
return true if installed?
|
181
181
|
return false unless installable?(config)
|
@@ -186,24 +186,24 @@ module OpenTelemetry
|
|
186
186
|
@installed = true
|
187
187
|
end
|
188
188
|
|
189
|
-
# Whether or not this
|
190
|
-
# be true when the
|
189
|
+
# Whether or not this instrumentation is installable in the current process. Will
|
190
|
+
# be true when the instrumentation defines an install block, is not disabled
|
191
191
|
# by environment or config, and the target library present and compatible.
|
192
192
|
#
|
193
|
-
# @param [Hash] config The config for this
|
193
|
+
# @param [Hash] config The config for this instrumentation
|
194
194
|
def installable?(config = {})
|
195
195
|
@install_blk && enabled?(config) && present? && compatible?
|
196
196
|
end
|
197
197
|
|
198
|
-
# Calls the present block of the
|
199
|
-
# it's assumed the
|
198
|
+
# Calls the present block of the Instrumentation subclasses, if no block is provided
|
199
|
+
# it's assumed the instrumentation is not present
|
200
200
|
def present?
|
201
201
|
return false unless @present_blk
|
202
202
|
|
203
203
|
instance_exec(&@present_blk)
|
204
204
|
end
|
205
205
|
|
206
|
-
# Calls the compatible block of the
|
206
|
+
# Calls the compatible block of the Instrumentation subclasses, if no block is provided
|
207
207
|
# it's assumed to be compatible
|
208
208
|
def compatible?
|
209
209
|
return true unless @compatible_blk
|
@@ -211,7 +211,7 @@ module OpenTelemetry
|
|
211
211
|
instance_exec(&@compatible_blk)
|
212
212
|
end
|
213
213
|
|
214
|
-
# Whether this
|
214
|
+
# Whether this instrumentation is enabled. It first checks to see if it's enabled
|
215
215
|
# by an environment variable and will proceed to check if it's enabled
|
216
216
|
# by local config, if given.
|
217
217
|
#
|
@@ -225,16 +225,17 @@ module OpenTelemetry
|
|
225
225
|
|
226
226
|
private
|
227
227
|
|
228
|
-
# Checks to see if this
|
229
|
-
# environment variable will be the
|
230
|
-
# replaced by underscores and _ENABLED appended.
|
231
|
-
# environment variable name for OpenTelemetry::
|
232
|
-
#
|
233
|
-
# the
|
228
|
+
# Checks to see if this instrumentation is enabled by env var. By convention, the
|
229
|
+
# environment variable will be the instrumentation name upper cased, with '::'
|
230
|
+
# replaced by underscores, OPENTELEMETRY shortened to OTEL_{LANG} and _ENABLED appended.
|
231
|
+
# For example, the, environment variable name for OpenTelemetry::Instrumentation::Sinatra
|
232
|
+
# will be OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED. A value of 'false' will disable
|
233
|
+
# the instrumentation, all other values will enable it.
|
234
234
|
def enabled_by_env_var?
|
235
235
|
var_name = name.dup.tap do |n|
|
236
236
|
n.upcase!
|
237
237
|
n.gsub!('::', '_')
|
238
|
+
n.gsub!('OPENTELEMETRY_', 'OTEL_RUBY_')
|
238
239
|
n << '_ENABLED'
|
239
240
|
end
|
240
241
|
ENV[var_name] != 'false'
|