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

Inherits:
Object
  • Object
show all
Defined in:
lib/mongo/tracing/open_telemetry/tracer.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

OpenTelemetry tracer for MongoDB operations and commands.

API:

  • private

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(enabled: nil, query_text_max_length: nil, otel_tracer: nil) ⇒ Tracer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initializes a new OpenTelemetry tracer.

Parameters:

  • (defaults to: nil)

    whether OpenTelemetry is enabled or not. Defaults to nil, which means it will check the environment variable OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED (values: true/1/yes). If the environment variable is not set, OpenTelemetry will be disabled by default.

  • (defaults to: nil)

    maximum length for captured query text. Defaults to nil, which means it will check the environment variable OTEL_RUBY_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH. If the environment variable is not set, the query text will not be captured.

  • (defaults to: nil)

    the OpenTelemetry tracer implementation to use. Defaults to nil, which means it will use the default tracer from OpenTelemetry’s tracer provider.

API:

  • private



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/mongo/tracing/open_telemetry/tracer.rb', line 42

def initialize(enabled: nil, query_text_max_length: nil, otel_tracer: nil)
  @enabled = if enabled.nil?
               %w[true 1 yes].include?(ENV['OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED']&.downcase)
             else
               enabled
             end
  check_opentelemetry_loaded
  @query_text_max_length = if query_text_max_length.nil?
                             ENV['OTEL_RUBY_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH'].to_i
                           else
                             query_text_max_length
                           end
  @otel_tracer = otel_tracer || initialize_tracer
  @operation_tracer = OperationTracer.new(@otel_tracer, self)
  @command_tracer = CommandTracer.new(@otel_tracer, self, query_text_max_length: @query_text_max_length)
end

Instance Attribute Details

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the OpenTelemetry tracer implementation used to create spans for MongoDB operations and commands.

Returns:

  • the OpenTelemetry tracer implementation used to create spans for MongoDB operations and commands.

API:

  • private



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

def otel_tracer
  @otel_tracer
end

Instance Method Details

#cursor_context_map ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • map of cursor IDs to OpenTelemetry contexts.

API:

  • private



145
146
147
 
# 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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • the session associated with the cursor.

  • the cursor ID.

Returns:

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

API:

  • private



155
156
157
158
159
 
# 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

#enabled? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Whether OpenTelemetry is enabled or not.

Returns:

  • true if OpenTelemetry is enabled, false otherwise.

API:

  • private



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

def enabled?
  @enabled
end

#finish_transaction_span(session) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Finish a transaction span and deactivate its context.

Parameters:

  • The session finishing the transaction.

API:

  • private



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# 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

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Determines the parent 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:

  • the operation context.

  • the cursor ID, if applicable.

Returns:

  • parent context or nil.

API:

  • private



170
171
172
173
174
175
176
177
 
# 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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Start a transaction span and activate its context.

Parameters:

  • The session starting the transaction.

API:

  • private



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# 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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Trace a MongoDB command.

Parameters:

  • The MongoDB command message to trace.

  • The context of the operation.

  • The connection used to send the command

Yields:

  • The block representing the command to be traced.

Returns:

  • The result of the command.

API:

  • private



86
87
88
89
90
 
# 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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Trace a MongoDB operation.

Parameters:

  • The MongoDB operation to trace.

  • The context of the operation.

  • (defaults to: nil)

    An optional name for the operation.

Yields:

  • The block representing the operation to be traced.

Returns:

  • The result of the operation.

API:

  • private



73
74
75
76
77
 
# 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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the transaction context map for tracking active transaction contexts.

Returns:

  • map of transaction keys to OpenTelemetry contexts.

API:

  • private



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

def transaction_context_map
  @transaction_context_map ||= {}
end

#transaction_map_key(session) ⇒ String | nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Generates a unique key for transaction tracking.

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

Parameters:

  • the session.

Returns:

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

API:

  • private



207
208
209
210
211
 
# 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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the transaction span map for tracking active transaction spans.

Returns:

  • map of transaction keys to OpenTelemetry spans.

API:

  • private



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

def transaction_span_map
  @transaction_span_map ||= {}
end

#transaction_token_map ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the transaction token map for tracking context attachment tokens.

Returns:

  • map of transaction keys to OpenTelemetry context tokens.

API:

  • private



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

def transaction_token_map
  @transaction_token_map ||= {}
end