Package com.apple.foundationdb.record.provider.common

Class StoreTimer

  • Direct Known Subclasses:
    FDBStoreTimer
    @API(MAINTAINED)
public class StoreTimer
extends Object
    A context-wide accumulator of timing information.

    A store timer is a thread-safe record of call counts and nanosecond call times for various database operations, classified by an StoreTimer.Event. If a context has a store timer, various operations will record timing information in it. It is up to the caller to provide the necessary integration between this information and any system monitoring tools.

    • Constructor Detail

      • StoreTimer

        public StoreTimer()

    • Method Detail

      • checkEventNameUniqueness

        public static void checkEventNameUniqueness​(@Nonnull
                                            Stream<StoreTimer.Event> events)
        Confirm that there is no naming conflict among the event names that will be used.
        Parameters:
        events - a stream of events to check for duplicates

      • getDifference

        @Nonnull
public static StoreTimer getDifference​(@Nonnull
                                       StoreTimer timer,
                                       @Nonnull
                                       StoreTimerSnapshot timerSnapshot)
        Subtracts counts and times recorded by a snapshot of a timer returning a new timer representing the difference.

        Subtracting a snapshot of a timer from the original timer after subsequent operations have been performed and timed can provide useful metrics as to the cost of those subsequent operations.

        The timer must have been previously derived from the snapshot. Moreover, the timer should not have been reset after the snapshot was taken.

        Parameters:
        timer - timer to subtract the snapshot from
        timerSnapshot - snapshot of the provided timer
        Returns:
        a snapshot of the provided timer

      • getCounter

        @Nullable
public StoreTimer.Counter getCounter​(@Nonnull
                                     StoreTimer.Event event)
        Return the counter for a given event.
        Parameters:
        event - the event to have its counter retrieved
        Returns:
        the counter for the event or null if not counter exists

      • getCounter

        @Nullable
protected StoreTimer.Counter getCounter​(@Nonnull
                                        StoreTimer.Event event,
                                        boolean createIfNotExists)
        Return the counter value for a given event type. When createIfNotExists is true and a counter for the event did not previously exists, a zero-value counter will be created and returned, ensuring that you will never receive a null value; for StoreTimer.Aggregate events, the zero-value counter will be immutable, however for non-aggregate events the counter returned may be updated by the caller as necessary.
        Parameters:
        event - the event to have its counter retrieved
        createIfNotExists - if true the counter returned will be created if it did not already exist
        Returns:
        the counter for the event or null if there is no value present for the event and createIfNotExists was false

      • getTimeoutCounter

        @Nullable
public StoreTimer.Counter getTimeoutCounter​(@Nonnull
                                            StoreTimer.Event event)
        Return the timeout counter value for a given event type.
        Parameters:
        event - the event to have its counter retrieved
        Returns:
        the counter for the event or null if there is no value present for the event

      • geUUID

        @Nonnull
public UUID geUUID()
        Get the UUID of this timer.
        Returns:
        the UUID of this timer

      • record

        public void record​(Set<StoreTimer.Event> events,
                   long timeDifferenceNanos)
        Record the amount of time each element in a set of events took to run. This applies the same time difference to each event in the set.
        Parameters:
        events - the set of events being recorded
        timeDifferenceNanos - the time that the instrumented events took to run

      • record

        public void record​(StoreTimer.Event event,
                   long timeDifferenceNanos)
        Record the amount of time an event took to run. Subclasses can extend this to also update metrics aggregation or monitoring services.
        Parameters:
        event - the event being recorded
        timeDifferenceNanos - the time that instrumented event took to run

      • recordSinceNanoTime

        public void recordSinceNanoTime​(@Nonnull
                                StoreTimer.Event event,
                                long startTime)
        Record time since given time.
        Parameters:
        event - the event being recorded
        startTime - the System.nanoTime() when the event started

      • recordTimeout

        public void recordTimeout​(StoreTimer.Wait event,
                          long startTime)
        Record that some operation timed out.
        Parameters:
        event - the event that was waited for
        startTime - the System.nanoTime() when the event started

      • increment

        public void increment​(@Nonnull
                      Set<StoreTimer.Count> events)
        Record that each event in a set occurred once. This increments the counters associated with each event.
        Parameters:
        events - the set of events being recorded

      • increment

        public void increment​(@Nonnull
                      StoreTimer.Count event)
        Record that an event occurred once. This increments the counter associated with the given event.
        Parameters:
        event - the event being recorded

      • increment

        public void increment​(@Nonnull
                      Set<StoreTimer.Count> events,
                      int amount)
        Record that each event occurred one or more times. This increments the counters associated with each event by amount.
        Parameters:
        events - the set of events being recorded
        amount - the number of times each event occurred

      • increment

        public void increment​(@Nonnull
                      StoreTimer.Count event,
                      int amount)
        Record that an event occurred one or more times. This increments the counter associated with the given event by amount.
        Parameters:
        event - the event being recorded
        amount - the number of times the event occurred

      • getTimeNanos

        public long getTimeNanos​(StoreTimer.Event event)
        Get the total time spent for a given event.
        Parameters:
        event - the event to get time information for
        Returns:
        the total number of nanoseconds recorded for the event

      • getCount

        public int getCount​(StoreTimer.Event event)
        Get the total count for a given event.
        Parameters:
        event - the event to get count information for
        Returns:
        the total number times that event was recorded

      • getTimeoutTimeNanos

        public long getTimeoutTimeNanos​(StoreTimer.Event event)
        Get the total time spent for a given event that timed out.
        Parameters:
        event - the event to get time information for
        Returns:
        the total number of nanoseconds recorded for when the event timed out

      • getTimeoutCount

        public int getTimeoutCount​(StoreTimer.Event event)
        Get the total count of timeouts for a given event.
        Parameters:
        event - the event to get timeout information for
        Returns:
        the total number times that event was recorded as timed out

      • getAggregates

        @Nonnull
