Clarify tags are merged in tags helpers

Document the tags helpers better.

Also add a test for the calling of the tags helper multiple times.

[skip changeset]

lib/appsignal/helpers/instrumentation.rb

@@ -479,8 +479,10 @@ def set_namespace(namespace)
       # Tags are extra bits of information that are added to transaction and
       # appear on sample details pages on AppSignal.com.
       #
+      # When this method is called multiple times, it will merge the tags.
+      #
       # @example
-      #   Appsignal.tag_request(:locale => "en")
+      #   Appsignal.tag_request(:locale => "en", :user_id => 1)
       #   Appsignal.tag_request("locale" => "en")
       #   Appsignal.tag_request("user_id" => 1)
       #

lib/appsignal/transaction.rb

@@ -180,14 +180,16 @@ def set_params_if_nil(given_params)
 
     # Set tags on the transaction.
     #
+    # When this method is called multiple times, it will merge the tags.
+    #
     # @param given_tags [Hash] Collection of tags.
     # @option given_tags [String, Symbol, Integer] :any
     #   The name of the tag as a Symbol.
     # @option given_tags [String, Symbol, Integer] "any"
     #   The name of the tag as a String.
     # @return [void]
     #
-    # @see Appsignal.tag_request
+    # @see Helpers::Instrumentation#tag_request
     # @see https://docs.appsignal.com/ruby/instrumentation/tagging.html
     #   Tagging guide
     def set_tags(given_tags = {})

spec/lib/appsignal/transaction_spec.rb

@@ -431,6 +431,42 @@ def create_transaction(id = transaction_id)
 
     describe "#set_tags" do
       let(:long_string) { "a" * 10_001 }
+
+      it "stores tags on the transaction" do
+        transaction.set_tags(
+          :valid_key => "valid_value",
+          "valid_string_key" => "valid_value",
+          :both_symbols => :valid_value,
+          :integer_value => 1,
+          :hash_value => { "invalid" => "hash" },
+          :array_value => %w[invalid array],
+          :object => Object.new,
+          :too_long_value => long_string,
+          long_string => "too_long_key"
+        )
+        transaction._sample
+
+        expect(transaction).to include_tags(
+          "valid_key" => "valid_value",
+          "valid_string_key" => "valid_value",
+          "both_symbols" => "valid_value",
+          "integer_value" => 1,
+          "too_long_value" => "#{"a" * 10_000}...",
+          long_string => "too_long_key"
+        )
+      end
+
+      it "merges the tags when called multiple times" do
+        transaction.set_tags(:key1 => "value1")
+        transaction.set_tags(:key2 => "value2")
+        transaction._sample
+
+        expect(transaction).to include_tags(
+          "key1" => "value1",
+          "key2" => "value2"
+        )
+      end
+    end
       before do
         transaction.set_tags(
           :valid_key => "valid_value",