Skip to content
Events Service

Monitor consumer lag

Consumer lag identifies the number of pending messages that a consumer is yet to consume. The Event Consumer Metrics API fetches the consumer lag count (which might not be real time). A large consumer lag count indicates that the consuming application isn’t keeping up with the volume of messages. To get real-time messages, consumers must maintain close to zero lag.

The Consumer Lag API is deployed across multiple regions — US, EU, AP, and AU in production. Consumers are advised to use the endpoint corresponding to their region.

Recommendations

  • Adjust your application’s polling rate in response to the number of pending messages ready for consumption.
  • The consuming application should define a normal/standard polling rate based on average event traffic. If the application falls behind, increase the standard poll rate by 2X or 3X. The Poll rate should be left at this higher rate until the lag is minimal or approximates to 0, implying that your application receives near real-time messages.
  • Consumers are advised not to adjust the polling rate for high traffic events (thousands of events per hour) until the lag has reached several hundred notifications. Often, network glitches can create low lag, and it is recommended not to respond to this arbitrary lag. A consistently increasing lag count indicates the need to increase polling frequency.

The consumer lag data is refreshed every 60 seconds. Fetching data before the next refresh will return stale data.

Events consumer metrics API

The Event Consumer Metrics API allows consumers to fetch the lag of their application, the publishing rate of the topic, and the state of their subscription (active or inactive). An inactive subscription indicates that the consumer has been inactive for 7 consecutive days. The event publish rate is the 15 minute average of the number of messages published by the producer per second and is updated every 15 minutes. This field helps consumers maintain their real-time polling rate based on the current publish rate. A huge increase or decrease in the publish rate should get reflected in the consumer polling rate.

Recommendations

  • Follow the recommendations mentioned in the preceding sections but adjust the polling rate based on the Event Publish Rate in 15-minute intervals (the metric is updated every 15 minutes). If your application falls behind in the polling queue, use the Consumer Lag Count to increase the polling rate.
  • Adjust your application polling rate based on consumer lag and producer rate at which messages are published.
  • Standard/normal consumer polling rate should be (1.3X of the producer rate)/(max poll per record).

To fetch event publisher rate:

  1. Go to Trimble Cloud Console.
  2. From the left menu click Home > Products.
  3. Search for the Events API Product.
  4. In the Version tab, select “Events-Consumer-Info-2.0”. Region-specific endpoints will be displayed.
  5. Click SUBSCRIBE to subscribe the consuming application (which is already subscribed to the Events Service).
  6. Use the Consumer Key and Secret to obtain the access token and start consuming the API. Ensure that the scope events-consumer-info-2-0 is included in the token request to enable access to the Event Consumer Metrics API.