public Set<StoreTimer.Aggregate> getAggregates()
        Return the set of aggregates that this store timer can produce. This method is expected to be overridden by implementation in order to expose whichever aggregates they produce. Note that the aggregates that are returned are the complete set that are defined for the store timer, however it is possible that a returned aggregate may not have any of the underlying counters necessary to compute its value (see StoreTimer.Aggregate.compute(StoreTimer)).
        Returns:
        the set of aggregates that can be computed by this timer

      • getEvents

        public Collection<StoreTimer.Event> getEvents()
        Get all events known to this timer.
        Returns:
        a collection of events for which timing information was recorded

      • getTimeoutEvents

        public Collection<StoreTimer.Event> getTimeoutEvents()
        Get all events that have timed out.
        Returns:
        a collection of events for which timeout information was recorded

      • reset

        public void reset()
        Clear all recorded timing information.

      • instrument

        public <T> CompletableFuture<T> instrument​(StoreTimer.Event event,
                                           CompletableFuture<T> future,
                                           Executor executor)
        Add timing instrumentation to an asynchronous operation.
        Type Parameters:
        T - the type of the future
        Parameters:
        event - the event type to use to record timing
        future - a future that will complete when the operation is finished
        executor - an asynchronous executor to use to run the recording
        Returns:
        a new future that will be complete after also recording timing information

      • instrument

        public <T> CompletableFuture<T> instrument​(Set<StoreTimer.Event> events,
                                           CompletableFuture<T> future,
                                           Executor executor)
        Add timing instrumentation to an asynchronous operation.
        Type Parameters:
        T - the type of the future
        Parameters:
        events - the event types to use to record timing
        future - a future that will complete when the operation is finished
        executor - an asynchronous executor to use to run the recording
        Returns:
        a new future that will be complete after also recording timing information

      • instrument

        public <T> CompletableFuture<T> instrument​(StoreTimer.Event event,
                                           CompletableFuture<T> future,
                                           Executor executor,
                                           long startTime)
        Add timing instrumentation to an asynchronous operation.
        Type Parameters:
        T - the type of the future
        Parameters:
        event - the event type to use to record timing
        future - a future that will complete when the operation is finished
        executor - an asynchronous executor to use to run the recording
        startTime - the nanosecond time at which the operation started
        Returns:
        a new future that will be complete after also recording timing information

      • instrument

        public <T> CompletableFuture<T> instrument​(Set<StoreTimer.Event> events,
                                           CompletableFuture<T> future,
                                           Executor executor,
                                           long startTime)
        Add timing instrumentation to an asynchronous operation.
        Type Parameters:
        T - the type of the future
        Parameters:
        events - the event types to use to record timing
        future - a future that will complete when the operation is finished
        executor - an asynchronous executor to use to run the recording
        startTime - the nanosecond time at which the operation started
        Returns:
        a new future that will be complete after also recording timing information

      • instrument

        public <T> RecordCursor<T> instrument​(StoreTimer.Event event,
                                      RecordCursor<T> inner)
        Instrument an asynchronous cursor. Timing information is recorded for each invocation of the RecordCursor.onHasNext() asynchronous method.
        Type Parameters:
        T - the type of the cursor elements
        Parameters:
        event - the event type to use to record timing
        inner - the cursor to record timing information for
        Returns:
        a new cursor that returns the same elements and also records timing information