activesupport-json_logging 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 879dfb3d0d8142a294407c70771d234e55d410032dbc50f035bf85f3bd33b79a
-  data.tar.gz: bfa9d0637d5e84f58acdf407ce782feda91b584c5c63700b93ec2aa4e6e59dd4
+  metadata.gz: 71ac52d26c4cca14a0eaed618927f9432880865ad9b24e43232b5801ce10a055
+  data.tar.gz: 81ef2c90e5d44fc7910f319acdbbd4bb9b56572075c6a28050fd05759349e91b
 SHA512:
-  metadata.gz: e4ed4ef5739e411af61e6186581ec30aa3f0653c557d7f2bc088abf264a3e8608c483b0790b892a7e1c10674d55811f95a5a3e4c33d073cd59949469e732e875
-  data.tar.gz: ec86db106814dee2731695159275fb7c56700d36564571edd72e54013d076dd1a3328a050eae06429d16eaaf1c0538404ae8345605d5a2ec63684ca1f71f40b7
+  metadata.gz: 0f8ebdfeb94e456cdffd8e8d176c9dde7dff4187f2547b721dd4ec33e229c290663386a1f1c091ee54e95821be3bc11eb8f02fbf645f3a9bd8a54ab1e79596b9
+  data.tar.gz: cbfdad0f75642ec096bf18ca154a9aef9ce3364d92a43c263ceea81f877f018db3459b1a3fc239b2025aa6d96815db8f37063675f33a29d24fd24de4eaeb2299

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # CHANGELOG
 
+## 1.2.3 (2026-07-13)
+
+- Reduce per-line work for plain string, hash, tagged, and context-scoped log messages on common shapes
+- Sanitize flat and nested structured hash payloads without deep-copying the source when values are logging-safe primitives
+- Reuse ISO8601 microsecond UTC timestamps when callers already supply them
+- Skip context merging when tags and additional context are both empty
+- Cache empty thread context as a frozen hash on the hot path
+- Expand hot-path contract specs for fast-path logging and sanitization
+- Encode large nested structured hash log lines in one pass with copy-on-write sanitization and JSON.generate instead of building a full sanitized tree first
+
+## 1.2.2 (2026-07-08)
+
+- Isolate log context per execution via `ActiveSupport::IsolatedExecutionState` when available
+- Sanitize fallback formatter output when JSON encoding fails
+- Refactor emit path into `LineEncoder`, `PayloadBuilder`, and `Severity` modules
+- Cache sanitized `additional_context` per `with_context` scope on the hot path
+- Memoize `ActiveSupport::ParameterFilter` when `filter_parameters` is unchanged
+- Fast-path `sanitize_string` for clean ASCII text within length limits
+- Sanitize tags at push time instead of on every log line
+- Skip `deep_stringify_keys` when payload structure already uses string keys
+- Add hot-path optimization specs
+
 ## 1.2.1 (2026-01-18)
 
 - Refactor tag stack handling in JsonLogging formatter for improved maintainability

data/lib/json_logging/formatter.rb

@@ -2,17 +2,21 @@ module JsonLogging
   class Formatter < ::Logger::Formatter
     def initialize(tags: [])
       super()
-      @tags = Array(tags)
+      @tags = Sanitizer.prepare_tags(tags)
     end
 
     attr_reader :tags
 
     def call(severity, timestamp, progname, msg)
-      timestamp_str = Helpers.normalize_timestamp(timestamp)
-      payload = PayloadBuilder.build_base_payload(msg, severity: severity, timestamp: timestamp_str)
-      payload = PayloadBuilder.merge_context(payload, additional_context: JsonLogging.additional_context.compact, tags: @tags)
-
-      "#{payload.compact.to_json}\n"
+      LineEncoder.build_line(
+        msg: msg,
+        severity: severity,
+        timestamp: Helpers.normalize_timestamp(timestamp),
+        tags: @tags,
+        additional_context: JsonLogging.additional_context_for_payload,
+        additional_context_sanitized: true,
+        sanitize_tags: false
+      )
     rescue => e
       build_fallback_output(severity, timestamp, msg, e)
     end
