opentelemetry-api 0.2.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 +7 -0
  2. data/CHANGELOG.md +1 -0
  3. data/LICENSE +201 -0
  4. data/lib/opentelemetry.rb +43 -0
  5. data/lib/opentelemetry/context.rb +31 -0
  6. data/lib/opentelemetry/distributed_context.rb +19 -0
  7. data/lib/opentelemetry/distributed_context/distributed_context.rb +24 -0
  8. data/lib/opentelemetry/distributed_context/entry.rb +66 -0
  9. data/lib/opentelemetry/distributed_context/manager.rb +12 -0
  10. data/lib/opentelemetry/distributed_context/propagation.rb +19 -0
  11. data/lib/opentelemetry/distributed_context/propagation/binary_format.rb +26 -0
  12. data/lib/opentelemetry/distributed_context/propagation/text_format.rb +76 -0
  13. data/lib/opentelemetry/distributed_context/propagation/trace_parent.rb +124 -0
  14. data/lib/opentelemetry/error.rb +9 -0
  15. data/lib/opentelemetry/internal.rb +22 -0
  16. data/lib/opentelemetry/metrics.rb +16 -0
  17. data/lib/opentelemetry/metrics/handles.rb +54 -0
  18. data/lib/opentelemetry/metrics/instruments.rb +156 -0
  19. data/lib/opentelemetry/metrics/meter.rb +109 -0
  20. data/lib/opentelemetry/metrics/meter_factory.rb +22 -0
  21. data/lib/opentelemetry/trace.rb +53 -0
  22. data/lib/opentelemetry/trace/event.rb +45 -0
  23. data/lib/opentelemetry/trace/link.rb +45 -0
  24. data/lib/opentelemetry/trace/sampling_hint.rb +22 -0
  25. data/lib/opentelemetry/trace/span.rb +137 -0
  26. data/lib/opentelemetry/trace/span_context.rb +56 -0
  27. data/lib/opentelemetry/trace/span_kind.rb +35 -0
  28. data/lib/opentelemetry/trace/status.rb +109 -0
  29. data/lib/opentelemetry/trace/trace_flags.rb +50 -0
  30. data/lib/opentelemetry/trace/tracer.rb +69 -0
  31. data/lib/opentelemetry/trace/tracer_factory.rb +45 -0
  32. data/lib/opentelemetry/version.rb +10 -0
  33. metadata +200 -0
