com.salesforce.cantor

Interface Events

public interface Events

Events are multi-dimensional time series data. { timestamp = 1521860720690, dimensions = ['cpu'=0.5, 'mem'=0.13], metadata: ['ip'='10.0.137.21', 'data-center'='dc-1'], payload: "arbitrary byte array" } Implementations of this interface provide functionalities to store and retrieve

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Events.AggregationFunction Enum representing all available aggregation functions.
static class	Events.Event An event consists of a timestamp in milli-seconds, a map of string to string as metadata, and a map of string to double value as dimensions.

Method Summary

Modifier and Type	Method and Description
Map<Long,Double>	aggregate(String namespace, String dimension, long startTimestampMillis, long endTimestampMillis, Map<String,String> metadataQuery, Map<String,String> dimensionsQuery, int aggregateIntervalMillis, Events.AggregationFunction aggregationFunction) Get result of an aggregate function for all events in the given namespace, with timestamp between the start and end, and metadata and dimensions matching the given queries, for the given function and aggregated over an interval period in milli-seconds.
void	create(String namespace) Create a new namespace.
int	delete(String namespace, long startTimestampMillis, long endTimestampMillis, Map<String,String> metadataQuery, Map<String,String> dimensionsQuery) Delete all events in the given namespace, matching start/end timestamps and metadata/dimension query objects and return the number of events deleted.
void	drop(String namespace) Drop a namespace.
void	expire(String namespace, long endTimestampMillis) Expire all events with timestamp before the given end timestamp.
default List<Events.Event>	get(String namespace, long startTimestampMillis, long endTimestampMillis) Get all events in the given namespace, with timestamp between the start and end.
default List<Events.Event>	get(String namespace, long startTimestampMillis, long endTimestampMillis, boolean includePayloads) Get all events in the given namespace, with timestamp between the start and end.
default List<Events.Event>	get(String namespace, long startTimestampMillis, long endTimestampMillis, Map<String,String> metadataQuery, Map<String,String> dimensionsQuery) Get all events in the given namespace, with timestamp between the start and end, and metadata and dimensions matching the given queries.
List<Events.Event>	get(String namespace, long startTimestampMillis, long endTimestampMillis, Map<String,String> metadataQuery, Map<String,String> dimensionsQuery, boolean includePayloads) Get all events in the given namespace, with timestamp between the start and end, and metadata and dimensions matching the given queries.
Set<String>	metadata(String namespace, String metadataKey, long startTimestampMillis, long endTimestampMillis, Map<String,String> metadataQuery, Map<String,String> dimensionsQuery) Get distinct metadata values for the given metadata key for events in the given namespace, with timestamp between the start and end, metadata and dimensions matching the given queries.
Collection<String>	namespaces() Get list of all namespaces.
void	store(String namespace, Collection<Events.Event> batch) Store batch of events in the given namespace.
default void	store(String namespace, Events.Event event) Store an event object.
default void	store(String namespace, long timestampMillis, Map<String,String> metadata, Map<String,Double> dimensions) Store an event in the given namespace, with timestamp and optionally metadata and dimensions.
default void	store(String namespace, long timestampMillis, Map<String,String> metadata, Map<String,Double> dimensions, byte[] payload) Store an event in the given namespace, with timestamp and optionally metadata and dimensions, along with an arbitrary byte array as payload.

Method Detail

namespaces

Collection<String> namespaces()
                       throws IOException

Get list of all namespaces.

Returns:

collection of namespace identifiers

Throws:

IOException - exception thrown from the underlying storage implementation

create

void create(String namespace)
     throws IOException

Create a new namespace.

Parameters:

namespace - the namespace identifier

Throws:

IOException - exception thrown from the underlying storage implementation

drop

void drop(String namespace)
   throws IOException

Drop a namespace.

Parameters:

namespace - the namespace identifier

Throws:

IOException - exception thrown from the underlying storage implementation

store

