org.agrona.concurrent.errors

Class DistinctErrorLog

java.lang.Object

org.agrona.concurrent.errors.DistinctErrorLog

public 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 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 Summary

Fields

Modifier and Type	Field and Description
static int	ENCODED_ERROR_OFFSET Offset within a record at which the encoded exception field begins.
static int	FIRST_OBSERVATION_TIMESTAMP_OFFSET Offset within a record at which the first observation timestamp field begins.
static int	LAST_OBSERVATION_TIMESTAMP_OFFSET Offset within a record at which the last observation timestamp field begins.
static int	LENGTH_OFFSET Offset within a record at which the length field begins.
static int	OBSERVATION_COUNT_OFFSET Offset within a record at which the observation count field begins.
static int	RECORD_ALIGNMENT Alignment to be applied for record beginning.

Constructor Summary

Constructors

Constructor and Description
DistinctErrorLog(AtomicBuffer buffer, EpochClock clock) Create a new error log that will be written to a provided AtomicBuffer.
DistinctErrorLog(AtomicBuffer buffer, EpochClock clock, Charset charset) Create a new error log that will be written to a provided AtomicBuffer.

Method Summary

Modifier and Type	Method and Description
AtomicBuffer	buffer() Buffer the error log is written to.
Charset	charset() Charset used to encode errors.
boolean	record(Throwable observation) Record an observation of an error.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LENGTH_OFFSET

public static final int LENGTH_OFFSET

Offset within a record at which the length field begins.

See Also:

Constant Field Values

OBSERVATION_COUNT_OFFSET

public static final int OBSERVATION_COUNT_OFFSET

Offset within a record at which the observation count field begins.

See Also:

Constant Field Values

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:

Constant Field Values

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:

Constant Field Values

ENCODED_ERROR_OFFSET

public static final int ENCODED_ERROR_OFFSET

Offset within a record at which the encoded exception field begins.

See Also:

Constant Field Values

RECORD_ALIGNMENT

public static final int RECORD_ALIGNMENT

Alignment to be applied for record beginning.

See Also:

Constant Field Values

Constructor Detail

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 Detail

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 observation)

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:

observation - to be logged as an error observation.

Returns:

true if successfully logged otherwise false if insufficient space remaining in the log.