@@ -0,0 +1,109 @@
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 Metrics
9
+ # No-op implementation of Meter.
10
+ class Meter
11
+ NOOP_LABEL_SET = Object.new
12
+ private_constant(:NOOP_LABEL_SET)
13
+
14
+ def record_batch(*measurements, label_set: nil); end
15
+
16
+ # Canonicalizes labels, returning an opaque {LabelSet} object.
17
+ #
18
+ # @param [Hash<String, String>] labels
19
+ # @return [LabelSet]
20
+ def labels(labels)
21
+ NOOP_LABEL_SET
22
+ end
23
+
24
+ # Create and return a floating point gauge.
25
+ #
26
+ # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
27
+ # @param [optional String] description Descriptive text documenting the instrument.
28
+ # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
29
+ # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
30
+ # @param [optional Boolean] monotonic Whether the gauge accepts only monotonic updates. Defaults to false.
31
+ # @return [FloatGauge]
32
+ def create_float_gauge(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: false)
33
+ raise ArgumentError if name.nil?
34
+
35
+ Instruments::FloatGauge.new
36
+ end
37
+
38
+ # Create and return an integer gauge.
39
+ #
40
+ # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
41
+ # @param [optional String] description Descriptive text documenting the instrument.
42
+ # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
43
+ # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
44
+ # @param [optional Boolean] monotonic Whether the gauge accepts only monotonic updates. Defaults to false.
45
+ # @return [IntegerGauge]
46
+ def create_integer_gauge(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: false)
47
+ raise ArgumentError if name.nil?
48
+
49
+ Instruments::IntegerGauge.new
50
+ end
51
+
52
+ # Create and return a floating point counter.
53
+ #
54
+ # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
55
+ # @param [optional String] description Descriptive text documenting the instrument.
56
+ # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
57
+ # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
58
+ # @param [optional Boolean] monotonic Whether the counter accepts only monotonic updates. Defaults to true.
59
+ # @return [FloatCounter]
60
+ def create_float_counter(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: true)
61
+ raise ArgumentError if name.nil?
62
+
63
+ Instruments::FloatCounter.new
64
+ end
65
+
66
+ # Create and return an integer counter.
67
+ #
68
+ # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
69
+ # @param [optional String] description Descriptive text documenting the instrument.
70
+ # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
71
+ # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
72
+ # @param [optional Boolean] monotonic Whether the counter accepts only monotonic updates. Defaults to true.
73
+ # @return [IntegerCounter]
74
+ def create_integer_counter(name, description: nil, unit: nil, recommended_label_keys: nil, monotonic: true)
75
+ raise ArgumentError if name.nil?
76
+
77
+ Instruments::IntegerCounter.new
78
+ end
79
+
80
+ # Create and return a floating point measure.
81
+ #
82
+ # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
83
+ # @param [optional String] description Descriptive text documenting the instrument.
84
+ # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
85
+ # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
86
+ # @param [optional Boolean] absolute Whether the measure accepts only non-negative updates. Defaults to true.
87
+ # @return [FloatMeasure]
88
+ def create_float_measure(name, description: nil, unit: nil, recommended_label_keys: nil, absolute: true)
89
+ raise ArgumentError if name.nil?
90
+
91
+ Instruments::FloatMeasure.new
92
+ end
93
+
94
+ # Create and return an integer measure.
95
+ #
96
+ # @param [String] name Name of the metric. See {Meter} for required metric name syntax.
97
+ # @param [optional String] description Descriptive text documenting the instrument.
98
+ # @param [optional String] unit Unit specified according to http://unitsofmeasure.org/ucum.html.
99
+ # @param [optional Enumerable<String>] recommended_label_keys Recommended grouping keys for this instrument.
100
+ # @param [optional Boolean] absolute Whether the measure accepts only non-negative updates. Defaults to true.
101
+ # @return [IntegerMeasure]
102
+ def create_integer_measure(name, description: nil, unit: nil, recommended_label_keys: nil, absolute: true)
103
+ raise ArgumentError if name.nil?
104
+
105
+ Instruments::IntegerMeasure.new
106
+ end
107
+ end
108
+ end
109
+ end
@@ -0,0 +1,22 @@
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 Metrics
9
+ # No-op implementation of a meter factory.
10
+ class MeterFactory
11
+ # Returns a {Meter} instance.
12
+ #
13
+ # @param [optional String] name Instrumentation package name
14
+ # @param [optional String] version Instrumentation package version
15
+ #
16
+ # @return [Meter]
17
+ def meter(name = nil, version = nil)
18
+ @meter ||= Meter.new
19
+ end
20
+ end
21
+ end
22
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2019 OpenTelemetry Authors
4
+ #
5
+ # SPDX-License-Identifier: Apache-2.0
6
+
7
+ module OpenTelemetry
8
+ # The Trace API allows recording a set of events, triggered as a result of a
9
+ # single logical operation, consolidated across various components of an
10
+ # application.
11
+ module Trace
12
+ # An invalid trace identifier, a 16-byte array with all zero bytes, encoded
13
+ # as a hexadecimal string.
14
+ INVALID_TRACE_ID = ('0' * 32).freeze
15
+
16
+ # An invalid span identifier, an 8-byte array with all zero bytes, encoded
17
+ # as a hexadecimal string.
18
+ INVALID_SPAN_ID = ('0' * 16).freeze
19
+
20
+ # Generates a valid trace identifier, a 16-byte array with at least one
21
+ # non-zero byte, encoded as a hexadecimal string.
22
+ #
23
+ # @return [String] a hexadecimal string encoding of a valid trace ID.
24
+ def self.generate_trace_id
25
+ loop do
26
+ id = Random::DEFAULT.bytes(16).unpack1('H*')
27
+ return id unless id == INVALID_TRACE_ID
28
+ end
29
+ end
30
+
31
+ # Generates a valid span identifier, an 8-byte array with at least one
32
+ # non-zero byte, encoded as a hexadecimal string.
33
+ #
34
+ # @return [String] a hexadecimal string encoding of a valid span ID.
35
+ def self.generate_span_id
36
+ loop do
37
+ id = Random::DEFAULT.bytes(8).unpack1('H*')
38
+ return id unless id == INVALID_SPAN_ID
39
+ end
40
+ end
41
+ end
42
+ end
43
+
44
+ require 'opentelemetry/trace/event'
45
+ require 'opentelemetry/trace/link'
46
+ require 'opentelemetry/trace/trace_flags'
47
+ require 'opentelemetry/trace/span_context'
48
+ require 'opentelemetry/trace/span_kind'
49
+ require 'opentelemetry/trace/span'
50
+ require 'opentelemetry/trace/sampling_hint'
51
+ require 'opentelemetry/trace/status'
52
+ require 'opentelemetry/trace/tracer'
53
+ require 'opentelemetry/trace/tracer_factory'
@@ -0,0 +1,45 @@
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 Trace
9
+ # A text annotation with a set of attributes and a timestamp.
10
+ class Event
11
+ EMPTY_ATTRIBUTES = {}.freeze
12
+
13
+ private_constant :EMPTY_ATTRIBUTES
14
+
15
+ # Returns the name of this event
16
+ #
17
+ # @return [String]
18
+ attr_reader :name
19
+
20
+ # Returns the frozen attributes for this event
21
+ #
22
+ # @return [Hash<String, Object>]
23
+ attr_reader :attributes
24
+
25
+ # Returns the timestamp for this event
26
+ #
27
+ # @return [Time]
28
+ attr_reader :timestamp
29
+
30
+ # Returns a new immutable {Event}.
31
+ #
32
+ # @param [String] name The name of this event
33
+ # @param [optional Hash<String, Object>] attributes A hash of attributes for this
34
+ # event. Attributes will be frozen during Event initialization.
35
+ # @param [optional Time] timestamp The timestamp for this event.
36
+ # Defaults to Time.now.
37
+ # @return [Event]
38
+ def initialize(name:, attributes: nil, timestamp: nil)
39
+ @name = name
40
+ @attributes = attributes.freeze || EMPTY_ATTRIBUTES
41
+ @timestamp = timestamp || Time.now
42
+ end
43
+ end
44
+ end
45
+ end
@@ -0,0 +1,45 @@
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 Trace
9
+ # A link to a {Span}. Used (for example) in batching operations, where a
10
+ # single batch handler processes multiple requests from different traces.
11
+ # A Link can be also used to reference spans from the same trace. A Link
12
+ # and its attributes are immutable.
13
+ class Link
14
+ EMPTY_ATTRIBUTES = {}.freeze
15
+
16
+ private_constant :EMPTY_ATTRIBUTES
17
+
18
+ # Returns the {SpanContext} for this link
19
+ #
20
+ # @return [SpanContext]
21
+ attr_reader :context
22
+
23
+ # Returns the frozen attributes for this link.
24
+ #
25
+ # @return [Hash<String, Object>]
26
+ attr_reader :attributes
27
+
28
+ # Returns a new immutable {Link}.
29
+ #
30
+ # @param [SpanContext] span_context The context of the linked {Span}.
31
+ # @param [optional Hash<String, Object>] attributes A hash of attributes for
32
+ # this link. Attributes will be frozen during Link initialization.
33
+ # @return [Link]
34
+ def initialize(span_context, attributes = nil)
35
+ @context = span_context
36
+ @attributes = attributes.freeze || EMPTY_ATTRIBUTES
37
+ end
38
+
39
+ # Returns true if two {Link}s are equal.
40
+ def ==(other)
41
+ other.context == @context && other.attributes == @attributes
42
+ end
43
+ end
44
+ end
45
+ end
@@ -0,0 +1,22 @@
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 Trace
9
+ # Hints to influence sampling decisions. The default option for span
10
+ # creation is to not provide any suggestion.
11
+ module SamplingHint
12
+ # Suggest to not record events and not sample.
13
+ NOT_RECORD = :__not_record__
14
+
15
+ # Suggest to record events and not sample.
16
+ RECORD = :__record__
17
+
18
+ # Suggest to record events and sample.
19
+ RECORD_AND_SAMPLED = :__record_and_sampled__
20
+ end
21
+ end
22
+ end
@@ -0,0 +1,137 @@
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 Trace
9
+ # Span represents a single operation within a trace. Spans can be nested to
10
+ # form a trace tree. Often, a trace contains a root span that describes the
11
+ # end-to-end latency and, optionally, one or more sub-spans for its
12
+ # sub-operations.
13
+ #
14
+ # Once Span {Tracer#start_span is created} - Span operations can be used to
15
+ # add additional properties to it like attributes, links, events, name and
16
+ # resulting status. Span cannot be used to retrieve these properties. This
17
+ # prevents the mis-use of spans as an in-process information propagation
18
+ # mechanism.
19
+ #
20
+ # {Span} must be ended by calling {#finish}.
21
+ class Span
22
+ # Retrieve the spans SpanContext
23
+ #
24
+ # The returned value may be used even after the Span is finished.
25
+ #
26
+ # @return [SpanContext]
27
+ attr_reader :context
28
+
29
+ # Spans must be created using {Tracer}. This is for internal use only.
30
+ #
31
+ # @api private
32
+ def initialize(span_context: nil)
33
+ @context = span_context || SpanContext.new
34
+ end
35
+
36
+ # Return whether this span is recording.
37
+ #
38
+ # @return [Boolean] true if this Span is active and recording information
39
+ # like events with the #add_event operation and attributes using
40
+ # #set_attribute.
41
+ def recording?
42
+ false
43
+ end
44
+
45
+ # Set attribute
46
+ #
47
+ # Note that the OpenTelemetry project
48
+ # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
49
+ # documents} certain "standard attributes" that have prescribed semantic
50
+ # meanings.
51
+ #
52
+ # @param [String] key
53
+ # @param [String, Boolean, Numeric] value
54
+ #
55
+ # @return [self] returns itself
56
+ def set_attribute(key, value)
57
+ self
58
+ end
59
+ alias []= set_attribute
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}.
64
+ #
65
+ # Eager example:
66
+ #
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}) }
72
+ #
73
+ # Note that the OpenTelemetry project
74
+ # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
75
+ # documents} certain "standard event names and keys" which have
76
+ # prescribed semantic meanings.
77
+ #
78
+ # @param [optional String] name Optional name of the event. This is
79
+ # required if a block is not given.
80
+ # @param [optional Hash<String, Object>] attributes One or more key:value
81
+ # pairs, where the keys must be strings and the values may be string,
82
+ # boolean or numeric type. This argument should only be used when
83
+ # passing in a name.
84
+ # @param [optional Time] timestamp Optional timestamp for the event.
85
+ # This argument should only be used when passing in a name.
86
+ #
87
+ # @return [self] returns itself
88
+ def add_event(name: nil, attributes: nil, timestamp: nil)
89
+ self
90
+ end
91
+
92
+ # Sets the Status to the Span
93
+ #
94
+ # If used, this will override the default Span status. Default is OK.
95
+ #
96
+ # Only the value of the last call will be recorded, and implementations
97
+ # are free to ignore previous calls.
98
+ #
99
+ # @param [Status] status The new status, which overrides the default Span
100
+ # status, which is OK.
101
+ #
102
+ # @return [void]
103
+ def status=(status); end
104
+
105
+ # Updates the Span name
106
+ #
107
+ # Upon this update, any sampling behavior based on Span name will depend
108
+ # on the implementation.
109
+ #
110
+ # @param [String] new_name The new operation name, which supersedes
111
+ # whatever was passed in when the Span was started
112
+ #
113
+ # @return [void]
114
+ def name=(new_name); end
115
+
116
+ # Finishes the Span
117
+ #
118
+ # Implementations MUST ignore all subsequent calls to {#finish} (there
119
+ # might be exceptions when Tracer is streaming event and has no mutable
120
+ # state associated with the Span).
121
+ #
122
+ # Call to {#finish} MUST not have any effects on child spans. Those may
123
+ # still be running and can be ended later.
124
+ #
125
+ # This API MUST be non-blocking.
126
+ #
127
+ # @param [Time] end_timestamp optional end timestamp for the span.
128
+ #
129
+ # @return [self] returns itself
130
+ def finish(end_timestamp: nil)
131
+ self
132
+ end
133
+
134
+ INVALID = new(span_context: SpanContext::INVALID)
135
+ end
136
+ end
137
+ end
@@ -0,0 +1,56 @@
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 Trace
9
+ # A SpanContext contains the state that must propagate to child {Span}s and across process boundaries.
10
+ # It contains the identifiers (a trace ID and span ID) associated with the {Span}, a set of
11
+ # {TraceFlags}, a system-specific tracestate, and a boolean indicating that the SpanContext was
12
+ # extracted from the wire.
13
+ class SpanContext
14
+ attr_reader :trace_id, :span_id, :trace_flags, :tracestate
15
+
16
+ # Returns a new {SpanContext}.
17
+ #
18
+ # @param [optional String] trace_id The trace ID associated with a {Span}.
19
+ # @param [optional String] span_id The span ID associated with a {Span}.
20
+ # @param [optional TraceFlags] trace_flags The trace flags associated with a {Span}.
21
+ # @param [optional String] tracestate The tracestate associated with a {Span}. May be nil.
22
+ # @param [optional Boolean] remote Whether the {SpanContext} was extracted from the wire.
23
+ # @return [SpanContext]
24
+ def initialize(
25
+ trace_id: Trace.generate_trace_id,
26
+ span_id: Trace.generate_span_id,
27
+ trace_flags: TraceFlags::DEFAULT,
28
+ tracestate: nil,
29
+ remote: false
30
+ )
31
+ @trace_id = trace_id
32
+ @span_id = span_id
33
+ @trace_flags = trace_flags
34
+ @tracestate = tracestate
35
+ @remote = remote
36
+ end
37
+
38
+ # Returns true if the {SpanContext} has a non-zero trace ID and non-zero span ID.
39
+ #
40
+ # @return [Boolean]
41
+ def valid?
42
+ @trace_id != INVALID_TRACE_ID && @span_id != INVALID_SPAN_ID
43
+ end
44
+
45
+ # Returns true if the {SpanContext} was propagated from a remote parent.
46
+ #
47
+ # @return [Boolean]
48
+ def remote?
49
+ @remote
50
+ end
51
+
52
+ # Represents an invalid {SpanContext}, with an invalid trace ID and an invalid span ID.
53
+ INVALID = new(trace_id: INVALID_TRACE_ID, span_id: INVALID_SPAN_ID)
54
+ end
55
+ end
56
+ end