Module: KubeMQ::Telemetry

Defined in:
lib/kubemq/telemetry/otel.rb,
lib/kubemq/telemetry/semconv.rb

Overview

OpenTelemetry integration for distributed tracing of KubeMQ operations.

Provides a thin wrapper around the OpenTelemetry API that degrades gracefully when the SDK is not loaded. Attribute names follow the SemanticConventions module.

See Also:

Defined Under Namespace

Modules: SemanticConventions

Constant Summary collapse

TRACER_NAME =

OpenTelemetry tracer name registered for this SDK.

'kubemq-ruby'

Class Method Summary collapse

Class Method Details

.otel_available? ⇒ Boolean

Returns whether the OpenTelemetry API is loaded and configured.

Returns:

  • (Boolean) —

    true if OpenTelemetry.tracer_provider is available



21
22
23
 
# File 'lib/kubemq/telemetry/otel.rb', line 21

def self.otel_available?
  defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:tracer_provider)
end

.with_span(name, kind: SemanticConventions::SPAN_KIND_CLIENT, attributes: {}) {|span| ... } ⇒ Object

Runs block inside an OpenTelemetry span when the API is loaded; otherwise yields nil once.

Always sets messaging.system to KubeMQ::Telemetry::SemanticConventions::MESSAGING_SYSTEM. Additional attributes are merged and their keys are coerced to strings.

Parameters:

  • name (String) —

    descriptive span name (e.g., "kubemq send_event orders")

  • kind (Symbol) (defaults to: SemanticConventions::SPAN_KIND_CLIENT) —

    OpenTelemetry span kind -- :producer, :consumer, or :client (default: KubeMQ::Telemetry::SemanticConventions::SPAN_KIND_CLIENT)

  • attributes (Hash{String, Symbol => String, Numeric, Boolean}) (defaults to: {}) —

    extra span attributes

Yields:

  • (span) —

    the block to execute inside the span

Yield Parameters:

  • span (OpenTelemetry::Trace::Span, nil) —

    the active span, or nil when OpenTelemetry is not available

Returns:

  • (Object) —

    the return value of the block

Raises:

  • (ArgumentError) —

    if no block is given



41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/kubemq/telemetry/otel.rb', line 41

def self.with_span(name, kind: SemanticConventions::SPAN_KIND_CLIENT, attributes: {}, &block)
  raise ArgumentError, 'block required' unless block

  return block.call(nil) unless otel_available?

  merged = {
    SemanticConventions::ATTR_MESSAGING_SYSTEM => SemanticConventions::MESSAGING_SYSTEM
  }.merge(stringify_attributes(attributes))

  tracer = OpenTelemetry.tracer_provider.tracer(TRACER_NAME)
  tracer.in_span(name, attributes: merged, kind: kind, &block)
end