@@ -23,14 +27,14 @@ module JsonLogging
       timestamp_str = Helpers.normalize_timestamp(timestamp)
       fallback_payload = {
         timestamp: timestamp_str,
-        severity: severity,
-        message: Helpers.safe_string(msg),
+        severity: Severity.name_for(severity),
+        message: Sanitizer.sanitize_string(Helpers.safe_string(msg)),
         formatter_error: {
           class: Sanitizer.sanitize_string(error.class.name),
           message: Sanitizer.sanitize_string(Helpers.safe_string(error.message))
         }
       }
-      "#{fallback_payload.compact.to_json}\n"
+      LineEncoder.to_json_line(fallback_payload)
     end
   end
 end

data/lib/json_logging/formatter_with_tags.rb

@@ -18,12 +18,15 @@ module JsonLogging
     end
 
     def call(severity, timestamp, progname, msg)
-      tags = current_tags
-      timestamp_str = Helpers.normalize_timestamp(timestamp)
-      payload = PayloadBuilder.build_base_payload(msg, severity: severity, timestamp: timestamp_str)
-      payload = PayloadBuilder.merge_context(payload, additional_context: JsonLogging.additional_context.compact, tags: tags)
-
-      "#{payload.compact.to_json}\n"
+      LineEncoder.build_line(
+        msg: msg,
+        severity: severity,
+        timestamp: Helpers.normalize_timestamp(timestamp),
+        tags: current_tags,
+        additional_context: JsonLogging.additional_context_for_payload,
+        additional_context_sanitized: true,
+        sanitize_tags: false
+      )
     rescue => e
       build_fallback_output(severity, timestamp, msg, e)
     end
@@ -89,14 +92,14 @@ module JsonLogging
       timestamp_str = Helpers.normalize_timestamp(timestamp)
       fallback_payload = {
         timestamp: timestamp_str,
-        severity: severity,
-        message: Helpers.safe_string(msg),
+        severity: Severity.name_for(severity),
+        message: Sanitizer.sanitize_string(Helpers.safe_string(msg)),
         formatter_error: {
           class: Sanitizer.sanitize_string(error.class.name),
           message: Sanitizer.sanitize_string(Helpers.safe_string(error.message))
         }
       }
-      "#{fallback_payload.compact.to_json}\n"
+      LineEncoder.to_json_line(fallback_payload)
     end
   end
 end

data/lib/json_logging/helpers.rb

@@ -1,13 +1,28 @@
 module JsonLogging
   module Helpers
+    ISO8601_MICROSECOND_UTC_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z\z/
+
     module_function
 
     # Normalize timestamp to ISO8601 with microseconds
     def normalize_timestamp(timestamp)
-      time = timestamp || current_time
+      return timestamp if iso8601_microsecond_utc?(timestamp)
+
+      format_timestamp(timestamp || current_time)
+    end
+
+    def current_timestamp
+      format_timestamp(current_time)
+    end
+
+    def format_timestamp(time)
       time.utc.iso8601(6)
     end
 
+    def iso8601_microsecond_utc?(timestamp)
+      timestamp.is_a?(String) && timestamp.match?(ISO8601_MICROSECOND_UTC_PATTERN)
+    end
+
     # Get current time, using Time.zone if available, otherwise Time.now
     def current_time
       if defined?(Time.zone) && Time.zone

data/lib/json_logging/json_logger_extension.rb

@@ -2,15 +2,6 @@ module JsonLogging
   # Module that extends any Logger with JSON formatting capabilities
   # This is used by JsonLogging.new to wrap standard loggers
   module JsonLoggerExtension
