Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion lib/mongo/monitoring/event/secure.rb
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,11 @@ module Secure
copydb
].freeze

# The hello and legacy hello command names. A constant, because
# sensitive? runs on every command event and an array literal would
# allocate on each call.
HELLO_COMMANDS = %w[hello ismaster isMaster].freeze

# Check whether the command is sensitive in terms of command monitoring
# spec. A command is detected as sensitive if it is in the
# list or if it is a hello/legacy hello command, and
Expand All @@ -53,7 +58,7 @@ def sensitive?(command_name:, document:)
# when speculativeAuthenticate is present, their commands AND replies
# MUST be redacted from the events.
# See https://github.com/mongodb/specifications/blob/master/source/command-logging-and-monitoring/command-logging-and-monitoring.md#security
%w[hello ismaster isMaster].include?(command_name.to_s) &&
HELLO_COMMANDS.include?(command_name.to_s) &&
!!document['speculativeAuthenticate']
end

Expand Down
132 changes: 71 additions & 61 deletions lib/mongo/tracing/open_telemetry/command_tracer.rb
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,6 @@ module OpenTelemetry
class CommandTracer
include Mongo::Monitoring::Event::Secure

# Commands for which a span MUST NOT be created. The OpenTelemetry spec
# requires drivers to skip command spans for sensitive commands listed in
# the Command Logging and Monitoring spec. We additionally skip hello /
# legacy hello in all forms — these are handshake/heartbeat traffic and
# would only add noise to traces.
HELLO_COMMANDS = %w[hello ismaster isMaster].freeze

# Upper bound of the lsid string cache (see #lsid).
LSID_CACHE_MAX = 128

Expand Down Expand Up @@ -70,18 +63,22 @@ def start_span(message, operation_context, connection); end
#
# @return [ Object ] the result of the command.
def trace_command(message, _operation_context, connection, &block)
return yield if skip_tracing?(message)
# Read the command document and name once and pass them on: every
# read of message.documents allocates.
doc = message.documents.first
name = command_name(doc)
return yield if skip_tracing?(doc, name)

# Commands should always be nested under their operation span, not directly under
# the transaction span. Don't pass with_parent to use automatic parent resolution
# from the currently active span (the operation span).
span = create_command_span(message, connection)
span = create_command_span(name, doc, connection)
# With no SDK and no valid parent, the API returns a span with an
# invalid context. It cannot be made current, recorded or
# propagated, so it gets no work at all, not even finishing it.
return yield unless span.context.valid?

trace_with_span(span, message, &block)
trace_with_span(span, message, name, doc, &block)
end

private
Expand All @@ -93,13 +90,15 @@ def trace_command(message, _operation_context, connection, &block)
#
# @param span [ OpenTelemetry::Trace::Span ] a span with a valid context.
# @param message [ Mongo::Protocol::Message ] the command message.
# @param name [ String ] the command name.
# @param doc [ Hash ] the command document.
#
# @return [ Object ] the result of the command.
#
# rubocop:disable Lint/RescueException
def trace_with_span(span, message)
def trace_with_span(span, message, name, doc)
recording = span.recording?
apply_deferred_attributes(span, message) if recording
apply_deferred_attributes(span, message, name, doc) if recording
::OpenTelemetry::Trace.with_span(span) do |s, _c|
yield.tap do |result|
process_command_result(result, s) if recording
Expand All @@ -116,29 +115,31 @@ def trace_with_span(span, message)
# Determines whether the command must not be traced. Sensitive auth
# commands carry credentials in their payloads (SCRAM proofs, cleartext
# passwords, etc.) and the OpenTelemetry spec requires drivers to skip
# command spans for them. Hello / legacy hello are also skipped to keep
# handshake traffic out of traces.
# command spans for them. Hello / legacy hello in all forms
# (Secure::HELLO_COMMANDS) are also skipped: they are handshake and
# heartbeat traffic and would only add noise to traces.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param doc [ Hash ] the command document.
# @param name [ String ] the command name.
#
# @return [ Boolean ] true when no command span should be created.
def skip_tracing?(message)
name = command_name(message)
def skip_tracing?(doc, name)
return true if HELLO_COMMANDS.include?(name)

sensitive?(command_name: name, document: message.documents.first)
sensitive?(command_name: name, document: doc)
end

