From a9c55514245fbb9a8dca6bb37cdc393210a095cf Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov <160598371+comandeo-mongo@users.noreply.github.com> Date: Thu, 29 Oct 2026 14:27:43 +0100 Subject: [PATCH] RUBY-3952 Add no more to spans that are not recording Spans the sampler drops are still made current, so that nested spans stay nested and their context is propagated, but the tracers also built every attribute and recorded the outcome on them, all of which the SDK discards. Pass only the cheap attributes the OpenTelemetry spec recommends at creation, set the rest once the span is known to record, and record the outcome only on recording spans. --- .../tracing/open_telemetry/command_tracer.rb | 76 +++++------ .../open_telemetry/operation_tracer.rb | 32 +++-- .../open_telemetry/command_tracer_spec.rb | 124 +++++++++++++++--- .../open_telemetry/operation_tracer_spec.rb | 77 +++++++++-- spec/support/tracing.rb | 6 + 5 files changed, 238 insertions(+), 77 deletions(-) diff --git a/lib/mongo/tracing/open_telemetry/command_tracer.rb b/lib/mongo/tracing/open_telemetry/command_tracer.rb index 4a1fa5e30a..9e32573f0e 100644 --- a/lib/mongo/tracing/open_telemetry/command_tracer.rb +++ b/lib/mongo/tracing/open_telemetry/command_tracer.rb @@ -82,6 +82,9 @@ def trace_command(message, _operation_context, connection, &block) private # Runs the command with the span made current, and finishes the span. + # A span that is not recording is still made current, so that its + # context is propagated, but gets no further attributes and no + # outcome: the SDK would discard them. # # @param span [ OpenTelemetry::Trace::Span ] a span with a valid context. # @param message [ Mongo::Protocol::Message ] the command message. @@ -90,13 +93,15 @@ def trace_command(message, _operation_context, connection, &block) # # rubocop:disable Lint/RescueException def trace_with_span(span, message) - ::OpenTelemetry::Trace.with_span(span) do |s, c| + recording = span.recording? + apply_deferred_attributes(span, message) if recording + ::OpenTelemetry::Trace.with_span(span) do |s, _c| yield.tap do |result| - process_command_result(result, cursor_id(message), c, s) + process_command_result(result, s) if recording end end rescue Exception => e - handle_command_exception(span, e) + handle_command_exception(span, e) if recording raise e ensure span.finish @@ -136,21 +141,17 @@ def create_command_span(message, connection) # Processes the command result and updates span attributes. # # @param result [ Object ] the command result. - # @param cursor_id [ Integer | nil ] the cursor ID. - # @param context [ OpenTelemetry::Context ] the context. # @param span [ OpenTelemetry::Trace::Span ] the current span. - def process_command_result(result, cursor_id, context, span) - process_cursor_context(result, cursor_id, context, span) + def process_command_result(result, span) + process_cursor_context(result, span) maybe_trace_error(result, span) end # Handles exceptions that occur during command execution. # - # @param span [ OpenTelemetry::Trace::Span | nil ] the span. + # @param span [ OpenTelemetry::Trace::Span ] the span. # @param exception [ Exception ] the exception that occurred. def handle_command_exception(span, exception) - return unless span - if exception.is_a?(Mongo::Error::OperationFailure) span.set_attribute('db.response.status_code', exception.code.to_s) end @@ -158,33 +159,41 @@ def handle_command_exception(span, exception) span.status = ::OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{exception.class}") end - # Builds span attributes for the command. + # Builds the attributes passed at span creation: the cheap set the + # OpenTelemetry spec recommends. They are built for every span, + # recorded or not, and are the only ones the sampler sees. The rest + # are set by apply_deferred_attributes once the span is known to + # record. # # @param message [ Mongo::Protocol::Message ] the command message. # @param connection [ Mongo::Server::Connection ] the connection. # # @return [ Hash ] OpenTelemetry span attributes following MongoDB semantic conventions. def span_attributes(message, connection) - base_attributes(message) - .merge(connection_attributes(connection)) - .merge(session_attributes(message)) - .compact + { + 'db.system.name' => 'mongodb', + 'db.namespace' => database(message), + 'db.collection.name' => collection_name(message), + 'db.command.name' => command_name(message) + }.compact.merge(connection_attributes(connection)) end - # Returns base database and command attributes. + # Sets the remaining attributes on a span that is recording. They are + # not visible to the sampler; only custom samplers keying on them are + # affected. # + # @param span [ OpenTelemetry::Trace::Span ] the span. # @param message [ Mongo::Protocol::Message ] the command message. - # - # @return [ Hash ] base span attributes. - def base_attributes(message) + def apply_deferred_attributes(span, message) { - 'db.system.name' => 'mongodb', - 'db.namespace' => database(message), - 'db.collection.name' => collection_name(message), - 'db.command.name' => command_name(message), 'db.query.summary' => query_summary(message), - 'db.query.text' => query_text(message) - } + 'db.query.text' => query_text(message), + 'db.mongodb.cursor_id' => cursor_id(message), + 'db.mongodb.lsid' => lsid(message), + 'db.mongodb.txn_number' => txn_number(message) + }.each do |key, value| + span.set_attribute(key, value) unless value.nil? + end end # Returns connection-related attributes. @@ -202,26 +211,11 @@ def connection_attributes(connection) } end - # Returns session and transaction attributes. - # - # @param message [ Mongo::Protocol::Message ] the command message. - # - # @return [ Hash ] session span attributes. - def session_attributes(message) - { - 'db.mongodb.cursor_id' => cursor_id(message), - 'db.mongodb.lsid' => lsid(message), - 'db.mongodb.txn_number' => txn_number(message) - } - end - # Processes cursor context from the command result. # # @param result [ Object ] the command result. - # @param _cursor_id [ Integer | nil ] the cursor ID (unused). - # @param _context [ OpenTelemetry::Context ] the context (unused). # @param span [ OpenTelemetry::Trace::Span ] the current span. - def process_cursor_context(result, _cursor_id, _context, span) + def process_cursor_context(result, span) cursor_id = normalize_cursor_id(result.cursor_id) return unless cursor_id.positive? diff --git a/lib/mongo/tracing/open_telemetry/operation_tracer.rb b/lib/mongo/tracing/open_telemetry/operation_tracer.rb index be5fb8c9d6..7eef6c2209 100644 --- a/lib/mongo/tracing/open_telemetry/operation_tracer.rb +++ b/lib/mongo/tracing/open_telemetry/operation_tracer.rb @@ -66,6 +66,9 @@ def trace_operation(operation, operation_context, op_name: nil, &block) private # Runs the operation with the span made current, and finishes the span. + # A span that is not recording is still made current, so that the + # command spans created within it nest under it, but gets no further + # attributes and no outcome: the SDK would discard them. # # @param span [ OpenTelemetry::Trace::Span ] a span with a valid context. # @param operation [ Mongo::Operation ] the operation. @@ -74,9 +77,13 @@ def trace_operation(operation, operation_context, op_name: nil, &block) # # rubocop:disable Lint/RescueException def trace_with_span(span, operation, &block) - execute_with_span(span, operation, &block) + recording = span.recording? + if recording && !operation.cursor_id.nil? + span.set_attribute('db.mongodb.cursor_id', operation.cursor_id) + end + execute_with_span(span, operation, recording, &block) rescue Exception => e - handle_span_exception(span, e) + handle_span_exception(span, e) if recording raise e ensure span.finish @@ -104,14 +111,15 @@ def create_operation_span(operation, operation_context, op_name) # # @param span [ OpenTelemetry::Trace::Span ] the span. # @param operation [ Mongo::Operation ] the operation. + # @param recording [ true | false ] whether the span is recording. # # @yield the block to execute. # # @return [ Object ] the result of the block. - def execute_with_span(span, operation) + def execute_with_span(span, operation, recording) ::OpenTelemetry::Trace.with_span(span) do |s, c| yield.tap do |result| - process_cursor_context(result, operation.cursor_id, c, s) + process_cursor_context(result, operation.cursor_id, c, s, recording) end end end @@ -121,8 +129,6 @@ def execute_with_span(span, operation) # @param span [ OpenTelemetry::Trace::Span ] the span. # @param exception [ Exception ] the exception. def handle_span_exception(span, exception) - return unless span - span.record_exception(exception) span.status = ::OpenTelemetry::Trace::Status.error( "Unhandled exception of type: #{exception.class}" @@ -139,7 +145,11 @@ def operation_name(operation, op_name = nil) op_name || operation.class.name.split('::').last.downcase end - # Builds span attributes for the operation. + # Builds the attributes passed at span creation. The cursor id is set + # by trace_with_span once the span is known to record. + # db.operation.summary is outside the spec's recommended creation set, + # but it is the span name, which is built anyway, and an attribute + # passed at creation is cheaper than one set later. # # @param operation [ Mongo::Operation ] the operation. # @param op_name [ String | nil ] optional operation name. @@ -151,8 +161,7 @@ def span_attributes(operation, op_name) 'db.namespace' => operation.db_name.to_s, 'db.collection.name' => collection_name(operation), 'db.operation.name' => operation_name(operation, op_name), - 'db.operation.summary' => operation_span_name(operation, op_name), - 'db.mongodb.cursor_id' => operation.cursor_id, + 'db.operation.summary' => operation_span_name(operation, op_name) }.compact end @@ -165,7 +174,8 @@ def span_attributes(operation, op_name) # @param cursor_id [ Integer | nil ] the cursor ID before the operation. # @param context [ OpenTelemetry::Context ] the OpenTelemetry context. # @param span [ OpenTelemetry::Trace::Span ] the current span. - def process_cursor_context(result, cursor_id, context, span) + # @param recording [ true | false ] whether the span is recording. + def process_cursor_context(result, cursor_id, context, span, recording) return unless result.is_a?(Cursor) if result.id.zero? @@ -174,7 +184,7 @@ def process_cursor_context(result, cursor_id, context, span) elsif result.id && cursor_id.nil? # New cursor created, store its context. cursor_context_map[result.id] = context - span.set_attribute('db.mongodb.cursor_id', result.id) + span.set_attribute('db.mongodb.cursor_id', result.id) if recording end end diff --git a/spec/mongo/tracing/open_telemetry/command_tracer_spec.rb b/spec/mongo/tracing/open_telemetry/command_tracer_spec.rb index 9b96d24895..45580e662c 100644 --- a/spec/mongo/tracing/open_telemetry/command_tracer_spec.rb +++ b/spec/mongo/tracing/open_telemetry/command_tracer_spec.rb @@ -67,7 +67,8 @@ describe '#trace_command' do let(:span_context) { instance_double(OpenTelemetry::Trace::SpanContext, valid?: true) } let(:span) do - instance_double(OpenTelemetry::Trace::Span, finish: nil, set_attribute: nil, context: span_context) + instance_double(OpenTelemetry::Trace::Span, finish: nil, set_attribute: nil, recording?: true, + context: span_context) end let(:context) { instance_double(Mongo::Operation::Context) } let(:result) { instance_double(Mongo::Operation::Result, cursor_id: 0, successful?: true) } @@ -77,6 +78,71 @@ allow(OpenTelemetry::Trace).to receive(:with_span).and_yield(span, context) end + it 'passes only the cheap attributes to start_span' do + expect(otel_tracer).to receive(:start_span).with( + 'find', + attributes: hash_excluding('db.query.summary', 'db.query.text', 'db.mongodb.lsid', + 'db.mongodb.cursor_id', 'db.mongodb.txn_number'), + kind: :client + ) + command_tracer.trace_command(message, operation_context, connection) { result } + end + + it 'sets the deferred attributes when the span is recording' do + expect(span).to receive(:set_attribute).with('db.query.summary', 'find test_db.users') + expect(span).to receive(:set_attribute).with('db.mongodb.lsid', lsid_value) + command_tracer.trace_command(message, operation_context, connection) { result } + end + + # A span the sampler dropped is still made current, so that its context + # is propagated and nested spans stay nested, but gets nothing else. + context 'with a span that is not recording' do + let(:span) do + instance_double(OpenTelemetry::Trace::Span, finish: nil, set_attribute: nil, recording?: false, + context: span_context) + end + + it 'does not set the deferred attributes' do + expect(span).not_to receive(:set_attribute) + command_tracer.trace_command(message, operation_context, connection) { result } + end + + it 'still makes the span current' do + expect(OpenTelemetry::Trace).to receive(:with_span).with(span).and_yield(span, context) + command_tracer.trace_command(message, operation_context, connection) { result } + end + + it 'does not record the cursor id from the reply' do + reply = instance_double(Mongo::Operation::Result, cursor_id: 789, successful?: true) + expect(span).not_to receive(:set_attribute) + command_tracer.trace_command(message, operation_context, connection) { reply } + end + + it 'does not record a failed reply' do + error = Mongo::Error::OperationFailure.new('error', nil, code: 42) + reply = instance_double(Mongo::Operation::Result, cursor_id: 0, successful?: false, error: error) + allow(reply).to receive(:validate!).and_raise(error) + expect(span).not_to receive(:set_attribute) + expect(span).not_to receive(:record_exception) + command_tracer.trace_command(message, operation_context, connection) { reply } + end + + it 'does not record a raised exception' do + error = Mongo::Error::OperationFailure.new('error', nil, code: 42) + expect(span).not_to receive(:set_attribute) + expect(span).not_to receive(:record_exception) + expect(span).not_to receive(:status=) + expect do + command_tracer.trace_command(message, operation_context, connection) { raise error } + end.to raise_error(error) + end + + it 'finishes the span' do + expect(span).to receive(:finish) + command_tracer.trace_command(message, operation_context, connection) { result } + end + end + it 'starts a span with the command name' do expect(otel_tracer).to receive(:start_span).with( 'find', @@ -342,8 +408,11 @@ expect(subject['db.command.name']).to eq('find') end - it 'includes db.query.summary' do - expect(subject['db.query.summary']).to eq('find test_db.users') + it 'excludes the attributes deferred until the span is known to record' do + %w[db.query.summary db.query.text db.mongodb.lsid db.mongodb.cursor_id + db.mongodb.txn_number].each do |key| + expect(subject).not_to have_key(key) + end end it 'includes server.port' do @@ -366,14 +435,35 @@ expect(subject['db.mongodb.driver_connection_id']).to eq(123) end - it 'includes db.mongodb.lsid' do - expect(subject['db.mongodb.lsid']).to eq(lsid_value) + context 'with an admin command without a collection' do + let(:document) { { 'serverStatus' => 1, '$db' => 'admin' } } + + it 'omits db.collection.name' do + expect(subject).not_to have_key('db.collection.name') + end end + end + + describe '#apply_deferred_attributes' do + subject(:apply) { command_tracer.send(:apply_deferred_attributes, deferred_span, message) } + + let(:deferred_span) { instance_double(OpenTelemetry::Trace::Span, set_attribute: nil) } - it 'does not include nil values' do - expect(subject).not_to have_key('db.mongodb.cursor_id') - expect(subject).not_to have_key('db.mongodb.txn_number') - expect(subject).not_to have_key('db.query.text') + it 'sets the query summary' do + expect(deferred_span).to receive(:set_attribute).with('db.query.summary', 'find test_db.users') + apply + end + + it 'sets the lsid' do + expect(deferred_span).to receive(:set_attribute).with('db.mongodb.lsid', lsid_value) + apply + end + + it 'skips attributes that are absent from the command' do + %w[db.query.text db.mongodb.cursor_id db.mongodb.txn_number].each do |key| + expect(deferred_span).not_to receive(:set_attribute).with(key, anything) + end + apply end context 'with getMore command' do @@ -385,8 +475,9 @@ } end - it 'includes db.mongodb.cursor_id' do - expect(subject['db.mongodb.cursor_id']).to eq(999) + it 'sets the cursor id' do + expect(deferred_span).to receive(:set_attribute).with('db.mongodb.cursor_id', 999) + apply end end @@ -399,17 +490,18 @@ } end - it 'includes db.mongodb.txn_number' do - expect(subject['db.mongodb.txn_number']).to eq(42) + it 'sets the transaction number' do + expect(deferred_span).to receive(:set_attribute).with('db.mongodb.txn_number', 42) + apply end end context 'with query text enabled' do let(:query_text_max_length) { 1000 } - it 'includes db.query.text' do - expect(subject['db.query.text']).to be_a(String) - expect(subject['db.query.text']).to include('find') + it 'sets the query text' do + expect(deferred_span).to receive(:set_attribute).with('db.query.text', a_string_including('find')) + apply end end end diff --git a/spec/mongo/tracing/open_telemetry/operation_tracer_spec.rb b/spec/mongo/tracing/open_telemetry/operation_tracer_spec.rb index 35e7b0e53a..8b9392ca57 100644 --- a/spec/mongo/tracing/open_telemetry/operation_tracer_spec.rb +++ b/spec/mongo/tracing/open_telemetry/operation_tracer_spec.rb @@ -42,6 +42,7 @@ allow(s).to receive(:record_exception) allow(s).to receive(:status=) allow(s).to receive(:context).and_return(double('SpanContext', valid?: true)) + allow(s).to receive(:recording?).and_return(true) end end let(:context) { double('OpenTelemetry::Context') } @@ -210,12 +211,74 @@ expect(cursor_context_map).not_to have_key(cursor_id) end - it 'does not set cursor_id attribute' do - expect(span).not_to receive(:set_attribute).with('db.mongodb.cursor_id', anything) + it 'sets only the cursor id of the operation itself' do + expect(span).to receive(:set_attribute).with('db.mongodb.cursor_id', 999).once operation_tracer.trace_operation(operation, operation_context) { cursor } end end + it 'passes no cursor id to start_span' do + expect(otel_tracer).to receive(:start_span).with( + anything, + attributes: hash_excluding('db.mongodb.cursor_id'), + with_parent: nil, + kind: :client + ) + operation_tracer.trace_operation(operation, operation_context) { result } + end + + # A span the sampler dropped is still made current, so that the command + # spans created within it nest under it, but gets nothing else. + context 'with a span that is not recording' do + let(:operation_class) { class_double(Mongo::Operation::GetMore, name: 'Mongo::Operation::GetMore') } + let(:operation) do + instance_double( + Mongo::Operation::GetMore, + db_name: 'test_db', + coll_name: 'test_collection', + cursor_id: 12_345, + class: operation_class, + respond_to?: true + ) + end + + before do + allow(span).to receive(:recording?).and_return(false) + end + + it 'does not set the cursor id' do + expect(span).not_to receive(:set_attribute) + operation_tracer.trace_operation(operation, operation_context) { result } + end + + it 'still makes the span current' do + expect(OpenTelemetry::Trace).to receive(:with_span).with(span).and_yield(span, context) + operation_tracer.trace_operation(operation, operation_context) { result } + end + + it 'does not record the cursor id of a new cursor' do + allow(operation).to receive(:cursor_id).and_return(nil) + cursor = instance_double(Mongo::Cursor, id: 777) + allow(cursor).to receive(:is_a?).with(Mongo::Cursor).and_return(true) + expect(span).not_to receive(:set_attribute) + operation_tracer.trace_operation(operation, operation_context) { cursor } + end + + it 'does not record a raised exception' do + error = StandardError.new('test error') + expect(span).not_to receive(:record_exception) + expect(span).not_to receive(:status=) + expect do + operation_tracer.trace_operation(operation, operation_context) { raise error } + end.to raise_error(error) + end + + it 'finishes the span' do + expect(span).to receive(:finish) + operation_tracer.trace_operation(operation, operation_context) { result } + end + end + context 'when an exception is raised' do let(:error) { StandardError.new('test error') } @@ -287,10 +350,6 @@ expect(attributes['db.operation.summary']).to eq('find test_db.users') end - it 'does not include nil values' do - expect(attributes).not_to have_key('db.mongodb.cursor_id') - end - context 'with cursor_id' do let(:operation_class) { class_double(Mongo::Operation::GetMore, name: 'Mongo::Operation::GetMore') } let(:operation) do @@ -304,8 +363,8 @@ ) end - it 'includes db.mongodb.cursor_id' do - expect(attributes['db.mongodb.cursor_id']).to eq(12_345) + it 'leaves the cursor id for after the span is known to record' do + expect(attributes).not_to have_key('db.mongodb.cursor_id') end end @@ -594,7 +653,7 @@ describe '#process_cursor_context' do subject(:process_result) do - operation_tracer.send(:process_cursor_context, result, cursor_id, context, span) + operation_tracer.send(:process_cursor_context, result, cursor_id, context, span, true) end # rubocop:disable RSpec/VerifiedDoubles diff --git a/spec/support/tracing.rb b/spec/support/tracing.rb index c2476cbb07..00260a4315 100644 --- a/spec/support/tracing.rb +++ b/spec/support/tracing.rb @@ -28,6 +28,12 @@ def context @context ||= Context.new(self) end + # Mirrors OpenTelemetry::Trace::Span#recording?. Spans from this tracer + # always record, so the assertions see every attribute. + def recording? + true + end + # rubocop:disable Lint/UnusedMethodArgument def record_exception(exception, attributes: nil) set_attribute('exception.type', exception.class.to_s)