AIT Database API

Database Backends

AIT provides a general database abstraction class on top of which custom implementations can be written. AIT comes packaged with abstractions for InfluxDB (ait.core.db.InfluxDBBackend)and SQLite (ait.core.db.SQLiteBackend). You can inherit from the abstract base class ait.core.db.GenericBackend and implement your own database abstraction.

Warning

Note, the database-specific implementations of ait.core.db.GenericBackend will often require a custom field to be inserted to track time associated with a given packet or field value. In general, AIT-provided implementations use time for the name of this field. User defined Packet Fields should avoid using this name. If an implementation uses a different value it will be noted for that specific backend.

class ait.core.db.GenericBackend

Bases: object

Generic database backend abstraction

GenericBackend attempts to adequately abstract database operations into a small set of common methods. Not all methods will be useful for every database type and additional methods may need to be added for future database support.

Generally, the expected method functionality should be

connect

Connect to instance of the database via the backend driver. Five configuration options are respected by convention in AIT built-in backend implementations if they’re applicable to the given backend

database.host

The host to connect to. Defaults to localhost

database.port

The port to connect to. Defaults to technology specific value.

database.un

The username to use when connecting to the database. Defaults to a technology specific value.

database.pw

The password to use when connecting to the database. Defaults to a technology specific value.

database.dbname

The name of the database to create/use. Defaults to ait.

create

Create a database in the database instance

insert

Insert a packet into the database

query

Take a string defining a database query and return the results. The format of the results is backend specific.

query_packets

Query for packet types with optional filters.

close

Close the connection to the database instance and handle any cleanup

__init__()

Initialize self. See help(type(self)) for accurate signature.

close(**kwargs)

Close connection to the database instance.

connect(**kwargs)

Connect to a backend’s database instance.

create(**kwargs)

Create a database in the instance.

classmethod create_packet_from_result(packet_name, result)

Return an AIT Packet from a given database query result item

Creates and returns an AIT Packet denoted by packet_name with field values set given the contents of result. Values that are missing in the result will be defaulted in the returned Packet. Specific implementations will have caveats related to their backend and the limitations of the API.

insert(packet, time=None, **kwargs)

Insert a record into the database.

query(query, **kwargs)

Query the database instance and return results.

query_packets(packets=None, start_time=None, end_time=None, **kwargs)

Query the database instance for packet objects

Return all packets of the defined type from the data store, filtering over an optional time range. If no parameters are specified, this will return all data for all packet types as Packet objects.

Data Archive Plugin

The Data Archive Plugin, which is provided as part of AIT-Core at ait.core.server.plugins.DataArchive, uses the database backend APIs for archiving incoming data. It uses the ait.core.db.InfluxDBBackend by default, but a custom database can be implemented and used instead by specifying the datastore parameter in the plugin’s configuration.

plugins:
    - plugin:
        name: ait.core.server.plugins.DataArchive
        inputs:
            - log_stream
        datastore:
            ait.core.db.InfluxDBBackend

class ait.core.server.plugins.DataArchive(inputs, outputs, datastore='ait.core.db.InfluxDBBackend', **kwargs)

Bases: ait.core.server.plugin.Plugin

__init__(inputs, outputs, datastore='ait.core.db.InfluxDBBackend', **kwargs)

Attempts to connect to database backend. Plugin will not be created if connection fails.

Creates base packet dictionary for decoding packets with packet UIDs as keys and packet definitions as values.

Params:

inputs: list of names of input streams to plugin outputs: list of names of plugin output streams datastore: path to database backend to use **kwargs: any args required for connecting to backend database

Raises:

ImportError: raised if provided database backend does not exist or

cannot be imported

Exception: raised if the backened database cannot be connected to

for any reason

process(input_data, topic=None, **kwargs)

Splits tuple received from PacketHandler into packet UID and packet message. Decodes packet and inserts into database backend. Logs any exceptions raised.

Params:

input_data: message received from inbound stream through PacketHandler topic: name of inbound stream message received from **kwargs: any args required for connected to the backend