opentelemetry-api 0.5.1 → 0.10.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.
Files changed (33) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +2 -2
  3. data/CHANGELOG.md +38 -0
  4. data/{OVERVIEW.md → README.md} +0 -0
  5. data/lib/opentelemetry.rb +10 -10
  6. data/lib/opentelemetry/baggage.rb +16 -0
  7. data/lib/opentelemetry/{correlation_context → baggage}/builder.rb +2 -2
  8. data/lib/opentelemetry/{correlation_context → baggage}/manager.rb +8 -3
  9. data/lib/opentelemetry/baggage/propagation.rb +57 -0
  10. data/lib/opentelemetry/baggage/propagation/context_keys.rb +27 -0
  11. data/lib/opentelemetry/{correlation_context/propagation/text_extractor.rb → baggage/propagation/text_map_extractor.rb} +14 -14
  12. data/lib/opentelemetry/baggage/propagation/text_map_injector.rb +55 -0
  13. data/lib/opentelemetry/trace.rb +38 -4
  14. data/lib/opentelemetry/trace/link.rb +3 -3
  15. data/lib/opentelemetry/trace/propagation.rb +0 -1
  16. data/lib/opentelemetry/trace/propagation/trace_context.rb +11 -11
  17. data/lib/opentelemetry/trace/propagation/trace_context/{text_extractor.rb → text_map_extractor.rb} +5 -4
  18. data/lib/opentelemetry/trace/propagation/trace_context/{text_injector.rb → text_map_injector.rb} +5 -6
  19. data/lib/opentelemetry/trace/propagation/trace_context/trace_parent.rb +4 -4
  20. data/lib/opentelemetry/trace/span.rb +10 -18
  21. data/lib/opentelemetry/trace/span_context.rb +25 -1
  22. data/lib/opentelemetry/trace/status.rb +13 -71
  23. data/lib/opentelemetry/trace/tracer.rb +13 -54
  24. data/lib/opentelemetry/trace/util/http_to_status.rb +4 -23
  25. data/lib/opentelemetry/version.rb +1 -1
  26. metadata +18 -17
  27. data/lib/opentelemetry/correlation_context.rb +0 -16
  28. data/lib/opentelemetry/correlation_context/propagation.rb +0 -57
  29. data/lib/opentelemetry/correlation_context/propagation/context_keys.rb +0 -27
  30. data/lib/opentelemetry/correlation_context/propagation/text_injector.rb +0 -55
  31. data/lib/opentelemetry/internal.rb +0 -22
  32. data/lib/opentelemetry/trace/event.rb +0 -46
  33. data/lib/opentelemetry/trace/propagation/context_keys.rb +0 -35
@@ -18,7 +18,7 @@ module OpenTelemetry
18
18
  # Returns the {SpanContext} for this link
19
19
  #
20
20
  # @return [SpanContext]
21
- attr_reader :context
21
+ attr_reader :span_context
22
22
 
23
23
  # Returns the frozen attributes for this link.
24
24
  #
@@ -33,13 +33,13 @@ module OpenTelemetry
33
33
  # frozen during Link initialization.
34
34
  # @return [Link]
35
35
  def initialize(span_context, attributes = nil)
36
- @context = span_context
36
+ @span_context = span_context
37
37
  @attributes = attributes.freeze || EMPTY_ATTRIBUTES
38
38
  end
39
39
 
40
40
  # Returns true if two {Link}s are equal.
41
41
  def ==(other)
42
- other.context == @context && other.attributes == @attributes
42
+ other.span_context == @span_context && other.attributes == @attributes
43
43
  end
44
44
  end
45
45
  end
@@ -4,7 +4,6 @@
4
4
  #
5
5
  # SPDX-License-Identifier: Apache-2.0
6
6
 
7
- require 'opentelemetry/trace/propagation/context_keys'
8
7
  require 'opentelemetry/trace/propagation/trace_context'
9
8
 
10
9
  module OpenTelemetry
@@ -5,8 +5,8 @@
5
5
  # SPDX-License-Identifier: Apache-2.0
6
6
 
