Module: Pinot::OpenTelemetry

Defined in:
lib/pinot/open_telemetry.rb

Overview

Opt-in OpenTelemetry bridge.

Setup

Add to an initializer after the opentelemetry SDK is configured:

require "pinot/open_telemetry"
Pinot::OpenTelemetry.install!

What it does

Each call to Connection#execute_sql (and anything built on top of it —execute_sql_with_params, execute_many, PreparedStatement) creates an OTel span named “pinot.query” with attributes following the OpenTelemetry semantic conventions for database spans:

db.system        = "pinot"
db.statement     = "<sql>"        (the full SQL string)
db.name          = "<table>"      (the Pinot table name)
db.operation     = "SELECT"       (first token of the SQL)

On failure the span is marked with error status and the exception is recorded on the span.

Trace-context propagation

When installed, every outbound HTTP request to a broker is injected with W3C Trace Context headers (traceparent / tracestate) so distributed traces flow through Pinot. This relies on OpenTelemetry.propagation being configured (the default SDK sets this up automatically).

Feature flag

The bridge can be toggled at runtime without reinstalling:

Pinot::OpenTelemetry.enabled = false   # pause tracing (e.g. in tests)
Pinot::OpenTelemetry.enabled = true    # resume
Pinot::OpenTelemetry.enabled?          # => true / false

Lifecycle

Pinot::OpenTelemetry.install!    # idempotent
Pinot::OpenTelemetry.installed?  # => true
Pinot::OpenTelemetry.uninstall!  # removes hooks; leaves transport unpatched

Note: this gem does NOT depend on opentelemetry-api or opentelemetry-sdk. Both must be present and initialized before install! is called.

Defined Under Namespace

Modules: TraceContextInjector

Constant Summary collapse

SPAN_NAME = 
"pinot.query".freeze
DB_SYSTEM = 
"pinot".freeze
TRACER_NAME = 
"pinot-client".freeze

Class Method Summary collapse

Class Method Details

.enabled=(val) ⇒ Object

Enable or disable tracing at runtime without uninstalling.



60
61
62
 
# File 'lib/pinot/open_telemetry.rb', line 60

def self.enabled=(val)
  @enabled = val ? true : false
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


64
65
66
 
# File 'lib/pinot/open_telemetry.rb', line 64

def self.enabled?
  @enabled
end

.install! ⇒ Object 



68
69
70
71
72
73
74
 
# File 'lib/pinot/open_telemetry.rb', line 68

def self.install!
  return if installed?

  _install_around_hook
  _patch_transport
  @installed = true
end

.installed? ⇒ Boolean

Returns:

  • (Boolean) 


76
77
78
 
# File 'lib/pinot/open_telemetry.rb', line 76

def self.installed?
  @installed
end

.uninstall! ⇒ Object 



80
81
82
83
84
85
 
# File 'lib/pinot/open_telemetry.rb', line 80

def self.uninstall!
  ::Pinot::Instrumentation.around = nil
  @installed = false
  # NOTE: JsonHttpTransport prepend is permanent once applied (Ruby limitation).
  # Disable the propagator by unsetting the flag — it no-ops when disabled.
end