Package org.agrona.concurrent.errors

Class DistinctErrorLog

java.lang.Object
org.agrona.concurrent.errors.DistinctErrorLog
public final class DistinctErrorLog extends Object
Distinct record of error observations. Rather than grow a record indefinitely when many errors of the same type are logged, this log takes the approach of only recording distinct errors of the same type and stack trace and keeping a count and time of observation so that the record only grows with new distinct observations.

The provided AtomicBuffer can wrap a memory-mapped file so logging can be out of process. This provides the benefit that if a crash or lockup occurs then the log can be read externally without loss of data.

Note: This class is threadsafe to be used from multiple logging threads.

The error records are recorded to the memory mapped buffer in the following format. 

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |R|                         Length                              |
  +-+-------------------------------------------------------------+
  |R|                    Observation Count                        |
  +-+-------------------------------------------------------------+
  |R|                Last Observation Timestamp                   |
  |                                                               |
  +-+-------------------------------------------------------------+
  |R|               First Observation Timestamp                   |
  |                                                               |
  +---------------------------------------------------------------+
  |                        Encoded Error                         ...
 ...                                                              |
  +---------------------------------------------------------------+

  • Field Details

    • LENGTH_OFFSET

      public static final int LENGTH_OFFSET
      Offset within a record at which the length field begins.
      See Also:

    • OBSERVATION_COUNT_OFFSET

      public static final int OBSERVATION_COUNT_OFFSET
      Offset within a record at which the observation count field begins.
      See Also:

    • LAST_OBSERVATION_TIMESTAMP_OFFSET

      public static final int LAST_OBSERVATION_TIMESTAMP_OFFSET
      Offset within a record at which the last observation timestamp field begins.
      See Also:

    • FIRST_OBSERVATION_TIMESTAMP_OFFSET

      public static final int FIRST_OBSERVATION_TIMESTAMP_OFFSET
      Offset within a record at which the first observation timestamp field begins.
      See Also:

    • ENCODED_ERROR_OFFSET

      public static final int ENCODED_ERROR_OFFSET
      Offset within a record at which the encoded exception field begins.
      See Also:

    • RECORD_ALIGNMENT

      public static final int RECORD_ALIGNMENT
      Alignment to be applied for record beginning.
      See Also:

  • Constructor Details

    • DistinctErrorLog

      public DistinctErrorLog(AtomicBuffer buffer, EpochClock clock)
      Create a new error log that will be written to a provided AtomicBuffer.

      The Charset with default to StandardCharsets.UTF_8 for encoding the exceptions.

      Parameters:
      buffer - into which the observation records are recorded.
      clock - to be used for time stamping records.

    • DistinctErrorLog

      public DistinctErrorLog(AtomicBuffer buffer, EpochClock clock, Charset charset)
      Create a new error log that will be written to a provided AtomicBuffer.
      Parameters:
      buffer - into which the observation records are recorded.
      clock - to be used for time stamping records.
      charset - for encoding the errors.

  • Method Details

    • buffer

      public AtomicBuffer buffer()
      Buffer the error log is written to.
      Returns:
      buffer the error log is written to.

    • charset

      public Charset charset()
      Charset used to encode errors.
      Returns:
      the Charset used to encode errors.

    • record

      public boolean record(Throwable exception)
      Record an observation of an error. If it is the first observation of this error type for a stack trace then a new entry will be created. For subsequent observations of the same error type and stack trace a counter and time of last observation will be updated.
      Parameters:
      exception - to be logged as an error observation.
      Returns:
      true if successfully logged otherwise false if insufficient space remaining in the log.