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)