Package com.tccc.kos.core.service.analytics

Interface AnalyticsExporter

All Known Subinterfaces:
AnalyticsChannelExporter, AnalyticsDefaultChannelExporter
public interface AnalyticsExporter
An AnalyticsExporter is responsible for exporting analytics beans to a destination. Exporters are registered with a channel name and AnalyticsServer will call the exporter with beans to export based on events, timers and policy implemented in the core service. The exporter simply needs to export the data and indicate whether it was successful or not. If successful, the beans will be deleted from the device. If not successful (throws an exception), the beans will remain cached locally and will be sent to the exporter again in the future to retry the export.

It is possible to register an exporter to multiple channels. This allows a single exporter to send multiple distinct data streams without the need to create multiple exporter instances.

Every analytics channel should have an exporter as a channel represents a collection of persistent events. Without an exporter, the events simply accumulate until they are purged by size or date.

As it's common for an exporter to be bound to a single channel, the AnalyticsChannelExporter interface can be used to have KOS automatically autowire the exporter to the AnalyticsServer. This is a convenience interface that avoids the need to manually register an exporter. Furthermore, the AnalyticsDefaultChannelExporter interface can be used to create an exporter for the default KOS channel (AnalyticsServer.DEFAULT_CHANNEL). Keep in mind that only a single exporter can be registered per channel, so typically only the system agent should register for the default channel.

Since:
1.0
Version:
2024-03-19

  • Method Details

    • exportAnalytics

      void exportAnalytics(String channel, List<AnalyticsExportBean> beans) throws Exception
      Export the list of analytics beans associated with the specified channel. A successful return implies the analytics were sent and that the data should be purged from the device. Throw an exception to indicate that the export failed. This will preserve the data and trigger a periodic retry.
      Parameters:
      channel - the channel being exported
      beans - the beans containing analytic data
      Throws:
      Exception

    • getMaxAnalyticsSize

      default int getMaxAnalyticsSize(String channel)
      Return the max size of data the exporter can handle in a single export call. A value of zero indicates there is no constraint and the service defaults should be used.

      If set to a value smaller than the largest analytic event, the limit will be ignored to ensure that the event can be sent. This is generally used to avoid sending data larger than the accepted payload size on the server if there is a limit in place.

      Parameters:
      channel - the channel being exported

    • getMinAnalyticsSize

      default int getMinAnalyticsSize(String channel)
      Return the minimum amount of data the exporter requires. This can be used to reduce the amount of traffic the exporter generates by asking the analytics service to hold data even when priorities indicate that it should send.

      When set and an export attempt was aborted due to not enough data, standard priority timings no longer occur. The channel will be tagged as pending and a standard retry timer will be used until the data is exported.

      If analytics data is explicitly flushed, the minimum size is not enforced. This allows tools to force all analytic events to be sent when the need to examine data outweighs the cost of sending it.

      Parameters:
      channel - the channel being exported

    • getAnalyticsPriorityDelay

      default int getAnalyticsPriorityDelay(String channel, AnalyticsPriority priority)
      Given an analytics priority, return how long the service should hold data before triggering a call to export. A value of zero indicates that service defaults should be used.
      Parameters:
      channel - the channel being exported
      priority - the priority to return the delay for