Add support for message templates

solnic · solnic · commit a1c20917d2e6 · 2025-05-08T13:34:52.000Z
diff --git a/sentry-ruby/lib/sentry/client.rb b/sentry-ruby/lib/sentry/client.rb
@@ -182,10 +182,17 @@ def event_from_check_in(
     end
 
     # Initializes a LogEvent object with the given message and options
+    #
+    # @param message [String] the log message
+    # @param level [Symbol] the log level (:trace, :debug, :info, :warn, :error, :fatal)
+    # @param options [Hash] additional options
+    # @option options [Array] :parameters Array of values to replace template tokens in the message
+    #
+    # @return [LogEvent] the created log event
     def event_from_log(message, level:, **options)
       return unless configuration.sending_allowed?
 
-      attributes = options.reject { |k, _| k == :level }
+      attributes = options.reject { |k, _| k == :level || k == :severity }
 
       LogEvent.new(
         level: level,
diff --git a/sentry-ruby/lib/sentry/log_event.rb b/sentry-ruby/lib/sentry/log_event.rb
@@ -21,19 +21,32 @@ class LogEvent < Event
       "sentry.release" => :release,
       "sentry.address" => :server_name,
       "sentry.sdk.name" => :sdk_name,
-      "sentry.sdk.version" => :sdk_version
+      "sentry.sdk.version" => :sdk_version,
+      "sentry.message.template" => :template
     }
 
     LEVELS = %i[trace debug info warn error fatal].freeze
 
-    attr_accessor :level, :body, :attributes, :trace_id
+    attr_accessor :level, :body, :template, :attributes, :trace_id, :parameters
 
     def initialize(configuration: Sentry.configuration, **options)
       super(configuration: configuration)
+
       @type = TYPE
       @level = options.fetch(:level)
       @body = options[:body]
+      @template = @body
       @attributes = options[:attributes] || {}
+      @parameters = @attributes[:parameters] || []
+
+      if has_template_parameters?
+        @attributes["sentry.message.template"] = @body
+
+        @parameters.each_with_index do |param, index|
+          @attributes["sentry.message.parameters.#{index}"] = param
+        end
+      end
+
       @contexts = {}
     end
 
@@ -79,6 +92,14 @@ def serialize_parent_span_id
       @contexts.dig(:trace, :parent_span_id)
     end
 
+    def serialize_body
+      if @parameters.empty?
+        @body
+      else
+        sprintf(@body, *@parameters)
+      end
+    end
+
     def serialize_attributes
       hash = @attributes.each_with_object({}) do |(key, value), memo|
         memo[key] = attribute_hash(value)
@@ -109,5 +130,9 @@ def value_type(value)
         "string"
       end
     end
+
+    def has_template_parameters?
+      @parameters.is_a?(Array) && !@parameters.empty? && @body.is_a?(String) && @body.include?("%")
+    end
   end
 end
diff --git a/sentry-ruby/lib/sentry/structured_logger.rb b/sentry-ruby/lib/sentry/structured_logger.rb
@@ -23,78 +23,98 @@ class StructuredLogger
     # Severity number mapping for log levels according to the Sentry Logs Protocol
     # @see https://develop.sentry.dev/sdk/telemetry/logs/#log-severity-number
     LEVELS = {
-      "trace" => 1,
-      "debug" => 5,
-      "info" => 9,
-      "warn" => 13,
-      "error" => 17,
-      "fatal" => 21
+      trace: 1,
+      debug: 5,
+      info: 9,
+      warn: 13,
+      error: 17,
+      fatal: 21
     }.freeze
 
     # @return [Configuration] The Sentry configuration
+    # @!visibility private
     attr_reader :config
 
     # Initializes a new StructuredLogger instance
+    #
     # @param config [Configuration] The Sentry configuration
     def initialize(config)
       @config = config
     end
 
     # Logs a message at TRACE level
+    #
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def trace(message, payload = {})
-      log(:trace, message, payload)
+    def trace(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
     end
 
     # Logs a message at DEBUG level
+    #
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def debug(message, payload = {})
-      log(:debug, message, payload)
+    def debug(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
     end
 
     # Logs a message at INFO level
+    #
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def info(message, payload = {})
-      log(:info, message, payload)
+    def info(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
     end
 
     # Logs a message at WARN level
+    #
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def warn(message, payload = {})
-      log(:warn, message, payload)
+    def warn(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
     end
 
     # Logs a message at ERROR level
+    #
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def error(message, payload = {})
-      log(:error, message, payload)
+    def error(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
     end
 
     # Logs a message at FATAL level
+    #
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def fatal(message, payload = {})
-      log(:fatal, message, payload)
+    def fatal(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
     end
 
     # Logs a message at the specified level
+    #
     # @param level [Symbol] The log level (:trace, :debug, :info, :warn, :error, :fatal)
     # @param message [String] The log message
-    # @param payload [Hash] Additional attributes to include with the log
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
     # @return [LogEvent, nil] The created log event or nil if logging is disabled
-    def log(level, message, payload)
-      Sentry.capture_log(message, level: level, severity: LEVELS[level], **payload)
+    def log(level, message, parameters:, **attributes)
+      if parameters.is_a?(Hash) && attributes.empty?
+        Sentry.capture_log(message, level: level, severity: LEVELS[level], parameters: [], **parameters)
+      else
+        Sentry.capture_log(message, level: level, severity: LEVELS[level], parameters: parameters, **attributes)
+      end
     end
   end
 end
diff --git a/sentry-ruby/spec/sentry/log_event_spec.rb b/sentry-ruby/spec/sentry/log_event_spec.rb
@@ -47,16 +47,10 @@
     end
 
     it "includes all required fields" do
-      attributes = {
-        "sentry.message.template" => "User %s has logged in!",
-        "sentry.message.parameters.0" => "John"
-      }
-
       event = described_class.new(
         configuration: configuration,
         level: :info,
-        body: "User John has logged in!",
-        attributes: attributes
+        body: "User John has logged in!"
       )
 
       hash = event.to_hash
@@ -68,11 +62,6 @@
       attributes = hash[:attributes]
 
       expect(attributes).to be_a(Hash)
-      expect(attributes["sentry.message.template"]).to eq({ value: "User %s has logged in!", type: "string" })
-      expect(attributes["sentry.message.parameters.0"]).to eq({ value: "John", type: "string" })
-      expect(attributes["sentry.environment"]).to eq({ value: "test", type: "string" })
-      expect(attributes["sentry.release"]).to eq({ value: "1.2.3", type: "string" })
-      expect(attributes["sentry.address"]).to eq({ value: "server-123", type: "string" })
       expect(attributes["sentry.sdk.name"]).to eq({ value: "sentry.ruby", type: "string" })
       expect(attributes["sentry.sdk.version"]).to eq({ value: Sentry::VERSION, type: "string" })
     end
diff --git a/sentry-ruby/spec/sentry/structured_logger_spec.rb b/sentry-ruby/spec/sentry/structured_logger_spec.rb
@@ -41,6 +41,49 @@
           expect(log_event.body).to eql("Hello World")
           expect(log_event.attributes).to include(payload)
         end
+
+        it "logs with template parameters" do
+          Sentry.logger.public_send(level, "Hello %s it is %s", ["Jane", "Monday"])
+
+          expect(logs).to_not be_empty
+
+          log_event = logs.last
+          log_hash = log_event.to_hash
+
+          expect(log_event.type).to eql("log")
+          expect(log_event.level).to eql(level.to_sym)
+          expect(log_event.body).to eql("Hello %s it is %s")
+
+          expect(log_hash[:body]).to eql("Hello Jane it is Monday")
+
+          attributes = log_hash[:attributes]
+
+          expect(attributes["sentry.message.template"]).to eql({ value: "Hello %s it is %s", type: "string" })
+          expect(attributes["sentry.message.parameters.0"]).to eql({ value: "Jane", type: "string" })
+          expect(attributes["sentry.message.parameters.1"]).to eql({ value: "Monday", type: "string" })
+        end
+
+        it "logs with template parameters and extra attributres" do
+          Sentry.logger.public_send(level, "Hello %s it is %s", ["Jane", "Monday"], extra: 312)
+
+          expect(logs).to_not be_empty
+
+          log_event = logs.last
+          log_hash = log_event.to_hash
+
+          expect(log_event.type).to eql("log")
+          expect(log_event.level).to eql(level.to_sym)
+          expect(log_event.body).to eql("Hello %s it is %s")
+
+          expect(log_hash[:body]).to eql("Hello Jane it is Monday")
+
+          attributes = log_hash[:attributes]
+
+          expect(attributes[:extra]).to eql({ value: 312, type: "integer" })
+          expect(attributes["sentry.message.template"]).to eql({ value: "Hello %s it is %s", type: "string" })
+          expect(attributes["sentry.message.parameters.0"]).to eql({ value: "Jane", type: "string" })
+          expect(attributes["sentry.message.parameters.1"]).to eql({ value: "Monday", type: "string" })
+        end
       end
     end
   end
diff --git a/sentry-ruby/spec/sentry/transport_spec.rb b/sentry-ruby/spec/sentry/transport_spec.rb
@@ -243,15 +243,11 @@
           Sentry::LogEvent.new(
             configuration: configuration,
             level: :info,
-            body: "User John has logged in!",
+            body: "User %s has logged in!",
             trace_id: "5b8efff798038103d269b633813fc60c",
             timestamp: 1544719860.0,
             attributes: {
-              "sentry.message.template" => "User %s has logged in!",
-              "sentry.message.parameters.0" => "John",
-              "sentry.environment" => "production",
-              "sentry.release" => "1.0.0",
-              "sentry.trace.parent_span_id" => "b0e6f15b45c36b12"
+              parameters: ["John"]
             }
           )
         end
@@ -299,10 +295,7 @@
         expect(log_event["attributes"]).to include(
           "sentry.message.template" => { "value" => "User %s has logged in!", "type" => "string" },
           "sentry.message.parameters.0" => { "value" => "John", "type" => "string" },
-          "sentry.environment" => { "value" => "development", "type" => "string" },
-          "sentry.release" => { "value" => "1.0.0", "type" => "string" },
-          "sentry.trace.parent_span_id" => { "value" => "b0e6f15b45c36b12", "type" => "string" },
-          "sentry.address" => { "value" => matching(/\w+/), "type" => "string" }
+          "sentry.environment" => { "value" => "development", "type" => "string" }
         )
       end
     end
@@ -318,7 +311,7 @@
 
       it "gracefully removes bad encoding breadcrumb message" do
         expect do
-          serialized_result = JSON.generate(event.to_hash)
+          JSON.generate(event.to_hash)
         end.not_to raise_error
       end
     end