-    SEVERITY_NAMES = {
-      ::Logger::DEBUG => "DEBUG",
-      ::Logger::INFO => "INFO",
-      ::Logger::WARN => "WARN",
-      ::Logger::ERROR => "ERROR",
-      ::Logger::FATAL => "FATAL",
-      ::Logger::UNKNOWN => "UNKNOWN"
-    }.freeze
-
     def formatter
       @formatter_with_tags ||= begin
         formatter_with_tags = FormatterWithTags.new(self)
@@ -19,46 +10,31 @@ module JsonLogging
       end
     end
 
-    def formatter=(formatter)
-      # Always use FormatterWithTags to ensure JSON formatting
+    def formatter=(_ignored)
+      # Custom formatters are ignored; JSON output requires FormatterWithTags.
       formatter_with_tags = @formatter_with_tags || FormatterWithTags.new(self)
       instance_variable_set(:@formatter, formatter_with_tags)
       @formatter_with_tags = formatter_with_tags
     end
 
-    def add(severity, message = nil, progname = nil)
+    def add(severity, message = nil, progname = nil, &block)
       return true if severity < level
 
-      msg = if message.nil?
-        if block_given?
-          yield
-        else
-          progname
-        end
-      else
-        message
-      end
-
-      payload = build_payload(severity, progname, msg)
-
-      stringified = stringify_keys(payload)
-      @logdev&.write("#{stringified.to_json}\n")
+      msg = nil
+      msg = extract_log_message(message, progname, &block)
+      line = LineEncoder.build_line(
+        msg: msg,
+        severity: severity,
+        timestamp: Helpers.current_timestamp,
+        tags: formatter.current_tags,
+        additional_context: JsonLogging.additional_context_for_payload,
+        additional_context_sanitized: true,
+        sanitize_tags: false
+      )
+      @logdev&.write(line)
       true
     rescue => e
-      # Never fail logging - write a fallback entry
-      # Initialize msg if it wasn't set due to error
-      msg ||= "<uninitialized>"
-
-      fallback = {
-        timestamp: Helpers.normalize_timestamp(Helpers.current_time),
-        severity: severity_name(severity),
-        message: Sanitizer.sanitize_string(Helpers.safe_string(msg)),
-        logger_error: {
-          class: Sanitizer.sanitize_string(e.class.name),
-          message: Sanitizer.sanitize_string(Helpers.safe_string(e.message))
-        }
-      }
-      @logdev&.write("#{fallback.compact.to_json}\n")
+      write_add_fallback(severity, msg, e)
       true
     end
 
@@ -91,6 +67,28 @@ module JsonLogging
 
     private
 
+    def extract_log_message(message, progname, &block)
+      if message.nil?
+        block ? block.call : progname
+      else
+        message
+      end
+    end
+
+    def write_add_fallback(severity, msg, error)
+      msg ||= "<uninitialized>"
+      fallback = {
+        timestamp: Helpers.current_timestamp,
+        severity: Severity.name_for(severity),
+        message: Sanitizer.sanitize_string(Helpers.safe_string(msg)),
+        logger_error: {
+          class: Sanitizer.sanitize_string(error.class.name),
+          message: Sanitizer.sanitize_string(Helpers.safe_string(error.message))
+        }
+      }
+      @logdev&.write(LineEncoder.to_json_line(fallback))
+    end
+
     def tags_key
       @tags_key ||= :"json_logging_tags_#{object_id}"
     end
@@ -116,8 +114,9 @@ module JsonLogging
     end
 
     def push_tags(tags)
-      flat = tags.flatten.compact.map(&:to_s).reject(&:empty?)
+      flat = Sanitizer.prepare_tags(tags)
       return if flat.empty?
+
       set_tags(current_tags + flat)
     end
 
@@ -125,36 +124,12 @@ module JsonLogging
       set_tags([])
     end
 