# Creates a span for a command.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param name [ String ] the command name.
# @param doc [ Hash ] the command document.
# @param connection [ Mongo::Server::Connection ] the connection.
#
# @return [ OpenTelemetry::Trace::Span ] the created span.
def create_command_span(message, connection)
def create_command_span(name, doc, connection)
@otel_tracer.start_span(
command_name(message),
attributes: span_attributes(message, connection),
name,
attributes: span_attributes(doc, name, connection),
kind: :client
)
end
Expand Down Expand Up @@ -170,16 +171,17 @@ def handle_command_exception(span, exception)
# are set by apply_deferred_attributes once the span is known to
# record.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param doc [ Hash ] the command document.
# @param name [ String ] the command name.
# @param connection [ Mongo::Server::Connection ] the connection.
#
# @return [ Hash ] OpenTelemetry span attributes following MongoDB semantic conventions.
def span_attributes(message, connection)
def span_attributes(doc, name, connection)
{
'db.system.name' => 'mongodb',
'db.namespace' => database(message),
'db.collection.name' => collection_name(message),
'db.command.name' => command_name(message)
'db.namespace' => database(doc),
'db.collection.name' => collection_name(name, doc),
'db.command.name' => name
}.compact.merge(connection_attributes(connection))
end

Expand All @@ -189,13 +191,15 @@ def span_attributes(message, connection)
#
# @param span [ OpenTelemetry::Trace::Span ] the span.
# @param message [ Mongo::Protocol::Message ] the command message.
def apply_deferred_attributes(span, message)
# @param name [ String ] the command name.
# @param doc [ Hash ] the command document.
def apply_deferred_attributes(span, message, name, doc)
{
'db.query.summary' => query_summary(message),
'db.query.summary' => query_summary(name, doc),
'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)
'db.mongodb.cursor_id' => cursor_id(name, doc),
'db.mongodb.lsid' => lsid(doc),
'db.mongodb.txn_number' => txn_number(doc)
}.each do |key, value|
span.set_attribute(key, value) unless value.nil?
end
Expand Down Expand Up @@ -259,51 +263,56 @@ def maybe_trace_error(result, span)

# Generates a summary string for the query.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param name [ String ] the command name.
# @param doc [ Hash ] the command document.
#
# @return [ String ] summary in format "command_name db.collection" or "command_name db".
def query_summary(message)
if (coll_name = collection_name(message))
"#{command_name(message)} #{database(message)}.#{coll_name}"
def query_summary(name, doc)
if (coll_name = collection_name(name, doc))
"#{name} #{database(doc)}.#{coll_name}"
else
"#{command_name(message)} #{database(message)}"
"#{name} #{database(doc)}"
end
end

# Extracts the collection name from the command message.
# Extracts the collection name from the command document.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param name [ String ] the command name.
# @param doc [ Hash ] the command document.
#
# @return [ String | nil ] the collection name, or nil if not applicable.
def collection_name(message)
case command_name(message)
def collection_name(name, doc)
case name
when 'getMore'
message.documents.first['collection'].to_s
doc['collection'].to_s
when 'listCollections', 'listDatabases', 'commitTransaction', 'abortTransaction'
nil
else
value = message.documents.first.values.first
# The first value, read without building an array of all of them.
value = doc.each_value { |v| break v } # rubocop:disable Lint/UnreachableLoop -- first value only
# Return nil if the value is not a string (e.g., for admin commands that have numeric values)
value.is_a?(String) ? value : nil
end
end

# Extracts the command name from the message.
# Extracts the command name, the first key of the command document,
# without building an array of all keys.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param doc [ Hash ] the command document.
#
# @return [ String ] the command name.
def command_name(message)
message.documents.first.keys.first.to_s
def command_name(doc)
doc.each_key { |key| return key.to_s } # rubocop:disable Lint/UnreachableLoop -- first key only
''
end

# Extracts the database name from the message.
# Extracts the database name from the command document.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param doc [ Hash ] the command document.
#
# @return [ String ] the database name.
def database(message)
message.documents.first['$db'].to_s
def database(doc)
doc['$db'].to_s
end

# Checks if query text capture is enabled.
Expand All @@ -315,24 +324,25 @@ def query_text?

# Extracts the cursor ID from getMore commands.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param name [ String ] the command name.
# @param doc [ Hash ] the command document.
#
# @return [ Integer | nil ] the cursor ID, or nil if not a getMore command.
def cursor_id(message)
return unless command_name(message) == 'getMore'
def cursor_id(name, doc)
return unless name == 'getMore'

