Getting Started
Define a Route
Routes allow messages to be delivered to an external system (or destination). A route connects the Everyware Cloud messaging service to the destination with a one-way channel. A route is defined by several parameters which specify:
- the source of the messages
- the conversion (if any) that need to be applied to the messages
- the destination of the messages
- the retry policy and the error handling
When possible, parameters have a default values that can be adapted to the specific use case. Each route is an instance of a template; the templates currently supported are the following:
- Apache Kafka
- REST Endpoint
A route can also be temporary disabled if necessary. Using the forwardable flag it can be propagated to child accounts.
Forwarded Routes
Routes Scope
Routes can be defined only for level-one accounts (tenants) and the root account (tenant). Child accounts of level higher than one can inherit a route from their parent account through route forwarding feature but cannot define their own new routes.
Routes can be propagated to child accounts of any level in the hierarchy by setting the field Forwardable to true; check the configuration of the RouteService in the account Settings tab, if it's enabled then the forwarded rules are applied otherwise they will not.
The configuration of the rule applied to the child account is the same of the parent account included the destination. The Forwardable feature is implemented in such a way that account segregation is always enforced, that is, the route can only handle messages belonging to the child account.
Common Parameters for all Routes
The following are common Apache Camel parameters for all routes.
| Parameter Name | Description | Default |
|---|---|---|
| Maximum Redeliveries | Maximum number of redelivery attempts allowed. 0 is used to disable redelivery, and -1 will attempt redelivery forever until it succeeds. | 5 |
| Redelivery Delay | Fixed delay in milliseconds between each redelivery attempt. | 20 |
| Maximum Redelivery Delay | An upper bound in milliseconds for redelivery delay. This is used when you specify non-fixed-delays, such as exponential backoff, to avoid the delay growing too large. | 2000 |
| Message Domain | Defines the type of messages routed: - TELEMETRY. Messages published on topics with prefix like account_name/device_id/ - LOG. The log messages are published on topics with prefix like $LOG/account_name/device_id/ - LIFECYCLE. Messages published on topics with prefix like $EDC/account_name/device_id/MQTT/ | TELEMETRY |
If the message is not delivered successfully within the max number of delivery attempts (defined through the parameter Maximum Redeliveries), it is logged and discarded.
Retry attempts follow an exponential backoff algorithm that is always enabled. The Back Off Multiplier parameter value is set to 2 by default (not configurable). The Maximum Redeliveries value is used as highest exponent of the Back Off Multiplier parameter value, while the Redelivery Delay is used as the starting base delay.
Blacklisting Feature
This feature help you prevent a set of addresses, host, subnets to be used as destinations for the routes. To implement this, the feature uses a black list. When a message has to be routed to a destination the Route service checks the addresses contained in the blacklist, if the destination is contained in the list, the service will raise an error and the delivery to the destination will be blocked.
Usually, the black list will contain a list of subnets instead a long list of single IP addresses. If a specific address within one of the blacklisted subnets needs to be reached by a route, then it can be added to the white list. The service will check the white list before checking the black list, if a match is found then the delivery to the destination is allowed.
The black list as well as the white list need to be defined as container properties. Please check the section container properties for more informations regarding how to configure this feature and the default values.
Performance Notes
Message routes have an impact in terms of workload and resource usage on the Messaging Service component which handles the connections from the devices. The magnitude of the impact depends on several factors related to the specific business use case:
- the number of active routes
- the retry policy of each route
- the reliability of the infrastructure including the network and the external services that have to be reached by the routes.
Best Practice
In order to avoid possible consequences on the service level, take some time to fine tune the values of the retry policy parameters and the number of active routes in order to check that the final configuration of the routes works well for your use case.
Updated 4 months ago