Class: Mongo::Tracing::OpenTelemetry::Tracer Private

Do not use. This class is for internal use only.

Relationships & Source Files
Inherits:	Object
Defined in:	lib/mongo/tracing/open_telemetry/tracer.rb

Overview

::Mongo::Tracing::OpenTelemetry tracer for MongoDB operations and commands.

Class Method Summary

.new(enabled: nil, query_text_max_length: nil, otel_tracer: nil) ⇒ Tracer constructor Internal use only

Initializes a new ::Mongo::Tracing::OpenTelemetry tracer.

Instance Attribute Summary

#enabled? ⇒ Boolean readonly Internal use only

Whether OpenTelemetry is enabled or not.
#otel_tracer ⇒ OpenTelemetry::Trace::Tracer readonly Internal use only

Instance Method Summary

#cursor_context_map ⇒ Hash Internal use only

Returns the cursor context map for tracking cursor-related ::Mongo::Tracing::OpenTelemetry contexts.
#cursor_map_key(session, cursor_id) ⇒ String | nil Internal use only

Generates a unique key for cursor tracking in the context map.
#finish_transaction_span(session) Internal use only

Finish a transaction span and deactivate its context.
#parent_context_for(operation_context, cursor_id) ⇒ OpenTelemetry::Context | nil Internal use only

Determines the parent ::Mongo::Tracing::OpenTelemetry context for an operation.
#start_transaction_span(session) Internal use only

Start a transaction span and activate its context.
#trace_command(message, operation_context, connection) { ... } ⇒ Object Internal use only

Trace a MongoDB command.
#trace_operation(operation, operation_context, op_name: nil) { ... } ⇒ Object Internal use only

Trace a MongoDB operation.
#transaction_context_map ⇒ Hash Internal use only

Returns the transaction context map for tracking active transaction contexts.
#transaction_map_key(session) ⇒ String | nil Internal use only

Generates a unique key for transaction tracking.
#transaction_span_map ⇒ Hash Internal use only

Returns the transaction span map for tracking active transaction spans.
#transaction_token_map ⇒ Hash Internal use only

Returns the transaction token map for tracking context attachment tokens.
#check_opentelemetry_loaded private Internal use only
#initialize_tracer private Internal use only

Instance Attribute Details

#enabled? ⇒ `Boolean` (readonly)

Whether OpenTelemetry is enabled or not.

Returns:

(Boolean) —

true if ::Mongo::Tracing::OpenTelemetry is enabled, false otherwise.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 62


def enabled?
  @enabled
end

#otel_tracer ⇒ `OpenTelemetry::Trace::Tracer` (readonly)

Returns:

(OpenTelemetry::Trace::Tracer) —

the ::Mongo::Tracing::OpenTelemetry tracer implementation used to create spans for MongoDB operations and commands.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 27


attr_reader :otel_tracer

Instance Method Details

#check_opentelemetry_loaded (private)

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 215


def check_opentelemetry_loaded
  return unless @enabled
  return if defined?(::OpenTelemetry)

  Logger.logger.warn('OpenTelemetry tracing for MongoDB is enabled, ' \
                     'but the OpenTelemetry library is not loaded. ' \
                     'Disabling tracing.')
  @enabled = false
end

#cursor_context_map ⇒ `Hash`

Returns the cursor context map for tracking cursor-related ::Mongo::Tracing::OpenTelemetry contexts.

Returns:

(Hash) —

map of cursor IDs to ::Mongo::Tracing::OpenTelemetry contexts.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 145


def cursor_context_map
  @cursor_context_map ||= {}
end

#cursor_map_key(session, cursor_id) ⇒ `String` | `nil`

Generates a unique key for cursor tracking in the context map.

Parameters:

session (Mongo::Session) —

the session associated with the cursor.
cursor_id (Integer) —

the cursor ID.

Returns:

(String | nil) —

unique key combining session ID and cursor ID, or nil if either is nil.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 155


def cursor_map_key(session, cursor_id)
  return if cursor_id.nil? || session.nil?

  "#{session.session_id['id'].to_uuid}-#{cursor_id}"
end

#finish_transaction_span(session)

Finish a transaction span and deactivate its context.

Parameters:

session (Mongo::Session) —

The session finishing the transaction.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 123


def finish_transaction_span(session)
  return unless enabled?

  key = transaction_map_key(session)
  return unless key

  span = transaction_span_map.delete(key)
  token = transaction_token_map.delete(key)
  transaction_context_map.delete(key)

  return unless span && token

  begin
    span.finish
  ensure
    ::OpenTelemetry::Context.detach(token)
  end
end

#initialize_tracer (private)

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 225


def initialize_tracer
  return unless enabled?

  ::OpenTelemetry.tracer_provider.tracer(
    'mongo-ruby-driver',
    Mongo::VERSION
  )
end

#parent_context_for(operation_context, cursor_id) ⇒ `OpenTelemetry::Context` | `nil`

Determines the parent ::Mongo::Tracing::OpenTelemetry context for an operation.

Returns the transaction context if the operation is part of a transaction, otherwise returns nil. Cursor-based context nesting is not currently implemented.

Parameters:

operation_context (Mongo::Operation::Context) —

the operation context.
cursor_id (Integer) —

the cursor ID, if applicable.

Returns:

(OpenTelemetry::Context | nil) —