-    def build_payload(severity, _progname, msg)
-      payload = PayloadBuilder.build_base_payload(
-        msg,
-        severity: severity_name(severity),
-        timestamp: Helpers.normalize_timestamp(Helpers.current_time)
-      )
-      payload = PayloadBuilder.merge_context(
-        payload,
-        additional_context: JsonLogging.additional_context.compact,
-        tags: formatter.current_tags
-      )
-
-      payload.compact
-    end
-
     def severity_name(severity)
-      SEVERITY_NAMES[severity] || severity.to_s
+      Severity.name_for(severity)
     end
 
-    def stringify_keys(hash)
-      case hash
-      when Hash
-        hash.each_with_object({}) do |(k, v), result|
-          result[k.to_s] = stringify_keys(v)
-        end
-      when Array
-        hash.map { |v| stringify_keys(v) }
-      else
-        hash
-      end
+    def stringify_keys(obj)
+      LineEncoder.deep_stringify_structure(obj)
     end
   end
 
@@ -179,8 +154,9 @@ module JsonLogging
       end
 
       def push_tags(tags)
-        flat = Array(tags).flatten.compact.map(&:to_s).reject(&:empty?)
+        flat = Sanitizer.prepare_tags(tags)
         return [] if flat.empty?
+
         @tags.concat(flat)
         flat
       end

data/lib/json_logging/line_encoder.rb

