Add tags to long tasks. (#4)

Author: samuel-williams-shopify

guides/long-tasks/readme.md

@@ -128,6 +128,16 @@ end
 
 The block form ensures the long task is properly stopped even if an exception occurs. They can also be nested.
 
+### Tags
+
+You can attach application-specific metadata when starting a long task:
+
+```ruby
+Falcon::Limiter::LongTask.current.start(tags: {name: :external_api_call})
+```
+
+Tags are stored on the long task while it is started or pending, and cleared when it stops. The limiter does not interpret tags directly; they are intended for instrumentation layers.
+
 ## Long Task Lifecycle
 
 ### 1. Creation

lib/falcon/limiter/long_task.rb

@@ -19,6 +19,8 @@ class LongTask
 			# The priority to use when stopping a long task to re-acquire the connection token.
 			STOP_PRIORITY = 1000
 
+			attr_reader :tags
+			
 			# @returns [LongTask] The current long task.
 			def self.current
 				Fiber.current.falcon_limiter_long_task
@@ -63,6 +65,7 @@ def initialize(request, limiter, connection_token = nil, start_delay: 0.1)
 
 				@token = Async::Limiter::Token.new(@limiter)
 				@delayed_start_task = nil
+				@tags = nil
 			end
 
 			# Check if the long task has been started, but not necessarily acquired (e.g. if there was a delay).
@@ -84,7 +87,7 @@ def pending?
 			end
 
 			# Start the long task, optionally with a delay to avoid overhead for short operations
-			def start(delay: @start_delay)
+			def start(delay: @start_delay, tags: nil)
 				# If already started, nothing to do:
 				if started?
 					if block_given?
@@ -100,6 +103,8 @@ def start(delay: @start_delay)
 					delay = nil
 				end
 
+				@tags = tags
+				
 				# Otherwise, start the long task:
 				if delay&.positive?
 					# Wait specified delay before starting the long task:
@@ -137,6 +142,8 @@ def stop(force: false, **options)
 
 				# Release the long task token:
 				release(force, **options)
+			ensure
+				@tags = nil
 			end
 
 			private

readme.md

@@ -26,6 +26,10 @@ Please see the [project documentation](https://socketry.github.io/falcon-limiter
 
 Please see the [project releases](https://socketry.github.io/falcon-limiter/releases/index) for all releases.
 
+### Unreleased
+
+  - Add optional `Falcon::Limiter::LongTask#start(tags:)` metadata for instrumentation.
+
 ### v0.4.0
 
   - Add `Falcon::Limiter::LongTask#pending?` for detecting delayed long tasks which have not acquired yet.

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Add optional `Falcon::Limiter::LongTask#start(tags:)` metadata for instrumentation.
+
 ## v0.4.0
 
   - Add `Falcon::Limiter::LongTask#pending?` for detecting delayed long tasks which have not acquired yet.

test/falcon/limiter/long_task.rb

@@ -61,6 +61,28 @@
 		expect(long_task).not.to be(:started?)
 	end
 
+	it "stores tags while started and clears them when stopped" do
+		long_task = Falcon::Limiter::LongTask.for(mock_request, long_task_limiter, start_delay: 0)
+		tags = {name: :rpc, controller: "ProductsController"}
+		
+		long_task.start(delay: 0, tags: tags)
+		expect(long_task.tags).to be == tags
+		
+		long_task.stop
+		expect(long_task.tags).to be_nil
+	end
+	
+	it "stores tags during block form and clears them afterwards" do
+		long_task = Falcon::Limiter::LongTask.for(mock_request, long_task_limiter, start_delay: 0)
+		tags = {name: :graphql_proxy}
+		
+		long_task.start(delay: 0, tags: tags) do |task|
+			expect(task.tags).to be == tags
+		end
+		
+		expect(long_task.tags).to be_nil
+	end
+	
 	it "can start with delay" do
 		long_task = Falcon::Limiter::LongTask.for(mock_request, long_task_limiter, start_delay: 0.01)
 
@@ -91,6 +113,19 @@
 		long_task.stop
 		expect(long_task).not.to be(:pending?)
 		expect(long_task).not.to be(:acquired?)
+		expect(long_task.tags).to be_nil
+	end
+	
+	it "stores tags while pending" do
+		long_task = Falcon::Limiter::LongTask.for(mock_request, long_task_limiter, start_delay: 0.1)
+		tags = {name: :core_polling}
+		
+		long_task.start(delay: 0.1, tags: tags)
+		expect(long_task).to be(:pending?)
+		expect(long_task.tags).to be == tags
+		
+		long_task.stop
+		expect(long_task.tags).to be_nil
 	end
 
 	it "is pending while waiting to acquire after delay" do
@@ -276,4 +311,18 @@
 		# Clean up
 		long_task.stop(force: true)
 	end
+	
+	it "does not replace tags when already started" do
+		long_task = Falcon::Limiter::LongTask.new(nil, long_task_limiter)
+		tags = {name: :outer}
+		
+		long_task.start(delay: 0, tags: tags)
+		long_task.start(delay: 0, tags: {name: :inner})
+		
+		expect(long_task.tags).to be == tags
+		
+		# Clean up
+		long_task.stop(force: true)
+		expect(long_task.tags).to be_nil
+	end
 end