Getting Started

Define a Route

Routes allow telemetry 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

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 but cannot define new routes. Each route is an instance of a template; the list of templates currently supported is the following:

  • Apache Kafka
  • REST Endpoint

Routes can be defined using the Web Console through the Routing view. A route is defined by a set of parameters that need to be defined. When possible parameters come with a default value that can be changed in order to adapt to the specific use case.

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.