@@ -0,0 +1,245 @@
+require "active_support/core_ext/hash/keys"
+
+require_relative "message_parser"
+require_relative "severity"
+require_relative "payload_builder"
+require_relative "structured_hash_json_encoder"
+
+module JsonLogging
+  module LineEncoder
+    module_function
+
+    def build_line(msg:, severity:, timestamp:, tags:, additional_context:, additional_context_sanitized: false, sanitize_tags: true)
+      if simple_string_line?(msg, tags, additional_context)
+        return simple_string_json_line(
+          message: msg,
+          severity: Severity.name_for(severity),
+          timestamp: timestamp
+        )
+      end
+
+      if tagged_simple_string_line?(msg, tags, additional_context)
+        return tagged_simple_string_json_line(
+          message: msg,
+          severity: Severity.name_for(severity),
+          timestamp: timestamp,
+          tags: tags,
+          sanitize_tags: sanitize_tags
+        )
+      end
+
+      if contextual_simple_string_line?(msg, tags, additional_context, additional_context_sanitized: additional_context_sanitized)
+        return contextual_simple_string_json_line(
+          message: msg,
+          severity: Severity.name_for(severity),
+          timestamp: timestamp,
+          additional_context: additional_context
+        )
+      end
+
+      if standalone_hash_line?(msg, tags, additional_context)
+        return standalone_hash_json_line(
+          message: msg,
+          severity: Severity.name_for(severity),
+          timestamp: timestamp
+        )
+      end
+
+      if tagged_hash_line?(msg, tags, additional_context)
+        return tagged_hash_json_line(
+          message: msg,
+          severity: Severity.name_for(severity),
+          timestamp: timestamp,
+          tags: tags,
+          sanitize_tags: sanitize_tags
+        )
+      end
+
+      if contextual_hash_line?(msg, tags, additional_context, additional_context_sanitized: additional_context_sanitized)
+        return contextual_hash_json_line(
+          message: msg,
+          severity: Severity.name_for(severity),
+          timestamp: timestamp,
+          additional_context: additional_context
+        )
+      end
+
+      sev = Severity.name_for(severity)
+      payload = PayloadBuilder.build_base_payload(msg, severity: sev, timestamp: timestamp)
+      unless tags.empty? && PayloadBuilder.empty_additional_context?(additional_context)
+        payload = PayloadBuilder.merge_context(
+          payload,
+          additional_context: additional_context,
+          tags: tags,
+          additional_context_sanitized: additional_context_sanitized,
+          sanitize_tags: sanitize_tags
+        )
+      end
+      to_json_line(payload)
+    end
+
+    def to_json_line(payload_hash)
+      compacted = payload_hash.compact
+      json_payload = string_keyed_structure?(compacted) ? compacted : compacted.deep_stringify_keys
+      "#{json_payload.to_json}\n"
+    end
+
+    def string_keyed_structure?(object)
+      case object
+      when Hash
+        object.keys.all?(String) && object.values.all? { |value| string_keyed_structure?(value) }
+      when Array
+        object.all? { |value| string_keyed_structure?(value) }
+      else
+        true
+      end
+    end
+
+    def simple_string_line?(message, tags, additional_context)
+      message.is_a?(String) &&
+        !MessageParser.json_string?(message) &&
+        tags.respond_to?(:empty?) && tags.empty? &&
+        additional_context.respond_to?(:empty?) && additional_context.empty?
+    end
+
+    def simple_string_json_line(message:, severity:, timestamp:)
+      sanitized_message = Sanitizer.sanitize_string(message)
+      "#{JSON.generate("message" => sanitized_message, "severity" => severity, "timestamp" => timestamp)}\n"
+    end
+
+    def tagged_simple_string_line?(message, tags, additional_context)
+      message.is_a?(String) &&
+        !MessageParser.json_string?(message) &&
+        tags.respond_to?(:empty?) && !tags.empty? &&
+        additional_context.respond_to?(:empty?) && additional_context.empty?
+    end
+
+    def tagged_simple_string_json_line(message:, severity:, timestamp:, tags:, sanitize_tags:)
+      sanitized_message = Sanitizer.sanitize_string(message)
+      prepared_tags = sanitize_tags ? Sanitizer.prepare_tags(tags) : tags
+      "#{JSON.generate("message" => sanitized_message, "severity" => severity, "timestamp" => timestamp, "tags" => prepared_tags.uniq)}\n"
+    end
+
+    def contextual_simple_string_line?(message, tags, additional_context, additional_context_sanitized:)
+      message.is_a?(String) &&
+        !MessageParser.json_string?(message) &&
+        tags.respond_to?(:empty?) && tags.empty? &&
+        !PayloadBuilder.empty_additional_context?(additional_context) &&
+        additional_context_sanitized
+    end
+
+    def contextual_simple_string_json_line(message:, severity:, timestamp:, additional_context:)
+      sanitized_message = Sanitizer.sanitize_string(message)
+      payload = {
+        "message" => sanitized_message,
+        "severity" => severity,
+        "timestamp" => timestamp
+      }
+      context = PayloadBuilder.context_payload_portion(additional_context)
+      payload["context"] = context unless context.empty?
+      "#{JSON.generate(payload)}\n"
+    end
+
+    def standalone_hash_line?(message, tags, additional_context)
+      hash_message?(message) &&
+        tags.respond_to?(:empty?) && tags.empty? &&
+        additional_context.respond_to?(:empty?) && additional_context.empty?
+    end
+
+    def hash_message?(message)
+      message.is_a?(Hash) || (message.respond_to?(:to_hash) && !message.is_a?(String))
+    end
+
+    def standalone_hash_json_line(message:, severity:, timestamp:)
+      hash = message.is_a?(Hash) ? message : message.to_hash
+      line = StructuredHashJsonEncoder.try_encode_line(hash, severity: severity, timestamp: timestamp)
+      return line if line
+
+      payload = Sanitizer.sanitize_hash(hash)
+      payload["severity"] = severity
+      payload["timestamp"] = timestamp
+      "#{JSON.generate(payload)}\n"
+    end
+
+    def tagged_hash_line?(message, tags, additional_context)
+      hash_message?(message) &&
+        tags.respond_to?(:empty?) && !tags.empty? &&
+        additional_context.respond_to?(:empty?) && additional_context.empty?
+    end
+
+    def tagged_hash_json_line(message:, severity:, timestamp:, tags:, sanitize_tags:)
+      hash = message.is_a?(Hash) ? message : message.to_hash
+      prepared_tags = sanitize_tags ? Sanitizer.prepare_tags(tags) : tags
+      merged_tags = (Array(hash[:tags] || hash["tags"]) + prepared_tags).uniq
+      field_overrides = {"tags" => merged_tags}
+
+      line = StructuredHashJsonEncoder.try_encode_line(
+        hash,
+        severity: severity,
+        timestamp: timestamp,
+        field_overrides: field_overrides
+      )
+      return line if line
+
+      payload = Sanitizer.sanitize_hash(hash)
+      payload["severity"] = severity
+      payload["timestamp"] = timestamp
+      payload["tags"] = merged_tags
+      "#{JSON.generate(payload)}\n"
+    end
+
+    def contextual_hash_line?(message, tags, additional_context, additional_context_sanitized:)
+      hash_message?(message) &&
+        tags.respond_to?(:empty?) && tags.empty? &&
+        !PayloadBuilder.empty_additional_context?(additional_context) &&
+        additional_context_sanitized
+    end
+
+    def contextual_hash_json_line(message:, severity:, timestamp:, additional_context:)
+      hash = message.is_a?(Hash) ? message : message.to_hash
+      context = PayloadBuilder.context_payload_portion(additional_context)
+      merged_context = {}
+      unless context.empty?
+        existing_context = hash[:context] || hash["context"]
+        merged_context = existing_context.is_a?(Hash) ? existing_context.merge(context) : context
+      end
+      field_overrides = merged_context.empty? ? {} : {"context" => merged_context}
+
+      line = StructuredHashJsonEncoder.try_encode_line(
+        hash,
+        severity: severity,
+        timestamp: timestamp,
+        field_overrides: field_overrides
+      )
+      return line if line
+
+      payload = Sanitizer.sanitize_hash(hash)
+      payload["severity"] = severity
+      payload["timestamp"] = timestamp
+      unless merged_context.empty?
+        existing_context = payload["context"].is_a?(Hash) ? payload["context"] : {}
+        payload["context"] = existing_context.merge(merged_context)
+      end
+      "#{JSON.generate(payload)}\n"
+    end
+
+    def build_sanitized_hash_payload(message:, severity:, timestamp:)
+      hash = message.is_a?(Hash) ? message : message.to_hash
+      payload = Sanitizer.sanitize_hash(hash)
+      payload["severity"] = severity
+      payload["timestamp"] = timestamp
+      payload
+    end
+
+    def deep_stringify_structure(obj)
+      case obj
+      when Hash
+        obj.deep_stringify_keys
+      when Array
+        obj.map { |v| deep_stringify_structure(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/json_logging/payload_builder.rb

@@ -1,5 +1,7 @@
 module JsonLogging
   module PayloadBuilder
+    SYSTEM_CONTROLLED_KEYS = [:tags, "tags", :severity, "severity", :timestamp, "timestamp", :message, "message", :context, "context"].freeze
+
     module_function
 
     def build_base_payload(msg, severity: nil, timestamp: nil)
@@ -9,46 +11,80 @@ module JsonLogging
       if parsed.is_a?(Hash)
         payload.merge!(parsed)
       else
-        payload[:message] = parsed
+        payload["message"] = parsed
       end
 
-      payload[:severity] = severity if severity
-      payload[:timestamp] = timestamp if timestamp
+      payload["severity"] = severity if severity
+      payload["timestamp"] = timestamp if timestamp
 
       payload
     end
 
-    def merge_context(payload, additional_context:, tags: [])
-      existing_context = payload[:context].is_a?(Hash) ? payload[:context] : {}
+    def merge_context(payload, additional_context:, tags: [], additional_context_sanitized: false, sanitize_tags: true)
+      return payload if merge_context_skippable?(payload, additional_context: additional_context, tags: tags)
+      return merge_tags_only(payload, tags: tags, sanitize_tags: sanitize_tags) if tags_only_merge?(payload, additional_context: additional_context, tags: tags)
+
+      existing_context = payload["context"].is_a?(Hash) ? payload["context"] : {}
 
-      # Sanitize additional context before merging (filters sensitive keys, limits size, sanitizes strings only)
-      # Only sanitize if it's a hash - preserve other types
-      sanitized_context = if additional_context.is_a?(Hash) && !additional_context.empty?
+      sanitized_context = if additional_context_sanitized
+        additional_context.is_a?(Hash) ? additional_context : {}
+      elsif additional_context.is_a?(Hash) && !additional_context.empty?
         Sanitizer.sanitize_hash(additional_context)
       else
         additional_context || {}
       end
 
-      # Filter out system-controlled keys from user context
-      # These keys should never be set by user context as they're controlled by the logger
-      system_controlled_keys = [:tags, "tags", :severity, "severity", :timestamp, "timestamp", :message, "message", :context, "context"]
-      user_context_filtered = sanitized_context.except(*system_controlled_keys)
+      user_context_filtered = sanitized_context.except(*SYSTEM_CONTROLLED_KEYS)
 
-      # Also prevent overriding any existing payload keys (additional safety)
-      deduped_additional = user_context_filtered.reject { |k, _| payload.key?(k) }
+      deduped_additional = user_context_filtered.reject { |key, _| payload.key?(key) || payload.key?(key.to_s) }
       merged_context = existing_context.merge(deduped_additional)
 
-      # Put tags at root level, separate from context
-      # Merge with existing tags from payload (e.g., when logging a hash with tags: [...] at root)
       unless tags.empty?
-        existing_tags = Array(payload[:tags] || payload["tags"])
-        # Sanitize tag strings (remove control chars, truncate)
-        sanitized_tags = tags.map { |tag| Sanitizer.sanitize_string(tag.to_s) }
-        payload[:tags] = (existing_tags + sanitized_tags).uniq
+        existing_tags = Array(payload["tags"])
+        prepared_tags = sanitize_tags ? tags.map { |tag| Sanitizer.sanitize_string(tag.to_s) } : tags
+        payload["tags"] = (existing_tags + prepared_tags).uniq
       end
 
-      payload[:context] = merged_context unless merged_context.empty?
+      unless merged_context.empty?
+        payload["context"] = merged_context.transform_keys(&:to_s)
+      end
+      payload
+    end
+
+    def empty_additional_context?(additional_context)
+      additional_context.nil? || (additional_context.respond_to?(:empty?) && additional_context.empty?)
+    end
+
+    def merge_context_skippable?(payload, additional_context:, tags:)
+      tags.empty? &&
+        empty_additional_context?(additional_context) &&
+        payload_context_empty?(payload)
+    end
+
+    def payload_context_empty?(payload)
+      existing_context = payload["context"]
+      existing_context.nil? || (existing_context.respond_to?(:empty?) && existing_context.empty?)
+    end
+
+    def tags_only_merge?(payload, additional_context:, tags:)
+      !tags.empty? &&
+        empty_additional_context?(additional_context) &&
+        payload_context_empty?(payload)
+    end
+
+    def merge_tags_only(payload, tags:, sanitize_tags:)
+      existing_tags = Array(payload["tags"])
+      prepared_tags = sanitize_tags ? tags.map { |tag| Sanitizer.sanitize_string(tag.to_s) } : tags
+      payload["tags"] = (existing_tags + prepared_tags).uniq
       payload
     end
+
+    def context_payload_portion(additional_context)
+      return {} unless additional_context.is_a?(Hash)
+
+      additional_context.reject do |key, _|
+        SYSTEM_CONTROLLED_KEYS.include?(key) || SYSTEM_CONTROLLED_KEYS.include?(key.to_s)
+      end
+    end
   end
 end