Part 1: Logging metric data with Drivers

GARDNR requires Python 3.5 or higher.

Be sure to famliarize yourself with Object-oriented programming and Python classes before using GARDNR.

First, install GARDNR using pip:

$ pip install gardnr

The basic features of GARDNR are logging metrics to the database and exporting metric logs. To start logging a metric, you first must add the metric to the database, like so:

$ gardnr add metric air temperature hello-world

Next, a sensor driver can be added which can create logs for the metric hello-world. The sensor driver code must be implemented before it can be added to the database. GARDNR can generate empty templates of driver classes to be able to write them faster.

$ gardnr new sensor hello_world_sensor.py

There should now be a file called hello_world_sensor.py in your current directory. Open this file in your preferred code editor, it should contain:

from gardnr import drivers, logger, metrics


class Sensor(drivers.Sensor):
    """
    Add code to interface with physical or virtual sensors here.
    """

    def setup(self):
        """
        Add configuration here
        """

        # remove the next line and add code
        pass

    def read(self):
        """
        Example log:

        metrics.create_metric_log('my-metric', 42)


        Example image log:

        metrics.create_image_log(
            self.metric_name,
            image_bytes,
            extension=self.image_file_extension
        )
        """

        # remove the next line and add code
        pass

At the end of the file, remove the last two lines and insert:

metrics.create_metric_log('hello-world', 20)

Be sure to indent the line above by eight spaces so it is properly nested under the read method. Your hello_world_sensor.py file should now look like:

from gardnr import drivers, logger, metrics


class Sensor(drivers.Sensor):
    """
    Add code to interface with physical or virtual sensors here.
    """

    def setup(self):
        """
        Add configuration here
        """

        # remove the next line and add code
        pass

    def read(self):
        """
        Example log:

        metrics.create_metric_log('my-metric', 42)


        Example image log:

        metrics.create_image_log(
            self.metric_name,
            image_bytes,
            extension=self.image_file_extension
        )
        """

        metrics.create_metric_log('hello-world', 20)

Next, the sensor driver module must be added to GARDNR’s system. To do this, run the following command:

$ gardnr add driver hello-world-sensor hello_world_sensor:Sensor

The sensor driver module you just added to GARDNR can now be executed using the following command:

$ gardnr read

What running the command above does is create a log for our hello-world metric. Now we can add an exporter driver to GARDNR. Exporters allow logs to be sent to external locations.. In this case, the log will simply be printed to the console for demostration purposes. First, start with an empty exporter template:

$ gardnr new exporter hello_world_exporter.py

Next, open hello_world_exporter.py in your preferred code editor, it should contain:

from gardnr import constants, drivers, logger


class Exporter(drivers.Exporter):
    """
    Uncomment these to filter the types of metrics are logged.
    Either whitelist or blacklist must be used, not both.
    """
    # whitelist = [constants.IMAGE]
    # blacklist = [constants.IMAGE]

    def setup(self):
        """
        Add configuration here
        """

        # remove the next line and add code
        pass

    def export(self, logs):
        """
        Output the list of logs to an external destination.
        The log object has the following fields available.

        Log:
            id: str
            timestamp: datetime
            longitude: float
            latitude: float
            elevation: float
            value: blob
            metric:
                topic: str
                type: str
                manual: bool
        """
        for log in logs:
            # remove the next line and add code
            pass

At the end of the file, remove the last two lines and insert:

print(log.value)

Be sure to indent the line above by 12 spaces so it is properly nested under the for loop inside the export method. Your hello_world_sensor.py file should now look like:

from gardnr import constants, drivers, logger


class Exporter(drivers.Exporter):
    """
    Uncomment these to filter the types of metrics are logged.
    Either whitelist or blacklist must be used, not both.
    """
    # whitelist = [constants.IMAGE]
    # blacklist = [constants.IMAGE]

    def setup(self):
        """
        Add configuration here
        """

        # remove the next line and add code
        pass

    def export(self, logs):
        """
        Output the list of logs to an external destination.
        The log object has the following fields available.

        Log:
            id: str
            timestamp: datetime
            longitude: float
            latitude: float
            elevation: float
            value: blob
            metric:
                topic: str
                type: str
                manual: bool
        """
        for log in logs:
            print(log.value)

Next, the exporter driver module must be added to GARDNR’s system. To do this, run the following command:

$ gardnr add driver hello-world-exporter hello_world_exporter:Exporter

The exporter driver module you just added to GARDNR can now be executed using the following command:

$ gardnr write

You should now see 20 displayed in the console. Note, that if you were to run the above command again, nothing would be displayed. This is because metric logs are only exported once per exporter in the system.