Module: GEPA::Telemetry

Extended by:
T::Sig
Defined in:
lib/gepa/telemetry.rb

Overview

Telemetry helpers for the GEPA optimizer.

The helpers wrap DSPy context spans and structured logs so that the GEPA port can attach observability data consistently across the optimization lifecycle. They mirror the phases from the Python sequence diagrams:

  • ‘gepa.optimize` (API entry)

  • ‘gepa.state.initialize`

  • ‘gepa.engine.run` / `gepa.engine.iteration`

  • ‘gepa.proposer.*` (selection, evaluation, reflection, acceptance)

Later phases of the port can depend on these helpers without reimplementing span naming or default attributes.

Defined Under Namespace

Classes: Context

Constant Summary collapse

DEFAULT_ATTRIBUTES = 
T.let({
  optimizer: 'GEPA',
  'gepa.instrumentation_version': 'phase0',
  'langfuse.observation.type': 'span'
}.freeze, T::Hash[Symbol, T.untyped])

Class Method Summary collapse

Class Method Details

.build_context(additional_attributes = {}) ⇒ Object 



70
71
72
73
74
75
 
# File 'lib/gepa/telemetry.rb', line 70

def self.build_context(additional_attributes = {})
  attributes = DEFAULT_ATTRIBUTES.merge(symbolize(additional_attributes.dup))
  run_id = attributes.delete(:run_id) || SecureRandom.uuid

  Context.new(run_id: run_id, attributes: attributes)
end

.emit(event_name, attributes = {}) ⇒ Object 



97
98
99
100
 
# File 'lib/gepa/telemetry.rb', line 97

def self.emit(event_name, attributes = {})
  payload = DEFAULT_ATTRIBUTES.merge(symbolize(attributes))
  DSPy.log("gepa.#{event_name}", **payload)
end

.with_span(operation, attributes = {}, &block) ⇒ Object 



84
85
86
87
88
89
 
# File 'lib/gepa/telemetry.rb', line 84

def self.with_span(operation, attributes = {}, &block)
  operation_name = normalize_operation(operation)
  span_attributes = DEFAULT_ATTRIBUTES.merge(symbolize(attributes))

  DSPy::Context.with_span(operation: operation_name, **span_attributes, &block)
end