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 NameDescriptionDefault
Maximum RedeliveriesMaximum number of redelivery attempts allowed. 0 is used to disable redelivery, and -1 will attempt redelivery forever until it succeeds.5
Redelivery DelayFixed delay in milliseconds between each redelivery attempt.20
Maximum Redelivery DelayAn 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 DomainDefines 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/
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.

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.