message.documents.first['getMore'].value
doc['getMore'].value
end

# Extracts the logical session ID from the command, as a UUID string.
# The string is formatted once per session id and kept in a small
# cache, cleared when it reaches LSID_CACHE_MAX entries.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param doc [ Hash ] the command document.
#
# @return [ String | nil ] the session ID, or nil if not present.
def lsid(message)
lsid_doc = message.documents.first['lsid']
def lsid(doc)
lsid_doc = doc['lsid']
return unless lsid_doc

binary = lsid_doc['id']
Expand All @@ -350,11 +360,11 @@ def lsid(message)

# Extracts the transaction number from the command.
#
# @param message [ Mongo::Protocol::Message ] the command message.
# @param doc [ Hash ] the command document.
#
# @return [ Integer | nil ] the transaction number, or nil if not present.
def txn_number(message)
txn_num = message.documents.first['txnNumber']
def txn_number(doc)
txn_num = doc['txnNumber']
return unless txn_num

txn_num.value
Expand Down
28 changes: 19 additions & 9 deletions spec/mongo/tracing/open_telemetry/command_tracer_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,16 @@
expect(count).to eq(1)
end

it 'reads the command document once per command' do
count = 0
allow(message).to receive(:documents) do
count += 1
[ document ]
end
command_tracer.trace_command(message, operation_context, connection) { result }
expect(count).to eq(1)
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
Expand Down Expand Up @@ -423,7 +433,7 @@
end

describe '#span_attributes' do
subject { command_tracer.send(:span_attributes, message, connection) }
subject { command_tracer.send(:span_attributes, document, document.keys.first, connection) }

it 'includes db.system.name' do
expect(subject['db.system.name']).to eq('mongodb')
Expand Down Expand Up @@ -478,7 +488,7 @@
end

describe '#apply_deferred_attributes' do
subject(:apply) { command_tracer.send(:apply_deferred_attributes, deferred_span, message) }
subject(:apply) { command_tracer.send(:apply_deferred_attributes, deferred_span, message, document.keys.first, document) }

let(:deferred_span) { instance_double(OpenTelemetry::Trace::Span, set_attribute: nil) }

Expand Down Expand Up @@ -540,7 +550,7 @@
end

describe '#collection_name' do
subject { command_tracer.send(:collection_name, message) }
subject { command_tracer.send(:collection_name, document.keys.first, document) }

context 'with find command' do
let(:document) { { 'find' => 'users' } }
Expand Down Expand Up @@ -600,7 +610,7 @@
end

describe '#command_name' do
subject { command_tracer.send(:command_name, message) }
subject { command_tracer.send(:command_name, document) }

let(:document) { { 'find' => 'users' } }

Expand All @@ -610,7 +620,7 @@
end

describe '#database' do
subject { command_tracer.send(:database, message) }
subject { command_tracer.send(:database, document) }

let(:document) { { 'find' => 'users', '$db' => 'test_db' } }

Expand All @@ -620,7 +630,7 @@
end

describe '#query_summary' do
subject { command_tracer.send(:query_summary, message) }
subject { command_tracer.send(:query_summary, document.keys.first, document) }

context 'with collection name' do
let(:document) { { 'find' => 'users', '$db' => 'test_db' } }
Expand All @@ -640,7 +650,7 @@
end

describe '#cursor_id' do
subject { command_tracer.send(:cursor_id, message) }
subject { command_tracer.send(:cursor_id, document.keys.first, document) }

context 'with getMore command' do
let(:document) { { 'getMore' => BSON::Int64.new(999) } }
Expand All @@ -660,7 +670,7 @@
end

describe '#lsid' do
subject { command_tracer.send(:lsid, message) }
subject { command_tracer.send(:lsid, document) }

context 'with lsid present' do
let(:document) { { 'find' => 'users', 'lsid' => { 'id' => BSON::Binary.from_uuid(lsid_value) } } }
Expand All @@ -680,7 +690,7 @@
end

describe '#txn_number' do
subject { command_tracer.send(:txn_number, message) }
subject { command_tracer.send(:txn_number, document) }

context 'with txnNumber present' do
let(:document) { { 'find' => 'users', 'txnNumber' => BSON::Int64.new(42) } }
Expand Down
Loading