7
7
  require 'opentelemetry/trace/propagation/trace_context/trace_parent'
8
- require 'opentelemetry/trace/propagation/trace_context/text_extractor'
9
- require 'opentelemetry/trace/propagation/trace_context/text_injector'
8
+ require 'opentelemetry/trace/propagation/trace_context/text_map_extractor'
9
+ require 'opentelemetry/trace/propagation/trace_context/text_map_injector'
10
10
 
11
11
  module OpenTelemetry
12
12
  module Trace
@@ -16,30 +16,30 @@ module OpenTelemetry
16
16
  module TraceContext
17
17
  extend self
18
18
 
19
- TEXT_EXTRACTOR = TextExtractor.new
20
- TEXT_INJECTOR = TextInjector.new
21
- RACK_EXTRACTOR = TextExtractor.new(
19
+ TEXT_MAP_EXTRACTOR = TextMapExtractor.new
20
+ TEXT_MAP_INJECTOR = TextMapInjector.new
21
+ RACK_EXTRACTOR = TextMapExtractor.new(
22
22
  traceparent_key: 'HTTP_TRACEPARENT',
23
23
  tracestate_key: 'HTTP_TRACESTATE'
24
24
  )
25
- RACK_INJECTOR = TextInjector.new(
25
+ RACK_INJECTOR = TextMapInjector.new(
26
26
  traceparent_key: 'HTTP_TRACEPARENT',
27
27
  tracestate_key: 'HTTP_TRACESTATE'
28
28
  )
29
29
 
30
- private_constant :TEXT_INJECTOR, :TEXT_EXTRACTOR,
30
+ private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR,
31
31
  :RACK_INJECTOR, :RACK_EXTRACTOR
32
32
 
33
33
  # Returns an extractor that extracts context using the W3C Trace Context
34
34
  # format
35
- def text_extractor
36
- TEXT_EXTRACTOR
35
+ def text_map_extractor
36
+ TEXT_MAP_EXTRACTOR
37
37
  end
38
38
 
39
39
  # Returns an injector that injects context using the W3C Trace Context
40
40
  # format
41
- def text_injector
42
- TEXT_INJECTOR
41
+ def text_map_injector
42
+ TEXT_MAP_INJECTOR
43
43
  end
44
44
 
45
45
  # Returns an extractor that extracts context using the W3C Trace Context
@@ -8,15 +8,15 @@ module OpenTelemetry
8
8
  module Propagation
9
9
  module TraceContext
10
10
  # Extracts context from carriers in the W3C Trace Context format
11
- class TextExtractor
11
+ class TextMapExtractor
12
12
  include Context::Propagation::DefaultGetter
13
13
 
14
- # Returns a new TextExtractor that extracts context using the
14
+ # Returns a new TextMapExtractor that extracts context using the
15
15
  # specified header keys
16
16
  #
17
17
  # @param [String] traceparent_key The traceparent header key used in the carrier
18
18
  # @param [String] tracestate_key The tracestate header key used in the carrier
19
- # @return [TextExtractor]
19
+ # @return [TextMapExtractor]
20
20
  def initialize(traceparent_key: 'traceparent',
21
21
  tracestate_key: 'tracestate')
22
22
  @traceparent_key = traceparent_key
@@ -47,7 +47,8 @@ module OpenTelemetry
47
47
  trace_flags: tp.flags,
48
48
  tracestate: tracestate,
49
49
  remote: true)
50
- context.set_value(ContextKeys.extracted_span_context_key, span_context)
50
+ span = Trace::Span.new(span_context: span_context)
51
+ OpenTelemetry::Trace.context_with_span(span)
51
52
  rescue OpenTelemetry::Error
52
53
  context
53
54
  end
@@ -8,15 +8,15 @@ module OpenTelemetry
8
8
  module Propagation
9
9
  module TraceContext
10
10
  # Injects context into carriers using the W3C Trace Context format
11
- class TextInjector
11
+ class TextMapInjector
12
12
  include Context::Propagation::DefaultSetter
13
13
 
14
- # Returns a new TextInjector that injects context using the
14
+ # Returns a new TextMapInjector that injects context using the
15
15
  # specified header keys
16
16
  #
17
17
  # @param [String] traceparent_key The traceparent header key used in the carrier
18
18
  # @param [String] tracestate_key The tracestate header key used in the carrier
19
- # @return [TextInjector]
19
+ # @return [TextMapInjector]
20
20
  def initialize(traceparent_key: 'traceparent',
21
21
  tracestate_key: 'tracestate')
22
22
  @traceparent_key = traceparent_key
@@ -36,7 +36,7 @@ module OpenTelemetry
36
36
  return carrier unless (span_context = span_context_from(context))
37
37
 
38
38
  setter ||= DEFAULT_SETTER
39
- setter.call(carrier, @traceparent_key, TraceParent.from_context(span_context).to_s)
39
+ setter.call(carrier, @traceparent_key, TraceParent.from_span_context(span_context).to_s)
40
40
  setter.call(carrier, @tracestate_key, span_context.tracestate) unless span_context.tracestate.nil?
41
41
 
42
42
  carrier
@@ -45,8 +45,7 @@ module OpenTelemetry
45
45
  private
46
46
 
47
47
  def span_context_from(context)
48
- context[ContextKeys.current_span_key]&.context ||
49
- context[ContextKeys.extracted_span_context_key]
48
+ OpenTelemetry::Trace.current_span(context).context
50
49
  end
51
50
  end
52
51
  end
@@ -25,15 +25,15 @@ module OpenTelemetry
25
25
  REGEXP = /^(?<version>[A-Fa-f0-9]{2})-(?<trace_id>[A-Fa-f0-9]{32})-(?<span_id>[A-Fa-f0-9]{16})-(?<flags>[A-Fa-f0-9]{2})(?<ignored>-.*)?$/.freeze
26
26
  private_constant :REGEXP
27
27
 
28
- INVALID_TRACE_ID = OpenTelemetry::Trace::INVALID_TRACE_ID.unpack1('H*')
29
- INVALID_SPAN_ID = OpenTelemetry::Trace::INVALID_SPAN_ID.unpack1('H*')
28
+ INVALID_TRACE_ID = OpenTelemetry::Trace::SpanContext::INVALID.hex_trace_id
29
+ INVALID_SPAN_ID = OpenTelemetry::Trace::SpanContext::INVALID.hex_span_id
30
30
  private_constant :INVALID_TRACE_ID, :INVALID_SPAN_ID
31
31
 
32
32
  class << self
33
33
  # Creates a new {TraceParent} from a supplied {Trace::SpanContext}
34
- # @param [SpanContext] ctx The context
34
+ # @param [SpanContext] ctx The span context
35
35
  # @return [TraceParent] a trace parent
36
- def from_context(ctx)
36
+ def from_span_context(ctx)
37
37
  new(trace_id: ctx.trace_id, span_id: ctx.span_id, flags: ctx.trace_flags)
38
38
  end
39
39
 
@@ -50,7 +50,7 @@ module OpenTelemetry
50
50
  # meanings.
51
51
  #
52
52
  # @param [String] key
53
- # @param [String, Boolean, Numeric] value
53
+ # @param [String, Boolean, Numeric, Array<String, Numeric, Boolean>] value
54
54
  #
55
55
  # @return [self] returns itself
56
56
  def set_attribute(key, value)
@@ -58,44 +58,36 @@ module OpenTelemetry
58
58
  end
59
59
  alias []= set_attribute
60
60
 
61
- # Add an Event to a {Span}. This can be accomplished eagerly or lazily.
62
- # Lazy evaluation is useful when the event attributes are expensive to
63
- # build and where the cost can be avoided for an unsampled {Span}.
61
+ # Add an event to a {Span}.
64
62
  #
65
- # Eager example:
63
+ # Example:
66
64
  #
67
- # span.add_event(name: 'event', attributes: {'eager' => true})
68
- #
69
- # Lazy example:
70
- #
71
- # span.add_event { tracer.create_event(name: 'event', attributes: {'eager' => false}) }
65
+ # span.add_event('event', attributes: {'eager' => true})
72
66
  #
73
67
  # Note that the OpenTelemetry project
74
68
  # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md
75
69
  # documents} certain "standard event names and keys" which have
76
70
  # prescribed semantic meanings.
77
71
  #
78
- # @param [optional String] name Optional name of the event. This is
79
- # required if a block is not given.
72
+ # @param [String] name Name of the event.
80
73
  # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
81
74
  # attributes One or more key:value pairs, where the keys must be
82
75
  # strings and the values may be (array of) string, boolean or numeric
83
- # type. This argument should only be used when passing in a name.
76
+ # type.
84
77
  # @param [optional Time] timestamp Optional timestamp for the event.
85
- # This argument should only be used when passing in a name.
86
78
  #
87
79
  # @return [self] returns itself
88
- def add_event(name: nil, attributes: nil, timestamp: nil)
80
+ def add_event(name, attributes: nil, timestamp: nil)
89
81
  self
90
82
  end
91
83
 
92
- # Record an error during the execution of this span. Multiple errors
84
+ # Record an exception during the execution of this span. Multiple exceptions
93
85
  # can be recorded on a span.
94
86
  #
95
- # @param [Exception] error The error to recorded
87
+ # @param [Exception] exception The exception to recorded
96
88
  #
97
89
  # @return [void]
98
- def record_error(error); end
90
+ def record_exception(exception); end
99
91
 
100
92
  # Sets the Status to the Span
101
93
  #
@@ -11,7 +11,7 @@ module OpenTelemetry
11
11
  # {TraceFlags}, a system-specific tracestate, and a boolean indicating that the SpanContext was
12
12
  # extracted from the wire.
13
13
  class SpanContext
14
- attr_reader :trace_id, :span_id, :trace_flags, :tracestate
14
+ attr_reader :trace_flags, :tracestate
15
15
 
16
16
  # Returns a new {SpanContext}.
17
17
  #
@@ -35,6 +35,30 @@ module OpenTelemetry
35
35
  @remote = remote
36
36
  end
37
37
 
38
+ # Returns the lowercase [hex encoded](https://tools.ietf.org/html/rfc4648#section-8) trace ID.
39
+ #
40
+ # @return [String] A 32-hex-character lowercase string.
41
+ def hex_trace_id
42
+ @trace_id.unpack1('H*')
43
+ end
44
+
45
+ # Returns the lowercase [hex encoded](https://tools.ietf.org/html/rfc4648#section-8) span ID.
46
+ #
47
+ # @return [String] A 16-hex-character lowercase string.
48
+ def hex_span_id
49
+ @span_id.unpack1('H*')
50
+ end
51
+
52
+ # Returns the binary representation of the trace ID.
53
+ #
54
+ # @return [String] A 16-byte binary string.
55
+ attr_reader :trace_id
56
+
57
+ # Returns the binary representation of the span ID.
58
+ #
59
+ # @return [String] An 8-byte binary string.
60
+ attr_reader :span_id
61
+
38
62
  # Returns true if the {SpanContext} has a non-zero trace ID and non-zero span ID.
39
63
  #
40
64
  # @return [Boolean]
@@ -9,15 +9,15 @@ require 'opentelemetry/trace/util/http_to_status'
9
9
  module OpenTelemetry
10
10
  module Trace
11
11
  # Status represents the status of a finished {Span}. It is composed of a
12
- # canonical code in conjunction with an optional descriptive message.
12
+ # status code in conjunction with an optional descriptive message.
13
13
  class Status
14
14
  # Convenience utility, not in API spec:
15
15
  extend Util::HttpToStatus
16
16
 
17
- # Retrieve the canonical code of this Status.
17
+ # Retrieve the status code of this Status.
18
18
  #
19
19
  # @return [Integer]
20
- attr_reader :canonical_code
20
+ attr_reader :code
21
21
 
22
22
  # Retrieve the description of this Status.
23
23
  #
@@ -26,10 +26,10 @@ module OpenTelemetry
26
26
 
27
27
  # Initialize a Status.
28
28
  #
29
- # @param [Integer] canonical_code One of the standard gRPC codes: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
29
+ # @param [Integer] code One of the status codes below
30
30
  # @param [String] description
31
- def initialize(canonical_code, description: '')
32
- @canonical_code = canonical_code
31
+ def initialize(code, description: '')
32
+ @code = code
33
33
  @description = description
34
34
  end
35
35
 
@@ -37,78 +37,20 @@ module OpenTelemetry
37
37
  #
38
38
  # @return [Boolean]
39
39
  def ok?
40
- @canonical_code == OK
40
+ @code != ERROR
41
41
  end
42
42
 
43
- # The following represents the canonical set of status codes of a
44
- # finished {Span}, following the standard gRPC codes:
45
- # https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
43
+ # The following represents the set of status codes of a
44
+ # finished {Span}
46
45
 
47
46
  # The operation completed successfully.
48
47
  OK = 0
49
48
 
50
- # The operation was cancelled (typically by the caller).
51
- CANCELLED = 1
49
+ # The default status.
50
+ UNSET = 1
52
51
 
53
- # An unknown error.
54
- UNKNOWN_ERROR = 2
55
-
56
- # Client specified an invalid argument. Note that this differs from
57
- # {FAILED_PRECONDITION}. {INVALID_ARGUMENT} indicates arguments that are
58
- # problematic regardless of the state of the system.
59
- INVALID_ARGUMENT = 3
60
-
61
- # Deadline expired before operation could complete. For operations that
62
- # change the state of the system, this error may be returned even if the
63
- # operation has completed successfully.
64
- DEADLINE_EXCEEDED = 4
65
-
66
- # Some requested entity (e.g., file or directory) was not found.
67
- NOT_FOUND = 5
68
-
69
- # Some entity that we attempted to create (e.g., file or directory)
70
- # already exists.
71
- ALREADY_EXISTS = 6
72
-
73
- # The caller does not have permission to execute the specified operation.
74
- # {PERMISSION_DENIED} must not be used if the caller cannot be identified
75
- # (use {UNAUTHENTICATED} instead for those errors).
76
- PERMISSION_DENIED = 7
77
-
78
- # Some resource has been exhausted, perhaps a per-user quota, or perhaps
79
- # the entire file system is out of space.
80
- RESOURCE_EXHAUSTED = 8
81
-
82
- # Operation was rejected because the system is not in a state required
83
- # for the operation's execution.
84
- FAILED_PRECONDITION = 9
85
-
86
- # The operation was aborted, typically due to a concurrency issue like
87
- # sequencer check failures, transaction aborts, etc.
88
- ABORTED = 10
89
-
90
- # Operation was attempted past the valid range. E.g., seeking or reading
91
- # past end of file. Unlike {INVALID_ARGUMENT}, this error indicates a
92
- # problem that may be fixed if the system state changes.
93
- OUT_OF_RANGE = 11
94
-
95
- # Operation is not implemented or not supported/enabled in this service.
96
- UNIMPLEMENTED = 12
97
-
98
- # Internal errors. Means some invariants expected by underlying system
99
- # has been broken.
100
- INTERNAL_ERROR = 13
101
-
102
- # The service is currently unavailable. This is a most likely a transient
103
- # condition and may be corrected by retrying with a backoff.
104
- UNAVAILABLE = 14
105
-
106
- # Unrecoverable data loss or corruption.
107
- DATA_LOSS = 15
108
-
109
- # The request does not have valid authentication credentials for the
110
- # operation.
111
- UNAUTHENTICATED = 16
52
+ # An error.
53
+ ERROR = 2
112
54
  end
113
55
  end
114
56
  end
@@ -8,35 +8,6 @@ module OpenTelemetry
8
8
  module Trace
9
9
  # No-op implementation of Tracer.
10
10
  class Tracer
11
- EXTRACTED_SPAN_CONTEXT_KEY = Propagation::ContextKeys.extracted_span_context_key
12
- CURRENT_SPAN_KEY = Propagation::ContextKeys.current_span_key
13
-
14
- private_constant :EXTRACTED_SPAN_CONTEXT_KEY, :CURRENT_SPAN_KEY
15
-
16
- # Returns the current span from the current or provided context
17
- #
18
- # @param [optional Context] context The context to lookup the current
19
- # {Span} from. Defaults to Context.current
20
- def current_span(context = Context.current)
21
- context.value(CURRENT_SPAN_KEY) || Span::INVALID
22
- end
23
-
24
- # Returns the the active span context from the given {Context}, or current
25
- # if one is not explicitly passed in. The active span context may refer to
26
- # a {SpanContext} that has been extracted. If both a current {Span} and an
27
- # extracted, {SpanContext} exist, the context of the current {Span} will be
28
- # returned.
29
- #
30
- # @param [optional Context] context The context to lookup the active
31
- # {SpanContext} from.
32
- #
33
- def active_span_context(context = nil)
34
- context ||= Context.current
35
- context.value(CURRENT_SPAN_KEY)&.context ||
36
- context.value(EXTRACTED_SPAN_CONTEXT_KEY) ||
37
- SpanContext::INVALID
38
- end
39
-
40
11
  # This is a helper for the default use-case of extending the current trace with a span.
41
12
  #
42
13
  # With this helper:
@@ -45,34 +16,24 @@ module OpenTelemetry
45
16
  #
46
17
  # Equivalent without helper:
47
18
  #
48
- # OpenTelemetry.tracer.with_span(OpenTelemetry.tracer.start_span('do-the-thing')) do ... end
19
+ # OpenTelemetry::Trace.with_span(tracer.start_span('do-the-thing')) do ... end
49
20
  #
50
21
  # On exit, the Span that was active before calling this method will be reactivated. If an
51
22
  # exception occurs during the execution of the provided block, it will be recorded on the
52
23
  # span and reraised.
53
24
  # @yield [span, context] yields the newly created span and a context containing the
54
25
  # span to the block.
55
- def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, with_parent: nil, with_parent_context: nil)
56
- span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, with_parent: with_parent, with_parent_context: with_parent_context)
57
- with_span(span) { |s, c| yield s, c }
26
+ def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, with_parent: nil)
27
+ span = nil
28
+ span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, with_parent: with_parent)
29
+ Trace.with_span(span) { |s, c| yield s, c }
58
30
  rescue Exception => e # rubocop:disable Lint/RescueException
