Theia API Docs

Full API docs

Basic model of an Event and serializers and parsers for Event manipulation.

exception theia.model.EOFException

class theia.model.Event(id, source, timestamp=None, tags=None, content=None)

Event represnts some event occuring at a specfic time.

Each event is uniquely identified by its id in the whole system. An event comes from a source and always has an associated timestamp. The timestamp is usually generated by the event producer.

The content of an event is an arbitrary string. It may be a log file line, some generated record, readings from a sensor or other non-structured or structured text.

Each event may have a list of tags associcated with it. These are arbitrary strings and help in filtering the events.

An event may look like this

id:331c531d-6eb4-4fb5-84d3-ea6937b01fdd
timestamp: 1509989630.6749051
source:/dev/sensors/door1-sensor
tags:sensors,home,doors,door1
Door has been unlocked.

class theia.model.EventPreamble(total, header, content)

content

Alias for field number 2

header

Alias for field number 1

total

Alias for field number 0

class theia.model.Header(id=None, timestamp=None, source=None, tags=None)

Header represents an Event header. The header contains the following properties:

• id, unique identifier for the event. Usually UUIDv4.

• timestamp, floating point of the number of milliseconds since epoch

  start (1970-1-1T00:00:00.00).

• source, string, the name of the event source.
• tags, list of strings, arbitrary tags attached to the event.

The header is usefull and usually used when serializing/parsing an event.

Provides: 1. Atomic file write:

• May squash couple of events together
• It is asynchronous
• Small lock window when the rename of the file is done

2. Store Reader

• per store file

3. Store API:

• Store event
• Find event by ID
• Search Events by filter

class theia.naivestore.DataFile(path, start, end)

end

Alias for field number 2

path

Alias for field number 0

start

Alias for field number 1

class theia.naivestore.NaiveEventStore(root_dir, flush_interval=1000)

save(event)

Saves an event in the underlying storage. event - the Event object to store. This method is guaranteed to be atomic in the sense that the storage will either succeed to write and flush the event, or it will fail completely. In either case, the storage will be left in a consistent state. The method does not return any value.

search(ts_start, ts_end=None, flags=None, match=None, order='asc')

Performs a search for events matching events in the specified time range. ts_start - start of the time range. Matching events with timestamp bigger

or equal to this paramter will be returned.

ts_end - end of the time range. Matching events with timestamp smaller or

equal to this paramter will be returned

flags - events that have ALL of the flags will be returned. match - regular expression (restricted to a subset of the full regexp

support) to match the event content against.

order - ‘asc’ or ‘desc’, order in which the event are returned.

The operation returns an iterator over the matched (ordered) set of events. This operation satisfies the strict consistency.

class theia.naivestore.PeriodicTimer(interval, action)

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

exception theia.storeapi.EventNotFound

Raised if there is no event found in the underlying storage.

exception theia.storeapi.EventReadException

Represents an error while reading an event from the underlying storage.

class theia.storeapi.EventStore

EventStore is the basic interface for interaction with the events.

Main uses of this store are CRUD interactions with the events. The API provides powerful search through all events based on a time range and optionally additional flags. An instance of this class is thread-safe.

delete(event_id)

Deletes an event from the storage. event_id - the unique identifier of the event to be removed. The delete operation removes an event from the underlying storage. This operation is guaranteed to be atomic, the event will either be removed or it will fail completely. In either case the storage will be left in a consistent state. This method does not return any value.

get(event_id)

Looks up an event by its unique identifier.

event_id - the unique identifier of the event to be looked up. The storage will try to look up the event with the specified id:

• if the event is found, it will return an Event object
• the event is not found, raises an EventNotFound excepton.

Edge cases:

• If the event is being inserted AFTER the get(..) operation is invoked, there is NO guarantee that it will be fetched.
• If the event is being inserted BEFORE the get(..) operation is invoked, but that transaction is still not commited, the operaton will block until the write operation completes (or errors out) and the Event will be returned (if the write succeds) or will error out (if the write fails) - strict consistency

Note:

Some specific implementations may break the strict consistency if the underlying mechanism does not provide means to implement it. In those cases, the subclass must override this documentation and must document its exact for the above edge-cases.

save(event)

Saves an event in the underlying storage. event - the Event object to store. This method is guaranteed to be atomic in the sense that the storage will either succeed to write and flush the event, or it will fail completely. In either case, the storage will be left in a consistent state. The method does not return any value.

search(ts_start, ts_end=None, flags=None, match=None, order='asc')

Performs a search for events matching events in the specified time range. ts_start - start of the time range. Matching events with timestamp bigger

or equal to this paramter will be returned.

ts_end - end of the time range. Matching events with timestamp smaller or

equal to this paramter will be returned

flags - events that have ALL of the flags will be returned. match - regular expression (restricted to a subset of the full regexp

support) to match the event content against.

order - ‘asc’ or ‘desc’, order in which the event are returned.

The operation returns an iterator over the matched (ordered) set of events. This operation satisfies the strict consistency.

exception theia.storeapi.EventStoreException

General store error.

exception theia.storeapi.EventWriteException

Represents an error while writing an event to the underlying storage.

class theia.watcher.DirectoryEventHandler(handlers)

on_created(event)

Called when a file or directory is created.

Parameters:event (DirCreatedEvent or FileCreatedEvent) – Event representing file/directory creation.

on_deleted(event)

Called when a file or directory is deleted.

Parameters:event (DirDeletedEvent or FileDeletedEvent) – Event representing file/directory deletion.

on_modified(event)

Called when a file or directory is modified.

Parameters:event (DirModifiedEvent or FileModifiedEvent) – Event representing file/directory modification.

on_moved(event)

Called when a file or a directory is moved or renamed.

Parameters:event (DirMovedEvent or FileMovedEvent) – Event representing file/directory movement.