Document addition of prefetch_count field to trigger policy

Signed-off-by: Arnaldo Cesco <[email protected]>

apps/astarte_realm_management_api/priv/static/astarte_realm_management_api.yaml

@@ -1130,6 +1130,14 @@ components:
         retry_times:
           type: integer
           description: The amount of times an event will be requeued if delivery fails and the related handler has 'retry' strategy.
+        prefetch_count:
+          type: integer
+          default: 1
+          minimum: 1
+          maximum: 300
+          description: >-
+            The maximum number of messages that can be dequeued concurrently from the policy event queue.
+            Values higher than 1 trade off message ordering for throughput.
       required:
         - name
         - maximum_capacity

doc/pages/architecture/062-trigger_delivery_policies.md

@@ -51,14 +51,14 @@ A Trigger Delivery Policy is composed of:
   milliseconds an event is retained in the event queue. When an event expires, it is discarded from the event queue, even if it has not been
   delivered. This is optional.
 
+- Prefetch count: the maximum number of messages that can be dequeued concurrently from the event queue.
+  When prefetch count is set to 1, events are processed in order. Higher values allow for higher throughput by relaxing the ordering guarantee.
+  This fields maps to AMQP (RabbitMQ) [consumer prefetch count](https://www.rabbitmq.com/consumer-prefetch.html).
+  This is optional and defaults to 1.
 
 ## Known issues
 
-At the moment, Trigger Delivery Policies in general do not provide a guarantee of in-order delivery of events.
+At the moment, Trigger Delivery Policies do not provide a guarantee of in-order delivery of events if the Astarte Trigger Engine component
+is replicated (event when the policy prefetch count is set to 1), as data from event queues are delivered to consumers in a round-robin fashion.
 Note that, since previous Astarte versions (i.e. < 1.1) did not provide a retry mechanism for events, this change does
-not impact the expected behaviour if Trigger Delivery Policies are not used.
-
-- If the Astarte Trigger Engine service is replicated, events could be delivered out of order, as data from event queues are delivered to consumers in a round-robin fashion.
-- If the `retry` strategy is specified, in-order delivery cannot be guaranteed because a > 1 [consumer prefetch count](https://www.rabbitmq.com/consumer-prefetch.html) is being used.
-  This allows for higher throughput at the cost of consistency. In the future, the user will be allowed to choose between having an higher number of
-  events handled, but out of order, or ordered event handling at a lower rate.
+not impact the expected behaviour if Trigger Delivery Policies are not used.