default void store(String namespace,
                   long timestampMillis,
                   Map<String,String> metadata,
                   Map<String,Double> dimensions)
            throws IOException

Store an event in the given namespace, with timestamp and optionally metadata and dimensions.

Parameters:

namespace - the namespace identifier

timestampMillis - event's UTC timestamp in milli-seconds

metadata - metadata to be attached to the event

dimensions - dimensions to be attached to the event

Throws:

IOException - exception thrown from the underlying storage implementation

store

default void store(String namespace,
                   Events.Event event)
            throws IOException

Store an event object.

Parameters:

namespace - the namespace identifier

event - the event object

Throws:

IOException - exception thrown from the underlying storage implementation

store

default void store(String namespace,
                   long timestampMillis,
                   Map<String,String> metadata,
                   Map<String,Double> dimensions,
                   byte[] payload)
            throws IOException

Store an event in the given namespace, with timestamp and optionally metadata and dimensions, along with an arbitrary byte array as payload.

Parameters:

namespace - the namespace identifier

timestampMillis - event's UTC timestamp in milli-seconds

metadata - metadata to be attached to the event

dimensions - dimensions to be attached to the event

payload - payload to be attached to the event

Throws:

IOException - exception thrown from the underlying storage implementation

store

void store(String namespace,
           Collection<Events.Event> batch)
    throws IOException

Store batch of events in the given namespace.

Parameters:

namespace - the namespace identifier

batch - batch of events

Throws:

IOException - exception thrown from the underlying storage implementation

get

default List<Events.Event> get(String namespace,
                               long startTimestampMillis,
                               long endTimestampMillis)
                        throws IOException

Get all events in the given namespace, with timestamp between the start and end.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start UTC timestamp in milli-seconds

endTimestampMillis - end UTC timestamp in milli-seconds

Returns:

list of all events in the namespace with timestamp between start/end

Throws:

IOException - exception thrown from the underlying storage implementation

get

default List<Events.Event> get(String namespace,
                               long startTimestampMillis,
                               long endTimestampMillis,
                               boolean includePayloads)
                        throws IOException

Get all events in the given namespace, with timestamp between the start and end.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start UTC timestamp in milli-seconds

endTimestampMillis - end UTC timestamp in milli-seconds

includePayloads - flag to include payloads in the response or not; if false, event.getPayload() returns null

Returns:

list of all events in the namespace with timestamp between start/end

Throws:

IOException - exception thrown from the underlying storage implementation

get

default List<Events.Event> get(String namespace,
                               long startTimestampMillis,
                               long endTimestampMillis,
                               Map<String,String> metadataQuery,
                               Map<String,String> dimensionsQuery)
                        throws IOException

Get all events in the given namespace, with timestamp between the start and end, and metadata and dimensions matching the given queries.

A metadata query can match against an exact value for a key, or use wild-card character (i.e., '*'). For example: "host" => "localhost" matches with all events where the value of metadata with key "host" is exactly "localhost"; and the query "host" => "~prod-*-example" matches all events where the value is "like 'prod-*-example'". Note that wild-card queries have to start with "~", exact queries can optionally start with "=".

A dimensions query can match against exact values or less-than, less-than-or-equal, more-than, more-than-or-equal values for a set of dimensions. For example: "cpu" => ">=0.3" matches all events where the dimension with key "cpu" has a value higher than or equal to 0.3.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start UTC timestamp in milli-seconds

endTimestampMillis - end UTC timestamp in milli-seconds

metadataQuery - map of string to string representing a query to run against events metadata

dimensionsQuery - map of string to string representing a query to run against events dimensions

Returns:

list of all events in the namespace with timestamp between start/end and metadata/dimensions matching the query

Throws:

IOException - exception thrown from the underlying storage implementation

get

List<Events.Event> get(String namespace,
                       long startTimestampMillis,
                       long endTimestampMillis,
                       Map<String,String> metadataQuery,
                       Map<String,String> dimensionsQuery,
                       boolean includePayloads)
                throws IOException

