org.janusgraph.diskstorage.util

Class MetricInstrumentedStore

java.lang.Object

org.janusgraph.diskstorage.util.MetricInstrumentedStore

All Implemented Interfaces:

KeyColumnValueStore

public class MetricInstrumentedStore
extends Object
implements KeyColumnValueStore

This class instruments an arbitrary KeyColumnValueStore backend with Metrics. The cumulative runtime of, number of invocations of, and number of exceptions thrown by each interface method are instrumented with Metrics (using Timer, Counter, and Counter again, respectively). The Metric names are generated by calling MetricRegistry#name(backendClass, methodName, identifier), where methodName is the exact name of the method including capitalization, and identifier is "time", "calls", or "exceptions".

In addition to the three standard metrics, getSlice and getKeys have some additional metrics related to their return values. getSlice carries metrics with the identifiers "entries-returned" and "entries-histogram". The first is a counter of total Entry objects returned. The second is a histogram of the size of Entry lists returned. getKeys returns a RecordIterator that manages metrics for its methods.

This implementation does not catch any exceptions. Exceptions emitted by the backend store implementation are guaranteed to pass through this implementation's methods.

The implementation includes repeated try...catch boilerplate that could be reduced by using reflection to determine the method name and by delegating Metrics object handling to a common helper that takes a Callable closure, but I'm not sure that the extra complexity and potential performance hit is worth it.

Author:

Dan LaRocque

Field Summary

Fields

Modifier and Type	Field and Description
static List<String>	EVENT_NAMES
static String	M_ACQUIRE_LOCK
static String	M_CALLS
static String	M_CLOSE
static String	M_CONTAINS_KEY
static String	M_ENTRIES_COUNT
static String	M_ENTRIES_HISTO
static String	M_EXCEPTIONS
static String	M_GET_KEYS
static String	M_GET_PART
static String	M_GET_SLICE
static String	M_ITERATOR
static String	M_MUTATE
static String	M_TIME
static List<String>	OPERATION_NAMES

Fields inherited from interface org.janusgraph.diskstorage.keycolumnvalue.KeyColumnValueStore

NO_ADDITIONS, NO_DELETIONS

Constructor Summary

Constructors

Constructor and Description
MetricInstrumentedStore(KeyColumnValueStore backend, String metricsStoreName)

Method Summary

