Document addition of prefetch_count field to trigger policy

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

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   trigger policies.
 - [astarte_trigger_engine] Add a customizable HTTP trigger redelivery mechanism via
   trigger policies (see [#554](https://github.com/astarte-platform/astarte/issues/554)).
+- [astarte_realm_management] Allow to change the prefetch count of a trigger delivery policy.
+  This feature is experimental (disable by default) and must be explicitly enabled using the
+  `REALM_MANAGEMENT_ALLOW_TRIGGER_POLICY_PREFETCH_COUNT` feature gate.
 
 ### Fixed
 - [astarte_appengine_api] Return empty data instead of error when querying `properties` interfaces 

doc/pages/architecture/062-trigger_delivery_policies.md

@@ -51,14 +51,16 @@ 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.
 
-
 ## Known issues
 
 At the moment, Trigger Delivery Policies in general do not provide a guarantee of in-order delivery of events.
-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 `retry` strategy is specified, in-order delivery cannot be guaranteed because a > 1 consumer prefetch count is being used. This allows for higher throughput at the cost of consistency.
+An experimental feature allows to set the maximum number of messages that can be dequeued concurrently from the event queue
+using AMQP (RabbitMQ) [consumer prefetch count](https://www.rabbitmq.com/consumer-prefetch.html). When prefetch count is set to 1, events are processed in order. Higher values allow for higher throughput by relaxing the ordering guarantee.
+This feature is disabled by default.
+
+Moreover, 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.
 
-- 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.
+Note that, since previous Astarte versions (i.e. < 1.1) did not provide a retry mechanism for events, both issues do
+not impact the expected behaviour if Trigger Delivery Policies are not used.