Contributing¶
Contributions to Caladrius are very welcome. The systems is designed to be extensible and the aim of the project is to provide a comprehensive suite of performance models to suit a wide range of situations.
Contributing new models¶
In order to construct a new model class for a particular DSPS you will need to
inherit from the appropriate base class. For example, to construct a new
traffic prediction model for Heron topologies you would inherit from the
HeronTrafficModel
class located in the
model/traffic/heron/base.py
module.
All traffic and topology performance model base classes in Caladrius inherit
from the Model
base class (see model/base.py
). This class has
two attributes that your new model class should override:
- name: This is the identification string used across the DSPS sub-domain of the Caladrius REST API to refer to this model. It should be distinct (within the sub-domain) from all other model names, e.g. stats-summary is unique within the
model/topology/heron
andmodel/traffic/heron
endpoints. If the Caladrius server is already running you can check the/model_info
endpoints of each DSPS sub-domain to see list of all registered models. Alternatively, once the model is added to the configuration file, Caladrius will check for model name uniqueness at startup and raise an exception of the name is a duplicate.- description: This is a short description of what the model does that is included in the information returned by the relevant
/model_info
endpoint.
The Model
classes constructor accepts 3 positional arguments that are
given to all models during start up:
- config: This is a dictionary parsed from the appropriate entry in the yaml configuration file. For example to specify configuration entries for a Heron topology performance model class you would add keys and values to the
heron.topology.models.config
map within the main Caladrius configuration file. Note that any entry in this map will be passed to all Heron topology models.- metrics_client: This is the metrics client the was configured for the particular DSPS that this model applies to. For example for Heron traffic and topology performance models this would be the metrics client specified by the
heron.metrics.client
configuration option.- graph_client: This the client connected to the Caladrius graph database and can be used to query topology structures and write new structures to the database (see Graph Database).
Your model constructor should accept the 3 positional arguments, any other
required setup arguments should be supplied via the config
dictionary.
You should consult the documentation for each DSPS’s base model base class for
details of the required methods and arguments. These are usually specific to
the DSPS and are supplied to the model by the relevant Resource
class
in the api/model
module.
Telling Caladrius about your model¶
Once you have a new model class it is easy to add this to Caladrius. The model
classes used by each endpoint are defined in the yaml
config file
passed to the app.py
script. An example configuration showing how to
specify the model classes used is shown in config/main.yaml.example
.
For example if you want to add a new traffic model for Heron topologies you would add the import path to you model class under the appropriate config heading:
heron.traffic.models:
- "caladrius.model.traffic.heron.stats_summary.StatsSummaryTrafficModel"
- "caladrius.model.traffic.heron.prophet.ProphetTrafficModel"
- "path.to.my.model.file.MyNewTrafficModel"
The config file uses absolute import paths for each class. Therefore, provided
that your source files are reachable on the PYTHONPATH
(with
__init__.py
in required subdirectories) your model does not need to be
within the Caladrius root folder. However, you will need to add the folder
above the Caladrius repo to your PYTHONPATH
to access the abstract base
classes and other utility features therein.
Once you have added your model to the config file it will be loaded by the REST
endpoint resource class and will be available at the appropriate endpoint. You
can query the model by supplying its name
attribute via the
model
parameter in the endpoint request (see REST API).
Contributing new metrics clients¶
Coming Soon…
Testing¶
Coming Soon…
Contributing Documentation¶
Coming Soon…