Modifier and Type	Method and Description
void	acquireLock(StaticBuffer key, StaticBuffer column, StaticBuffer expectedValue, StoreTransaction txh) Attempts to claim a lock on the value at the specified key and column pair.
void	close() Closes this store
KeyIterator	getKeys(KeyRangeQuery query, StoreTransaction txh) Returns a KeyIterator over all keys that fall within the key-range specified by the given query and have one or more columns matching the column-range.
KeyIterator	getKeys(SliceQuery query, StoreTransaction txh) Returns a KeyIterator over all keys in the store that have one or more columns matching the column-range.
String	getName() Returns the name of this store.
EntryList	getSlice(KeySliceQuery query, StoreTransaction txh) Retrieves the list of entries (i.e.
Map<StaticBuffer,EntryList>	getSlice(List<StaticBuffer> keys, SliceQuery query, StoreTransaction txh) Retrieves the list of entries (i.e.
void	mutate(StaticBuffer key, List<Entry> additions, List<StaticBuffer> deletions, StoreTransaction txh) Verifies acquisition of locks txh from previous calls to KeyColumnValueStore.acquireLock(StaticBuffer, StaticBuffer, StaticBuffer, StoreTransaction) , then writes supplied additions and/or deletions to key in the underlying data store.

Methods inherited from class java.lang.Object

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

Field Detail

M_CONTAINS_KEY

public static final String M_CONTAINS_KEY

See Also:

Constant Field Values

M_GET_SLICE

public static final String M_GET_SLICE

See Also:

Constant Field Values

M_MUTATE

public static final String M_MUTATE

See Also:

Constant Field Values

M_ACQUIRE_LOCK

public static final String M_ACQUIRE_LOCK

See Also:

Constant Field Values

M_GET_KEYS

public static final String M_GET_KEYS

See Also:

Constant Field Values

M_GET_PART

public static final String M_GET_PART

See Also:

Constant Field Values

M_CLOSE

public static final String M_CLOSE

See Also:

Constant Field Values

OPERATION_NAMES

public static final List<String> OPERATION_NAMES

M_CALLS

public static final String M_CALLS

See Also:

Constant Field Values

M_TIME

public static final String M_TIME

See Also:

Constant Field Values

M_EXCEPTIONS

public static final String M_EXCEPTIONS

See Also:

Constant Field Values

M_ENTRIES_COUNT

public static final String M_ENTRIES_COUNT

See Also:

Constant Field Values

M_ENTRIES_HISTO

public static final String M_ENTRIES_HISTO

See Also:

Constant Field Values

EVENT_NAMES

public static final List<String> EVENT_NAMES

M_ITERATOR

public static final String M_ITERATOR

See Also:

Constant Field Values

Constructor Detail

MetricInstrumentedStore

public MetricInstrumentedStore(KeyColumnValueStore backend,
                               String metricsStoreName)

Method Detail

getSlice

public EntryList getSlice(KeySliceQuery query,
                          StoreTransaction txh)
                   throws BackendException

Description copied from interface: KeyColumnValueStore

Retrieves the list of entries (i.e. column-value pairs) for a specified query.

Specified by:

getSlice in interface KeyColumnValueStore

Parameters:

query - Query to get results for

txh - Transaction

Returns:

List of entries up to a maximum of "limit" entries

Throws:

BackendException - when columnEnd < columnStart

See Also:

KeySliceQuery

getSlice

public Map<StaticBuffer,EntryList> getSlice(List<StaticBuffer> keys,
                                            SliceQuery query,
                                            StoreTransaction txh)
                                     throws BackendException

Description copied from interface: KeyColumnValueStore

Retrieves the list of entries (i.e. column-value pairs) as specified by the given SliceQuery for all of the given keys together.

Specified by:

getSlice in interface KeyColumnValueStore

Parameters:

keys - List of keys

query - Slicequery specifying matching entries

txh - Transaction

Returns:

The result of the query for each of the given keys as a map from the key to the list of result entries.

Throws:

BackendException

mutate

public void mutate(StaticBuffer key,
                   List<Entry> additions,
                   List<StaticBuffer> deletions,
                   StoreTransaction txh)
            throws BackendException

Description copied from interface: KeyColumnValueStore

Verifies acquisition of locks txh from previous calls to KeyColumnValueStore.acquireLock(StaticBuffer, StaticBuffer, StaticBuffer, StoreTransaction) , then writes supplied additions and/or deletions to key in the underlying data store. Deletions are applied strictly before additions. In other words, if both an addition and deletion are supplied for the same column, then the column will first be deleted and then the supplied Entry for the column will be added.

Implementations which don't support locking should skip the initial lock verification step but otherwise behave as described above.

Specified by:

mutate in interface KeyColumnValueStore

Parameters:

key - the key under which the columns in additions and deletions will be written

additions - the list of Entry instances representing column-value pairs to create under key, or null to add no column-value pairs

deletions - the list of columns to delete from key, or null to delete no columns

txh - the transaction to use

Throws:

PermanentLockingException - if locking is supported by the implementation and at least one lock acquisition attempted by KeyColumnValueStore.acquireLock(StaticBuffer, StaticBuffer, StaticBuffer, StoreTransaction) has failed

BackendException

acquireLock

public void acquireLock(StaticBuffer key,
                        StaticBuffer column,
                        StaticBuffer expectedValue,
                        StoreTransaction txh)
                 throws BackendException

Description copied from interface: KeyColumnValueStore

Attempts to claim a lock on the value at the specified key and column pair. These locks are discretionary.

If locking fails, implementations of this method may, but are not required to, throw PermanentLockingException. This method is not required to determine whether locking actually succeeded and may return without throwing an exception even when the lock can't be acquired. Lock acquisition is only only guaranteed to be verified by the first call to KeyColumnValueStore.mutate(StaticBuffer, List, List, StoreTransaction) on any given txh.

The expectedValue must match the actual value present at the key and column pair. If the true value does not match the expectedValue, the lock attempt fails and LockingException is thrown. This method may check expectedValue. The mutate() mutate is required to check it.

When this method is called multiple times on the same key, column, and txh, calls after the first have no effect.

Locks acquired by this method must be automatically released on transaction commit() or rollback().

Implementations which don't support locking should throw UnsupportedOperationException.

Specified by:

acquireLock in interface KeyColumnValueStore

Parameters:

key - the key on which to lock

column - the column on which to lock

expectedValue - the expected value for the specified key-column pair on which to lock (null means the pair must have no value)

txh - the transaction to use

Throws:

PermanentLockingException - the lock could not be acquired due to contention with other transactions or a locking-specific storage problem

BackendException

getKeys

public KeyIterator getKeys(KeyRangeQuery query,
                           StoreTransaction txh)
                    throws BackendException

Description copied from interface: KeyColumnValueStore

Returns a KeyIterator over all keys that fall within the key-range specified by the given query and have one or more columns matching the column-range. Calling KeyIterator.getEntries() returns the list of all entries that match the column-range specified by the given query.

This method is only supported by stores which keep keys in byte-order.

Specified by:

getKeys in interface KeyColumnValueStore

Returns:

Throws:

BackendException

getKeys

public KeyIterator getKeys(SliceQuery query,
                           StoreTransaction txh)
                    throws BackendException

Description copied from interface: KeyColumnValueStore

Returns a KeyIterator over all keys in the store that have one or more columns matching the column-range. Calling KeyIterator.getEntries() returns the list of all entries that match the column-range specified by the given query.

This method is only supported by stores which do not keep keys in byte-order.

Specified by:

getKeys in interface KeyColumnValueStore

Returns:

Throws:

BackendException

getName

public String getName()

Description copied from interface: KeyColumnValueStore

Returns the name of this store. Each store has a unique name which is used to open it.

Specified by:

getName in interface KeyColumnValueStore

Returns:

store name

See Also:

KeyColumnValueStoreManager.openDatabase(String)

close

public void close()
           throws BackendException

Description copied from interface: KeyColumnValueStore

Closes this store

Specified by:

close in interface KeyColumnValueStore

Throws:

BackendException