59
- span.record_error(e)
60
- span.status = Status.new(Status::UNKNOWN_ERROR,
61
- description: "Unhandled exception of type: #{e.class}")
31
+ span&.record_exception(e)
32
+ span&.status = Status.new(Status::ERROR,
33
+ description: "Unhandled exception of type: #{e.class}")
62
34
  raise e
63
35
  ensure
64
- span.finish
65
- end
66
-
67
- # Activates/deactivates the Span within the current Context, which makes the "current span"
68
- # available implicitly.
69
- #
70
- # On exit, the Span that was active before calling this method will be reactivated.
71
- #
72
- # @param [Span] span the span to activate
73
- # @yield [span, context] yields span and a context containing the span to the block.
74
- def with_span(span)
75
- Context.with_value(CURRENT_SPAN_KEY, span) { |c, s| yield s, c }
36
+ span&.finish
76
37
  end
77
38
 
78
39
  def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
@@ -84,14 +45,12 @@ module OpenTelemetry
84
45
  #
85
46
  # Parent context can be either passed explicitly, or inferred from currently activated span.
86
47
  #
87
- # @param [optional Span] with_parent Explicitly managed parent Span, overrides
88
- # +with_parent_context+.
89
- # @param [optional Context] with_parent_context Explicitly managed. Overridden by
90
- # +with_parent+.
48
+ # @param [optional Context] with_parent Explicitly managed parent context
91
49
  #
92
50
  # @return [Span]
93
- def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
94
- span_context = with_parent&.context || active_span_context(with_parent_context)
51
+ def start_span(name, with_parent: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
52
+ span_context = OpenTelemetry::Trace.current_span(with_parent).context
53
+
95
54
  if span_context.valid?
96
55
  Span.new(span_context: span_context)
97
56
  else