Package com.variant.spi

Interface TraceEventFlusher

public interface TraceEventFlusher

Interface to be implemented by a user-supplied class, handling the writing of trace events to external storage. The implementation will be instantiated by Variant and is bound to a particular Variant schema. The implementation is defined by the /meta/flusher schema element. If no flusher is supplied in the schema, Variant will use the server-wide default, as provided by variant.event.flusher.class.name and variant.event.flusher.class.init configuration properties.

The implementation should expect Variant server to periodically call #flush(Collection) with a collection of FlushableTraceEvents, ready to be flushed to external storage. The frequency of this call and the likely number of events in the collection depend on the rate of event production and the following system properties:

  • variant.event.writer.buffer.size: The maximum number of pending events that can be held in memory by the event writer. (Default = 20,000). If the rate of event production is too high and the event flusher can't keep up, new events will be discarded with the appropriate error message in the server's log.
  • variant.event.writer.max.delay: The maximum delay, in seconds, a pending event will be held in memory. (Default = 30) If the rate of event production is too low, pending events may be stuck in memory for too long, risking being lost in the event of a server crash, or delaying a critical action further down the data pipeline. This property will force the event writer to flush pending events even if a large portion of the event buffer is still free.

An implementation must provide at least one public constructor:

  1. If no state initialization is required, i.e. the variant.event.flusher.class.init is null, the nullary constructor is sufficient.
  2. If you need to pass an initial state to the newly constructed event flusher object, the implementation must provide a constructor which takes the single argument of type com.typesafe.config.Config. Variant will invoke this constructor and pass it the parsed value of the variant.event.flusher.class.init property.

Variant creates a new instance of the implementation class for each schema where it is defined.

Since:
0.7

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    destroy()
    Called by the server, whenever this event flusher is being destroyed because the associated schema generation is being undeployed.
    void
    flush(FlushableTraceEvent[] events, int size)
    Called by the server whenever a new collection of trace events become available to be flushed out of memory.

  • Method Details

    • flush

      void flush(FlushableTraceEvent[] events, int size) throws Exception

      Called by the server whenever a new collection of trace events become available to be flushed out of memory.

      Parameters:
      events - An array of decorated trace event objects of type FlushableTraceEvent to be flushed to an external data sync. The array length is guaranteed to be as given by the variant.event.writer.flush.size, although only first size elements are usable.
      size - The number of elements in the events array. Most of the time size will be equal to the length of the events array. But whenever the events production is slow enough for the variant.event.writer.max.delay config parameter to become applicable, partial flushes may be trigger by the server.
      Throws:
      Exception
      Since:
      0.7

    • destroy

      default void destroy() throws Exception

      Called by the server, whenever this event flusher is being destroyed because the associated schema generation is being undeployed. Client code can use this callback to do housekeeping tasks such as closing database connections.

      Throws:
      Exception
      Since:
      0.10