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.

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:

  • enabled (Boolean | nil) (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.

  • query_text_max_length (Integer | nil) (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.

  • otel_tracer (OpenTelemetry::Trace::Tracer | nil) (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.



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:

  • (OpenTelemetry::Trace::Tracer) —

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



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:

  • (Hash) —

    map of cursor IDs to OpenTelemetry contexts.



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:

  • 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.



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:

  • (Boolean) —

    true if OpenTelemetry is enabled, false otherwise.



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:



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:

  • operation_context (Mongo::Operation::Context) —

    the operation context.

  • cursor_id (Integer) —

    the cursor ID, if applicable.

Returns:

  • (OpenTelemetry::Context | nil) —

    parent context or nil.



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:



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:

Yields:

  • The block representing the command to be traced.

Returns:

  • (Object) —

    The result of the command.



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:

  • operation (Mongo::Operation) —

    The MongoDB operation to trace.

  • operation_context (Mongo::Operation::Context) —

    The context of the operation.

  • op_name (String, nil) (defaults to: nil) —

    An optional name for the operation.

Yields:

  • The block representing the operation to be traced.

Returns:

  • (Object) —

    The result of the operation.



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:

  • (Hash) —

    map of transaction keys to OpenTelemetry contexts.



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:

Returns:

  • (String | nil) —

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



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:

  • (Hash) —

    map of transaction keys to OpenTelemetry spans.



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:

  • (Hash) —

    map of transaction keys to OpenTelemetry context tokens.



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

def transaction_token_map
  @transaction_token_map ||= {}
end