Module: ActiveMatrix::Telemetry

Defined in:
lib/active_matrix/telemetry.rb

Overview

OpenTelemetry integration for ActiveMatrix

Provides distributed tracing for:

  • Agent lifecycle (connect, disconnect, error)

  • Message handling

  • Room operations

  • Matrix API calls

Examples:

Enable with OTLP exporter

ENV['OTEL_TRACES_EXPORTER'] = 'otlp'
ENV['OTEL_SERVICE_NAME'] = 'activematrix'
ActiveMatrix::Telemetry.configure!

Enable with console exporter for debugging

ActiveMatrix::Telemetry.configure!(exporter: :console)

Defined Under Namespace

Classes: NullSpan, NullTracer

Constant Summary collapse

TRACER_NAME = 
'activematrix'
TRACER_VERSION = 
ActiveMatrix::VERSION

Class Method Summary collapse

Class Method Details

.available? ⇒ Boolean

Returns whether OpenTelemetry is available.

Returns:

  • (Boolean) —

    whether OpenTelemetry is available



26
27
28
29
30
31
32
33
 
# File 'lib/active_matrix/telemetry.rb', line 26

def available?
  @available ||= begin
    require 'opentelemetry/sdk'
    true
  rescue LoadError
    false
  end
end

.configure!(exporter: nil, service_name: 'activematrix') ⇒ Object

Configure OpenTelemetry SDK for ActiveMatrix

Parameters:

  • exporter (Symbol, nil) (defaults to: nil) —

    :console, :otlp, or nil for env-based config

  • service_name (String) (defaults to: 'activematrix') —

    service name for traces



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/active_matrix/telemetry.rb', line 44

def configure!(exporter: nil, service_name: 'activematrix')
  return false unless available?
  return true if configured?

  require 'opentelemetry/sdk'

  case exporter
  when :console
    require 'opentelemetry/sdk'
    OpenTelemetry::SDK.configure do |c|
      c.service_name = service_name
      c.add_span_processor(
        OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
          OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
        )
      )
    end
  when :otlp
    require 'opentelemetry/exporter/otlp'
    ENV['OTEL_SERVICE_NAME'] ||= service_name
    OpenTelemetry::SDK.configure
  else
    # Use environment variables
    ENV['OTEL_SERVICE_NAME'] ||= service_name
    OpenTelemetry::SDK.configure
  end

  @configured = true
end

.configured? ⇒ Boolean

Returns whether telemetry has been configured.

Returns:

  • (Boolean) —

    whether telemetry has been configured



36
37
38
 
# File 'lib/active_matrix/telemetry.rb', line 36

def configured?
  @configured ||= false
end

.record_exception(exception, attributes: {}) ⇒ Object

Record an exception on the current span

Parameters:

  • exception (Exception)
  • attributes (Hash) (defaults to: {}) —

    additional attributes



98
99
100
101
102
103
104
 
# File 'lib/active_matrix/telemetry.rb', line 98

def record_exception(exception, attributes: {})
  return unless configured?

  span = OpenTelemetry::Trace.current_span
  span.record_exception(exception, attributes: attributes)
  span.status = OpenTelemetry::Trace::Status.error(exception.message)
end

.shutdown ⇒ Object

Shutdown the tracer provider



107
108
109
110
111
112
 
# File 'lib/active_matrix/telemetry.rb', line 107

def shutdown
  return unless configured?

  OpenTelemetry.tracer_provider.shutdown
  @configured = false
end

.trace(name, attributes: {}, kind: :internal) {|span| ... } ⇒ Object

Trace a block of code

Parameters:

  • name (String) —

    span name

  • attributes (Hash) (defaults to: {}) —

    span attributes

Yields:

  • (span) —

    the current span



88
89
90
91
92
 
# File 'lib/active_matrix/telemetry.rb', line 88

def trace(name, attributes: {}, kind: :internal, &)
  return yield(NullSpan.instance) unless configured?

  tracer.in_span(name, attributes: attributes, kind: kind, &)
end

.tracer ⇒ OpenTelemetry::Trace::Tracer, NullTracer

Get the ActiveMatrix tracer

Returns:



77
78
79
80
81
 
# File 'lib/active_matrix/telemetry.rb', line 77

def tracer
  return NullTracer.instance unless configured?

  OpenTelemetry.tracer_provider.tracer(TRACER_NAME, TRACER_VERSION)
end