Module: TIMEx::Telemetry

Extended by:
Telemetry
Included in:
Telemetry
Defined in:
lib/timex/telemetry.rb,
lib/timex/telemetry/adapters.rb

Overview

Lightweight instrumentation facade for strategies, composers, and internal events (deadline skew, cancellation observer errors, etc.).

Resolution order for #adapter: explicit #adapter= assignment, then Configuration#telemetry_adapter, then Adapters::Null.

See Also:

Defined Under Namespace

Modules: Adapters

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#strict ⇒ Boolean

When true, adapter errors propagate instead of being swallowed by #instrument / #emit.

Returns:

  • (Boolean) 


40
41
42
 
# File 'lib/timex/telemetry.rb', line 40

def strict
  @strict
end

Instance Method Details

#adapter ⇒ #emit, ...

Resolves the active adapter on each access so runtime config changes apply.

Returns:

  • (#emit, #start, #finish) —

    concrete adapter instance



23
24
25
26
27
 
# File 'lib/timex/telemetry.rb', line 23

def adapter
  return @adapter if @adapter

  TIMEx.config.telemetry_adapter || (@null_adapter ||= Adapters::Null.new)
end

#adapter=(value) ⇒ #emit, ...

Forces a specific adapter (overrides Configuration#telemetry_adapter until cleared).

Parameters:

  • value (#emit, #start, #finish, nil)

Returns:

  • (#emit, #start, #finish, nil) 


33
34
35
 
# File 'lib/timex/telemetry.rb', line 33

def adapter=(value)
  @adapter = value
end

#emit(event:, **payload) ⇒ void

This method returns an undefined value.

Emits a one-shot event (no span pairing).

Parameters:

  • event (Symbol, String) —

    logical event name

  • payload (Hash{Symbol => Object}) —

    structured attributes



63
64
65
66
67
68
 
# File 'lib/timex/telemetry.rb', line 63

def emit(event:, **payload)
  a = adapter
  return if a.is_a?(Adapters::Null)

  safely { a.emit(event:, payload:) }
end

#instrument(event:, **base_payload) {|payload| ... } ⇒ Object

Note:

Mutates base_payload in place to avoid per-call dup on the hot path.

Wraps a block with start / finish callbacks and elapsed timing in payload.

Parameters:

  • event (Symbol, String) —

    logical event name

  • base_payload (Hash{Symbol => Object}) —

    initial payload (mutated; see @note)

Yield Parameters:

  • payload (Hash{Symbol => Object}) —

    same object passed to the adapter

Returns:

  • (Object) —

    the block’s return value



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/timex/telemetry.rb', line 78

def instrument(event:, **base_payload)
  a = adapter
  return yield(base_payload) if a.is_a?(Adapters::Null)

  # `base_payload` is a fresh hash from the kwarg splat at the call site;
  # the caller can't observe our mutations, so we skip the defensive dup
  # to save an allocation per instrumented call.
  payload = base_payload
  started_ns = Clock.monotonic_ns
  safely { a.start(event:, payload:) }
  begin
    result = yield(payload)
    payload[:outcome] ||= :ok
    result
  rescue StandardError, Expired => e
    payload[:outcome] ||= e.is_a?(Expired) ? :timeout : :error
    payload[:error_class] = e.class.name unless e.is_a?(Expired)
    raise
  end
ensure
  if started_ns
    payload[:elapsed_ms] = (Clock.monotonic_ns - started_ns) / 1_000_000.0
    safely { a.finish(event:, payload:) }
  end
end

#null_adapter? ⇒ Boolean

Note:

Lets hot paths skip kwarg-heavy instrumentation when telemetry is disabled.

Returns true when the resolved adapter is TIMEx::Telemetry::Adapters::Null.

Returns:



54
55
56
 
# File 'lib/timex/telemetry.rb', line 54

def null_adapter?
  adapter.is_a?(Adapters::Null)
end

#reset! ⇒ void

This method returns an undefined value.

Clears memoized adapter state and resets #strict to false.



45
46
47
48
49
 
# File 'lib/timex/telemetry.rb', line 45

def reset!
  @adapter = nil
  @null_adapter = nil
  @strict = false
end