parent context or nil.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 170


def parent_context_for(operation_context, cursor_id)
  if (key = transaction_map_key(operation_context.session))
    transaction_context_map[key]
  elsif (_key = cursor_map_key(operation_context.session, cursor_id))
    # We return nil here unless we decide how to nest cursor operations.
    nil
  end
end

#start_transaction_span(session)

Start a transaction span and activate its context.

Parameters:

session (Mongo::Session) —

The session starting the transaction.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 95


def start_transaction_span(session)
  return unless enabled?

  key = transaction_map_key(session)
  return unless key

  # Create the transaction span with minimal attributes
  span = @otel_tracer.start_span(
    'transaction',
    attributes: { 'db.system' => 'mongodb' },
    kind: :client
  )

  # Create a context containing this span
  context = ::OpenTelemetry::Trace.context_with_span(span)

  # Activate the context and store the token for later detachment
  token = ::OpenTelemetry::Context.attach(context)

  # Store span, token, and context for later retrieval
  transaction_span_map[key] = span
  transaction_token_map[key] = token
  transaction_context_map[key] = context
end

#trace_command(message, operation_context, connection) { ... } ⇒ `Object`

Trace a MongoDB command.

Parameters:

message (Mongo::Protocol::Message) —

The MongoDB command message to trace.
operation_context (Mongo::Operation::Context) —

The context of the operation.
connection (Mongo::Server::Connection) —

The connection used to send the command

Yields:

The block representing the command to be traced.

Returns:

(Object) —

The result of the command.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 86


def trace_command(message, operation_context, connection, &block)
  return yield unless enabled?

  @command_tracer.trace_command(message, operation_context, connection, &block)
end

#trace_operation(operation, operation_context, op_name: nil) { ... } ⇒ `Object`

Trace a MongoDB operation.

Parameters:

operation (Mongo::Operation) —

The MongoDB operation to trace.
operation_context (Mongo::Operation::Context) —

The context of the operation.
op_name (String, nil) —

An optional name for the operation.

Yields:

The block representing the operation to be traced.

Returns:

(Object) —

The result of the operation.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 73


def trace_operation(operation, operation_context, op_name: nil, &block)
  return yield unless enabled?

  @operation_tracer.trace_operation(operation, operation_context, op_name: op_name, &block)
end

#transaction_context_map ⇒ `Hash`

Returns the transaction context map for tracking active transaction contexts.

Returns:

(Hash) —

map of transaction keys to ::Mongo::Tracing::OpenTelemetry contexts.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 182


def transaction_context_map
  @transaction_context_map ||= {}
end

#transaction_map_key(session) ⇒ `String` | `nil`

Generates a unique key for transaction tracking.

Returns nil for implicit sessions or sessions not in a transaction.

Parameters:

session (Mongo::Session) —

the session.

Returns:

(String | nil) —

unique key combining session ID and transaction number, or nil.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 207


def transaction_map_key(session)
  return if session.nil? || session.implicit? || !session.in_transaction?

  "#{session.session_id['id'].to_uuid}-#{session.txn_num}"
end

#transaction_span_map ⇒ `Hash`

Returns the transaction span map for tracking active transaction spans.

Returns:

(Hash) —

map of transaction keys to ::Mongo::Tracing::OpenTelemetry spans.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 189


def transaction_span_map
  @transaction_span_map ||= {}
end

#transaction_token_map ⇒ `Hash`

Returns the transaction token map for tracking context attachment tokens.

Returns:

(Hash) —

map of transaction keys to ::Mongo::Tracing::OpenTelemetry context tokens.

[ GitHub ]

# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 196


def transaction_token_map
  @transaction_token_map ||= {}
end

Class: Mongo::Tracing::OpenTelemetry::Tracer Private

Overview

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#enabled? ⇒ Boolean (readonly)

#otel_tracer ⇒ OpenTelemetry::Trace::Tracer (readonly)

Instance Method Details

#check_opentelemetry_loaded (private)

#cursor_context_map ⇒ Hash

#cursor_map_key(session, cursor_id) ⇒ String | nil

#finish_transaction_span(session)

#initialize_tracer (private)

#parent_context_for(operation_context, cursor_id) ⇒ OpenTelemetry::Context | nil

#start_transaction_span(session)

#trace_command(message, operation_context, connection) { ... } ⇒ Object

#trace_operation(operation, operation_context, op_name: nil) { ... } ⇒ Object

#transaction_context_map ⇒ Hash

#transaction_map_key(session) ⇒ String | nil

#transaction_span_map ⇒ Hash

#transaction_token_map ⇒ Hash

#enabled? ⇒ `Boolean` (readonly)

#otel_tracer ⇒ `OpenTelemetry::Trace::Tracer` (readonly)

#cursor_context_map ⇒ `Hash`

#cursor_map_key(session, cursor_id) ⇒ `String` | `nil`

#parent_context_for(operation_context, cursor_id) ⇒ `OpenTelemetry::Context` | `nil`

#trace_command(message, operation_context, connection) { ... } ⇒ `Object`

#trace_operation(operation, operation_context, op_name: nil) { ... } ⇒ `Object`

#transaction_context_map ⇒ `Hash`

#transaction_map_key(session) ⇒ `String` | `nil`

#transaction_span_map ⇒ `Hash`

#transaction_token_map ⇒ `Hash`