Get all events in the given namespace, with timestamp between the start and end, and metadata and dimensions matching the given queries. A metadata query can match against an exact value for a key, or use wild-card character (i.e., '*'). For example: "host" => "localhost" matches with all events where the value of metadata with key "host" is exactly "localhost"; and the query "host" => "~prod-*-example" matches all events where the value is "like 'prod-*-example'". Note that wild-card queries have to start with "~", exact queries can optionally start with "=". A dimensions query can match against exact values or less-than, less-than-or-equal, more-than, more-than-or-equal values for a set of dimensions. For example: "cpu" => ">=0.3" matches all events where the dimension with key "cpu" has a value higher than or equal to 0.3.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start UTC timestamp in milli-seconds

endTimestampMillis - end UTC timestamp in milli-seconds

metadataQuery - map of string to string representing a query to run against events metadata

dimensionsQuery - map of string to string representing a query to run against events dimensions

includePayloads - flag to include payloads in the response or not; if false, event.getPayload() returns null

Returns:

list of all events in the namespace with timestamp between start/end and metadata/dimensions matching the query

Throws:

IOException - exception thrown from the underlying storage implementation

delete

int delete(String namespace,
           long startTimestampMillis,
           long endTimestampMillis,
           Map<String,String> metadataQuery,
           Map<String,String> dimensionsQuery)
    throws IOException

Delete all events in the given namespace, matching start/end timestamps and metadata/dimension query objects and return the number of events deleted.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start UTC timestamp in milli-seconds

endTimestampMillis - end UTC timestamp in milli-seconds

metadataQuery - map of string to string representing a query to run against events metadata

dimensionsQuery - map of string to string representing a query to run against events dimensions

Returns:

number of events deleted

Throws:

IOException - exception thrown from the underlying storage implementation

aggregate

Map<Long,Double> aggregate(String namespace,
                           String dimension,
                           long startTimestampMillis,
                           long endTimestampMillis,
                           Map<String,String> metadataQuery,
                           Map<String,String> dimensionsQuery,
                           int aggregateIntervalMillis,
                           Events.AggregationFunction aggregationFunction)
                    throws IOException

Get result of an aggregate function for all events in the given namespace, with timestamp between the start and end, and metadata and dimensions matching the given queries, for the given function and aggregated over an interval period in milli-seconds.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start timestamp in milli-seconds

endTimestampMillis - end timestamp in milli-seconds

metadataQuery - map of string to string representing a query to run against events metadata

dimensionsQuery - map of string to string representing a query to run against events dimensions

Returns:

map of timestamp to value of the aggregate function for all events in the namespace with timestamp between start/end and metadata/dimensions matching the query, bucketed for each interval

Throws:

IOException - exception thrown from the underlying storage implementation

metadata

Set<String> metadata(String namespace,
                     String metadataKey,
                     long startTimestampMillis,
                     long endTimestampMillis,
                     Map<String,String> metadataQuery,
                     Map<String,String> dimensionsQuery)
              throws IOException

Get distinct metadata values for the given metadata key for events in the given namespace, with timestamp between the start and end, metadata and dimensions matching the given queries.

Parameters:

namespace - the namespace identifier

startTimestampMillis - start timestamp in milli-seconds

endTimestampMillis - end timestamp in milli-seconds

metadataQuery - map of string to string representing a query to run against events metadata

dimensionsQuery - map of string to string representing a query to run against events dimensions

Returns:

map of timestamp to set of metadata values for all events in the namespace with timestamp between start/end and metadata/dimensions matching the query, bucketed for each interval

Throws:

IOException - exception thrown from the underlying storage implementation

expire

void expire(String namespace,
            long endTimestampMillis)
     throws IOException

Expire all events with timestamp before the given end timestamp.

Parameters:

endTimestampMillis - end timestamp in milli-seconds

Throws:

IOException - exception thrown from the underlying storage implementation