actionable-otel 1.0.0.pre1
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 +7 -0
- data/CHANGELOG.md +13 -0
- data/LICENSE.txt +21 -0
- data/README.md +132 -0
- data/lib/actionable/otel/version.rb +9 -0
- data/lib/actionable/otel.rb +221 -0
- data/sig/actionable-otel.rbs +69 -0
- metadata +84 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 3ba054ac1dee08074b1e32982f265b8f678656fc2d28c1bb10e46e7433fca7c4
|
|
4
|
+
data.tar.gz: 1aa8c0f7ce31fd5b7b0825aca193282dfb3897cd8bc40ecb7fe2d76d06bbc145
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 8b8e65808c5e00daf733e512a443e8a8e66c7c1fe20bd1e765a7fe108b49f1826690ef149748ba14e2e332858c600bc623d52a613a75f6a763892bf4631de22f
|
|
7
|
+
data.tar.gz: 5d1dc0b2fe7bb940f63202c0768f469a7b6593d4a93fff1378c9c93bfead2acc4d9a8c6c0036402d308a843b5c54d314006ccc8b97dc0fa3526dd20647c1c62f
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [Unreleased]
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- The tracing hooks `trace_run`, `trace_step`, `tracer` and `label_for` are marked `@api private` in their YARD
|
|
8
|
+
comments: the prepended module calls them, and they aren't part of the public API.
|
|
9
|
+
|
|
10
|
+
## 1.0.0.pre1
|
|
11
|
+
|
|
12
|
+
- First release: OpenTelemetry spans for actionable-rb. One span per `Action.run`, a child span per executed step and hook,
|
|
13
|
+
`actionable.outcome` and `actionable.code` attributes, declared failures marked as errors, and never an input or output value.
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Adrian Madrid
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# actionable-otel
|
|
2
|
+
|
|
3
|
+
OpenTelemetry tracing for [actionable-rb](../../gems/actionable). One span per `.run`, a child span per executed step
|
|
4
|
+
and hook, the outcome and result code as attributes, and declared failures marked as errors. It never records an input
|
|
5
|
+
or output value.
|
|
6
|
+
|
|
7
|
+
Requiring it turns tracing on. The core gem never loads OpenTelemetry. The gem depends on `opentelemetry-api` only: the
|
|
8
|
+
SDK and the exporter are your application's choice.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```ruby
|
|
13
|
+
gem 'actionable-otel'
|
|
14
|
+
gem 'opentelemetry-sdk'
|
|
15
|
+
gem 'opentelemetry-exporter-otlp'
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```ruby
|
|
19
|
+
require 'opentelemetry/sdk'
|
|
20
|
+
require 'actionable/otel'
|
|
21
|
+
OpenTelemetry::SDK.configure { |c| c.service_name = "apiary" }
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## What a run looks like
|
|
25
|
+
|
|
26
|
+
```ruby run
|
|
27
|
+
require 'opentelemetry/sdk'
|
|
28
|
+
require 'actionable/otel'
|
|
29
|
+
|
|
30
|
+
exporter = OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter.new
|
|
31
|
+
OpenTelemetry::SDK.configure do |c|
|
|
32
|
+
c.add_span_processor(OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(exporter))
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
class HiveInspection < Actionable::Action
|
|
36
|
+
fails :queen_missing
|
|
37
|
+
|
|
38
|
+
step :open_hive
|
|
39
|
+
step :count_frames
|
|
40
|
+
on_success :file_report
|
|
41
|
+
on_failure :reseal_hive
|
|
42
|
+
always :stamp_log
|
|
43
|
+
|
|
44
|
+
private
|
|
45
|
+
|
|
46
|
+
def open_hive = @opened = true
|
|
47
|
+
def count_frames = fail!(:queen_missing)
|
|
48
|
+
def file_report = @filed = true
|
|
49
|
+
def reseal_hive = @resealed = true
|
|
50
|
+
def stamp_log = @stamped = true
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
HiveInspection.run.code # => :queen_missing
|
|
54
|
+
spans = exporter.finished_spans
|
|
55
|
+
spans.map(&:name) # => ["HiveInspection/open_hive", "HiveInspection/count_frames", "HiveInspection/reseal_hive", "HiveInspection/stamp_log", "HiveInspection.run"]
|
|
56
|
+
run = spans.last
|
|
57
|
+
run.attributes['actionable.outcome'] # => "failure"
|
|
58
|
+
run.attributes['actionable.code'] # => "queen_missing"
|
|
59
|
+
run.status.description # => "queen_missing"
|
|
60
|
+
spans[1].attributes['actionable.code'] # => "queen_missing"
|
|
61
|
+
spans[2].attributes['actionable.section'] # => "failure"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The trace of that run:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
HiveInspection.run outcome=failure code=queen_missing status=ERROR(queen_missing)
|
|
68
|
+
HiveInspection/open_hive section=main
|
|
69
|
+
HiveInspection/count_frames section=main code=queen_missing
|
|
70
|
+
HiveInspection/reseal_hive section=failure
|
|
71
|
+
HiveInspection/stamp_log section=always
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
A success has no error status, and its outcome hook (`file_report`) takes the failure hook's place.
|
|
75
|
+
|
|
76
|
+
## Spans and attributes
|
|
77
|
+
|
|
78
|
+
| Span | Name | Attributes |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| run | `<Class>.run` | `actionable.action`, then `actionable.outcome` (`success`, `failure`, `skipped`) and `actionable.code` when the run returns |
|
|
81
|
+
| step or hook | `<Class>/<name>` | `actionable.action`, `actionable.step`, `actionable.step.kind` (`method`, `action`, `case`), `actionable.section` (`main`, `success`, `failure`, `skip`, `always`), and `actionable.code` when the step recorded a result |
|
|
82
|
+
|
|
83
|
+
An anonymous action is labelled `Actionable::Action`. A nested action step is named after the child class, and the
|
|
84
|
+
child's run span nests under it. A case step is one span; the branch it picks runs inside it. Steps skipped by an
|
|
85
|
+
`if:` or `unless:` guard get no span. A skip is not an error; a declared failure is, so error rates include it. Filter
|
|
86
|
+
by `actionable.code` to tell declared failures from exceptions.
|
|
87
|
+
|
|
88
|
+
Spans are emitted whatever the action's `measure` is; sampling is the SDK's job. A run stubbed with the
|
|
89
|
+
`actionable/rspec` stubs emits no span.
|
|
90
|
+
|
|
91
|
+
## Settings
|
|
92
|
+
|
|
93
|
+
Process-wide.
|
|
94
|
+
|
|
95
|
+
```ruby run
|
|
96
|
+
require 'opentelemetry'
|
|
97
|
+
require 'actionable/otel'
|
|
98
|
+
|
|
99
|
+
Actionable::Otel.step_spans? # => true
|
|
100
|
+
Actionable::Otel.step_spans = false # run spans only
|
|
101
|
+
Actionable::Otel.step_spans? # => false
|
|
102
|
+
Actionable::Otel.exception_details # => :type_only
|
|
103
|
+
Actionable::Otel.exception_details = :full
|
|
104
|
+
Actionable::Otel.exception_details # => :full
|
|
105
|
+
begin
|
|
106
|
+
Actionable::Otel.exception_details = :message
|
|
107
|
+
rescue ArgumentError => e
|
|
108
|
+
e.message # => "Actionable::Otel.exception_details must be :type_only or :full, got :message"
|
|
109
|
+
end
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Exceptions
|
|
113
|
+
|
|
114
|
+
An exception that escapes a run is recorded once, on the run span, and re-raised unchanged. By default the event holds
|
|
115
|
+
the exception class only (`exception.type`), because messages and backtraces can hold input values.
|
|
116
|
+
`exception_details = :full` records the message and stacktrace too. A declared failure is a normal result: it records
|
|
117
|
+
no exception event.
|
|
118
|
+
|
|
119
|
+
## What is never recorded
|
|
120
|
+
|
|
121
|
+
Input fields, output fields, messages, error text and metadata. Result codes are recorded as they are, so keep them
|
|
122
|
+
static: `fail!(:"swarmed_#{hive}")` would leak and explode cardinality. Add your own attributes in a step if you need
|
|
123
|
+
them.
|
|
124
|
+
|
|
125
|
+
## Compatibility
|
|
126
|
+
|
|
127
|
+
Ruby 3.3+, `actionable-rb` `>= 2.0.0.pre1, < 3` (the gem wraps `Action.run` and the runner's internal `record` seam, so
|
|
128
|
+
a major release may move it), `opentelemetry-api` `~> 1.7`.
|
|
129
|
+
|
|
130
|
+
## Docs
|
|
131
|
+
|
|
132
|
+
The guide on the docs site, with every example run in CI: https://gliders-rb.github.io/adapters/opentelemetry/
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'opentelemetry'
|
|
4
|
+
require 'actionable'
|
|
5
|
+
require_relative 'otel/version'
|
|
6
|
+
|
|
7
|
+
# The actionable-rb namespace; this gem adds {Otel}.
|
|
8
|
+
module Actionable
|
|
9
|
+
# OpenTelemetry tracing for actionable: a run span per `Action.run`, a step span per executed step and hook.
|
|
10
|
+
# Requiring `actionable/otel` turns it on. Spans carry class, step and section names, outcomes and result
|
|
11
|
+
# codes, never an input or output value.
|
|
12
|
+
module Otel
|
|
13
|
+
# The instrumentation scope name of the tracer.
|
|
14
|
+
# @return [String]
|
|
15
|
+
TRACER_NAME = 'actionable'
|
|
16
|
+
|
|
17
|
+
# The values `exception_details=` accepts.
|
|
18
|
+
# @return [Array<Symbol>]
|
|
19
|
+
EXCEPTION_DETAILS = %i[type_only full].freeze
|
|
20
|
+
|
|
21
|
+
# What a permanent class name looks like: a constant path.
|
|
22
|
+
PERMANENT_NAME = /\A[[:upper:]][[:alnum:]_]*(?:::[[:upper:]][[:alnum:]_]*)*\z/
|
|
23
|
+
private_constant :PERMANENT_NAME
|
|
24
|
+
|
|
25
|
+
@exception_details = :type_only
|
|
26
|
+
@step_spans = true
|
|
27
|
+
@tracer_pair = nil
|
|
28
|
+
@step_cache = ObjectSpace::WeakKeyMap.new
|
|
29
|
+
|
|
30
|
+
# What a step span needs that does not change between runs: its name and the attribute values that are fixed for
|
|
31
|
+
# one (action label, step, section). The SDK keeps and mutates the Hash it is given, so each span gets a copy.
|
|
32
|
+
# +target+ is the label of an action step's class when it was built (nil for other steps).
|
|
33
|
+
StepSpan = Struct.new(:name, :attributes, :target)
|
|
34
|
+
private_constant :StepSpan
|
|
35
|
+
|
|
36
|
+
class << self
|
|
37
|
+
# @return [Symbol] `:type_only` (default) or `:full`
|
|
38
|
+
attr_reader :exception_details
|
|
39
|
+
|
|
40
|
+
# Sets how much of an escaping exception the run span records.
|
|
41
|
+
#
|
|
42
|
+
# @param level [Symbol] `:type_only` or `:full`
|
|
43
|
+
# @return [Symbol]
|
|
44
|
+
# @raise [ArgumentError] for anything else
|
|
45
|
+
def exception_details=(level)
|
|
46
|
+
unless EXCEPTION_DETAILS.include?(level)
|
|
47
|
+
raise ArgumentError,
|
|
48
|
+
"Actionable::Otel.exception_details must be #{EXCEPTION_DETAILS.map(&:inspect).join(' or ')}, got #{level.inspect}"
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
@exception_details = level
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
# @return [Boolean] whether step and hook spans are emitted (default true)
|
|
55
|
+
def step_spans? = @step_spans
|
|
56
|
+
|
|
57
|
+
# Turns step spans on (truthy) or off (`false`/`nil`).
|
|
58
|
+
#
|
|
59
|
+
# @param enabled [Object]
|
|
60
|
+
# @return [Object] the argument
|
|
61
|
+
def step_spans=(enabled)
|
|
62
|
+
@step_spans = enabled ? true : false
|
|
63
|
+
enabled
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# The tracer of the current provider, cached together with that provider as one frozen pair.
|
|
67
|
+
#
|
|
68
|
+
# @return [Object] an OpenTelemetry tracer
|
|
69
|
+
# @api private
|
|
70
|
+
def tracer
|
|
71
|
+
provider = OpenTelemetry.tracer_provider
|
|
72
|
+
pair = @tracer_pair
|
|
73
|
+
return pair[1] if pair && pair[0].equal?(provider)
|
|
74
|
+
|
|
75
|
+
tracer = provider.tracer(TRACER_NAME, VERSION)
|
|
76
|
+
@tracer_pair = [provider, tracer].freeze
|
|
77
|
+
tracer
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
# Runs the block inside the run span of one `Action.run` and annotates the span with the result.
|
|
81
|
+
#
|
|
82
|
+
# @param action [Class] the action class being run
|
|
83
|
+
# @yieldreturn [Actionable::Result] the result of the run
|
|
84
|
+
# @return [Actionable::Result] the block's result, unchanged
|
|
85
|
+
# @api private
|
|
86
|
+
def trace_run(action, &block)
|
|
87
|
+
label = label_for(action)
|
|
88
|
+
name = temporary_name?(action) ? "#{label}.run" : run_name(label)
|
|
89
|
+
tracer.in_span(name, attributes: { 'actionable.action' => label }, kind: :internal,
|
|
90
|
+
record_exception: false) do |span|
|
|
91
|
+
outcome = run_recording(span, &block)
|
|
92
|
+
annotate_run(span, outcome)
|
|
93
|
+
outcome
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
# Runs the block inside the span of one executed step or hook (one call of the runner's `record` seam).
|
|
98
|
+
#
|
|
99
|
+
# @param instance [Actionable::Action] the action instance being run
|
|
100
|
+
# @param section [Symbol] `:main`, `:success`, `:failure`, `:skip` or `:always`
|
|
101
|
+
# @param step [Object] the step object (`name`, `kind`)
|
|
102
|
+
# @yieldreturn [Object] the step's value
|
|
103
|
+
# @return [Object] the block's value
|
|
104
|
+
# @api private
|
|
105
|
+
def trace_step(instance, section, step, &block)
|
|
106
|
+
return yield unless step_spans?
|
|
107
|
+
|
|
108
|
+
label = label_for(instance.class)
|
|
109
|
+
klass = instance.class
|
|
110
|
+
prepared = temporary_name?(klass) ? build_step_span(label, section, step) : step_span(label, section, step)
|
|
111
|
+
tracer.in_span(prepared.name, attributes: prepared.attributes.dup, kind: :internal, record_exception: false) do |span|
|
|
112
|
+
step_recording(instance, span, &block)
|
|
113
|
+
end
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
# The span label of an action class: its name, or `Actionable::Action` when anonymous.
|
|
117
|
+
#
|
|
118
|
+
# @param klass [Class]
|
|
119
|
+
# @return [String]
|
|
120
|
+
# @api private
|
|
121
|
+
def label_for(klass) = klass.name || Actionable::Action.name
|
|
122
|
+
|
|
123
|
+
private
|
|
124
|
+
|
|
125
|
+
# A class whose name is temporary (anonymous, or set with `set_temporary_name`) has no constant behind its
|
|
126
|
+
# name. A temporary name can never be a valid constant path, so one that is not is temporary. OT-B9.
|
|
127
|
+
def temporary_name?(klass)
|
|
128
|
+
name = klass.name
|
|
129
|
+
name.nil? || !name.match?(PERMANENT_NAME)
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
# The run span's name per label; a label is a class name, so the table stays as small as the set of actions.
|
|
133
|
+
def run_name(label)
|
|
134
|
+
(@run_names ||= {})[label] ||= "#{label}.run".freeze
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
# The prepared span of a step in a section, built once per (step, action label, section). The label is part of
|
|
138
|
+
# the key because a subclass shares its parent's steps, and a class can be named after its first run; for the
|
|
139
|
+
# same reason an action step's span is rebuilt when its class's label is no longer the one it was built with.
|
|
140
|
+
def step_span(label, section, step)
|
|
141
|
+
by_label = (@step_cache[step] ||= {}.compare_by_identity)
|
|
142
|
+
by_section = (by_label[label] ||= {})
|
|
143
|
+
prepared = by_section[section]
|
|
144
|
+
return prepared if prepared && (prepared.target.nil? || prepared.target == label_for(step.name))
|
|
145
|
+
|
|
146
|
+
by_section[section] = build_step_span(label, section, step)
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
def build_step_span(label, section, step)
|
|
150
|
+
name = step.name
|
|
151
|
+
target = label_for(name) if name.is_a?(Class)
|
|
152
|
+
step_name = (target || name.to_s).dup.freeze
|
|
153
|
+
attributes = {
|
|
154
|
+
'actionable.action' => label,
|
|
155
|
+
'actionable.step' => step_name,
|
|
156
|
+
'actionable.step.kind' => step.kind.to_s.freeze,
|
|
157
|
+
'actionable.section' => section.to_s.freeze
|
|
158
|
+
}.freeze
|
|
159
|
+
StepSpan.new("#{label}/#{step_name}".freeze, attributes, target)
|
|
160
|
+
end
|
|
161
|
+
|
|
162
|
+
# A halt is a throw, so the code is set from an ensure: a halting step still carries its code.
|
|
163
|
+
def step_recording(instance, span)
|
|
164
|
+
seen = instance.result
|
|
165
|
+
yield
|
|
166
|
+
ensure
|
|
167
|
+
current = instance.result
|
|
168
|
+
changed = !current.equal?(seen) && current.is_a?(Actionable::Result)
|
|
169
|
+
span.set_attribute('actionable.code', current.code.to_s) if changed
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
def run_recording(span)
|
|
173
|
+
yield
|
|
174
|
+
rescue Exception => e # rubocop:disable Lint/RescueException -- recorded, then re-raised unchanged
|
|
175
|
+
record_error(span, e)
|
|
176
|
+
raise
|
|
177
|
+
end
|
|
178
|
+
|
|
179
|
+
def record_error(span, error)
|
|
180
|
+
return span.record_exception(error) if @exception_details == :full
|
|
181
|
+
|
|
182
|
+
type = error.class.name || error.class.to_s
|
|
183
|
+
span.add_event('exception', attributes: { 'exception.type' => type })
|
|
184
|
+
end
|
|
185
|
+
|
|
186
|
+
def annotate_run(span, result)
|
|
187
|
+
code = result.code.to_s
|
|
188
|
+
span.set_attribute('actionable.outcome', result.status.to_s)
|
|
189
|
+
span.set_attribute('actionable.code', code)
|
|
190
|
+
return unless result.failure?
|
|
191
|
+
|
|
192
|
+
span.status = OpenTelemetry::Trace::Status.error(code)
|
|
193
|
+
end
|
|
194
|
+
end
|
|
195
|
+
|
|
196
|
+
# Prepended onto `Actionable::Action`'s singleton class: wraps `.run` in the run span.
|
|
197
|
+
module ActionRun
|
|
198
|
+
# @param args [Array<Object>] positional run arguments, forwarded verbatim
|
|
199
|
+
# @param kwargs [Object] keyword run arguments, forwarded verbatim
|
|
200
|
+
# @return [Actionable::Result]
|
|
201
|
+
def run(*args, **kwargs)
|
|
202
|
+
Otel.trace_run(self) { super(*args, **kwargs) }
|
|
203
|
+
end
|
|
204
|
+
end
|
|
205
|
+
|
|
206
|
+
# Prepended onto `Actionable::Runner`: wraps its private `record(section, step)` seam in the step span.
|
|
207
|
+
module RunnerSteps
|
|
208
|
+
private
|
|
209
|
+
|
|
210
|
+
# @param section [Symbol]
|
|
211
|
+
# @param step [Object]
|
|
212
|
+
# @return [Object] the block's value
|
|
213
|
+
def record(section, step, &inner)
|
|
214
|
+
Otel.trace_step(@instance, section, step) { super(section, step, &inner) }
|
|
215
|
+
end
|
|
216
|
+
end
|
|
217
|
+
|
|
218
|
+
Actionable::Action.singleton_class.send(:prepend, ActionRun)
|
|
219
|
+
Actionable::Runner.send(:prepend, RunnerSteps) # rubocop:disable Lint/SendWithMixinArgument -- plain prepend makes YARD list a bogus mixin
|
|
220
|
+
end
|
|
221
|
+
end
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# The actionable-rb namespace; this gem adds {Otel}.
|
|
2
|
+
module Actionable
|
|
3
|
+
# OpenTelemetry tracing for actionable: a run span per `Action.run`, a step span per executed step and hook.
|
|
4
|
+
# Requiring `actionable/otel` turns it on. Spans carry class, step and section names, outcomes and result
|
|
5
|
+
# codes, never an input or output value.
|
|
6
|
+
module Otel
|
|
7
|
+
TRACER_NAME: String
|
|
8
|
+
EXCEPTION_DETAILS: ::Array[Symbol]
|
|
9
|
+
VERSION: String
|
|
10
|
+
|
|
11
|
+
# _@return_ — whether step and hook spans are emitted (default true)
|
|
12
|
+
def self.step_spans?: () -> bool
|
|
13
|
+
|
|
14
|
+
# Turns step spans on (truthy) or off (`false`/`nil`).
|
|
15
|
+
#
|
|
16
|
+
# _@param_ `enabled`
|
|
17
|
+
#
|
|
18
|
+
# _@return_ — the argument
|
|
19
|
+
def self.step_spans=: (Object enabled) -> Object
|
|
20
|
+
|
|
21
|
+
# The tracer of the current provider, cached together with that provider as one frozen pair.
|
|
22
|
+
#
|
|
23
|
+
# _@return_ — an OpenTelemetry tracer
|
|
24
|
+
def self.tracer: () -> Object
|
|
25
|
+
|
|
26
|
+
# Runs the block inside the run span of one `Action.run` and annotates the span with the result.
|
|
27
|
+
#
|
|
28
|
+
# _@param_ `action` — the action class being run
|
|
29
|
+
#
|
|
30
|
+
# _@return_ — the block's result, unchanged
|
|
31
|
+
def self.trace_run: (Class action) ?{ () -> Actionable::Result } -> Actionable::Result
|
|
32
|
+
|
|
33
|
+
# Runs the block inside the span of one executed step or hook (one call of the runner's `record` seam).
|
|
34
|
+
#
|
|
35
|
+
# _@param_ `instance` — the action instance being run
|
|
36
|
+
#
|
|
37
|
+
# _@param_ `section` — `:main`, `:success`, `:failure`, `:skip` or `:always`
|
|
38
|
+
#
|
|
39
|
+
# _@param_ `step` — the step object (`name`, `kind`)
|
|
40
|
+
#
|
|
41
|
+
# _@return_ — the block's value
|
|
42
|
+
def self.trace_step: (Actionable::Action _instance, Symbol section, Object step) ?{ () -> Object } -> Object
|
|
43
|
+
|
|
44
|
+
# The span label of an action class: its name, or `Actionable::Action` when anonymous.
|
|
45
|
+
#
|
|
46
|
+
# _@param_ `klass`
|
|
47
|
+
def self.label_for: (Class klass) -> String
|
|
48
|
+
|
|
49
|
+
# _@return_ — `:type_only` (default) or `:full`
|
|
50
|
+
def self.exception_details: () -> Symbol
|
|
51
|
+
|
|
52
|
+
# Sets how much of an escaping exception the run span records.
|
|
53
|
+
#
|
|
54
|
+
# _@param_ `level` — `:type_only` or `:full`
|
|
55
|
+
def self.exception_details=: (Symbol value) -> Symbol
|
|
56
|
+
|
|
57
|
+
# Prepended onto `Actionable::Action`'s singleton class: wraps `.run` in the run span.
|
|
58
|
+
module ActionRun
|
|
59
|
+
# _@param_ `args` — positional run arguments, forwarded verbatim
|
|
60
|
+
#
|
|
61
|
+
# _@param_ `kwargs` — keyword run arguments, forwarded verbatim
|
|
62
|
+
def run: (*::Array[Object] args, **Object kwargs) -> Actionable::Result
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
# Prepended onto `Actionable::Runner`: wraps its private `record(section, step)` seam in the step span.
|
|
66
|
+
module RunnerSteps
|
|
67
|
+
end
|
|
68
|
+
end
|
|
69
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: actionable-otel
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 1.0.0.pre1
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Adrian Madrid
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: actionable-rb
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - ">="
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: 2.0.0.pre1
|
|
19
|
+
- - "<"
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: '3'
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - ">="
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: 2.0.0.pre1
|
|
29
|
+
- - "<"
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: '3'
|
|
32
|
+
- !ruby/object:Gem::Dependency
|
|
33
|
+
name: opentelemetry-api
|
|
34
|
+
requirement: !ruby/object:Gem::Requirement
|
|
35
|
+
requirements:
|
|
36
|
+
- - "~>"
|
|
37
|
+
- !ruby/object:Gem::Version
|
|
38
|
+
version: '1.7'
|
|
39
|
+
type: :runtime
|
|
40
|
+
prerelease: false
|
|
41
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
42
|
+
requirements:
|
|
43
|
+
- - "~>"
|
|
44
|
+
- !ruby/object:Gem::Version
|
|
45
|
+
version: '1.7'
|
|
46
|
+
description: One span per Action.run, a child span per executed step and hook, the
|
|
47
|
+
outcome and result code as attributes, and never an input or output value.
|
|
48
|
+
email:
|
|
49
|
+
- adrian.madrid@timeworxs.com
|
|
50
|
+
executables: []
|
|
51
|
+
extensions: []
|
|
52
|
+
extra_rdoc_files: []
|
|
53
|
+
files:
|
|
54
|
+
- CHANGELOG.md
|
|
55
|
+
- LICENSE.txt
|
|
56
|
+
- README.md
|
|
57
|
+
- lib/actionable/otel.rb
|
|
58
|
+
- lib/actionable/otel/version.rb
|
|
59
|
+
- sig/actionable-otel.rbs
|
|
60
|
+
homepage: https://github.com/gliders-rb/gems
|
|
61
|
+
licenses:
|
|
62
|
+
- MIT
|
|
63
|
+
metadata:
|
|
64
|
+
source_code_uri: https://github.com/gliders-rb/gems/tree/main/adapters/actionable-otel
|
|
65
|
+
changelog_uri: https://github.com/gliders-rb/gems/blob/main/adapters/actionable-otel/CHANGELOG.md
|
|
66
|
+
rubygems_mfa_required: 'true'
|
|
67
|
+
rdoc_options: []
|
|
68
|
+
require_paths:
|
|
69
|
+
- lib
|
|
70
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
71
|
+
requirements:
|
|
72
|
+
- - ">="
|
|
73
|
+
- !ruby/object:Gem::Version
|
|
74
|
+
version: '3.3'
|
|
75
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
76
|
+
requirements:
|
|
77
|
+
- - ">="
|
|
78
|
+
- !ruby/object:Gem::Version
|
|
79
|
+
version: '0'
|
|
80
|
+
requirements: []
|
|
81
|
+
rubygems_version: 3.6.9
|
|
82
|
+
specification_version: 4
|
|
83
|
+
summary: OpenTelemetry tracing for actionable-rb actions.
|
|
84
|
+
test_files: []
|