Get Started

• Time to Complete: 30 minutes

• Programming Language: Python 3

Prerequisites

• System Requirements

Docker Configuration

1. Run Docker as Non-Root: Follow the steps in Manage Docker as a non-root user.

2. Configure Proxy (if required):

   • Set up proxy settings for Docker client and containers as described in Docker Proxy Configuration.

   • Example ~/.docker/config.json:

     {
       "proxies": {
         "default": {
           "httpProxy": "http://<proxy_server>:<proxy_port>",
           "httpsProxy": "http://<proxy_server>:<proxy_port>",
           "noProxy": "127.0.0.1,localhost"
         }
       }
     }
     

   • Configure the Docker daemon proxy as per Systemd Unit File.

3. Enable Log Rotation:

   • Add the following configuration to /etc/docker/daemon.json:

     {
       "log-driver": "json-file",
       "log-opts": {
         "max-size": "10m",
         "max-file": "5"
       }
     }
     

   • Reload and restart Docker:

     sudo systemctl daemon-reload
     sudo systemctl restart docker
     

Clone source code

git clone https://github.com/open-edge-platform/edge-ai-libraries.git -b main
cd edge-ai-libraries/microservices/time-series-analytics/docker

Build Docker Image

Navigate to the application directory and build the Docker image:

docker compose build

Note

To include copyleft licensed sources when building the Docker image, use the below command:

docker compose build --build-arg COPYLEFT_SOURCES=true

Push Docker Images (Optional)

To push images to a Docker registry:

1. Update the following fields in edge-ai-libraries/microservices/time-series-analytics/docker/.env:

   • DOCKER_REGISTRY

   • DOCKER_USERNAME

   • DOCKER_PASSWORD

2. Push the images:

   docker login $DOCKER_REGISTRY
   docker compose push
   

Configuration Details

Note

For the default deployment, no need to change anything in the configuration.

Time Series Analytics Microservice uses the User Defined Function(UDF) deployment package(TICK Scripts, UDFs, Models) which is already built-in to the container image. By default, we have a simple UDF python script at edge-ai-libraries/microservices/time-series-analytics/udfs/temperature_classifier.py which does not use any model file for inferencing, it just does a simple check to filter the temperature points which are less than 20 OR greater than 25. The corresponding tick script is available at edge-ai-libraries/microservices/time-series-analytics/temperature_classifier.tick.

Directory (edge-ai-libraries/microservices/time-series-analytics/) details are as follows::

config.json

Key	Description	Example Value
udfs	Configuration for the User-Defined Functions (UDFs).	See below for details.

UDFs Configuration:

The udfs section specifies the details of the UDFs used in the task.

Key	Description	Example Value
name	The name of the UDF script.	"temperature_classifier"

Note

The maximum allowed size for config.json is 5 KB.

Alerts Configuration: <Optional>

The alerts section defines the settings for alerting mechanisms, such as MQTT protocol. Please note the MQTT broker needs to be available.

MQTT Configuration:

The mqtt section specifies the MQTT broker details for sending alerts.

Key	Description	Example Value
mqtt_broker_host	The hostname or IP address of the MQTT broker.	"ia-mqtt-broker"
mqtt_broker_port	The port number of the MQTT broker.	1883
name	The name of the MQTT broker configuration.	"my_mqtt_broker"

config/

kapacitor_devmode.conf would be updated as per the above config.json at runtime for usage.

udfs/

Contains the Python script to process the incoming data.

tick_scripts/

The TICKScript temperature_classifier.tick determines processing of the input data coming in. Mainly, has the details on execution of the UDF file and publishing of alerts.

Deploy with Docker Compose

Navigate to the application directory and run the Docker container:

docker compose up -d

Upload the temperature_classifier UDF

Run the following commands to package and upload the temperature_classifier UDF deployment package to the microservice:

cd edge-ai-libraries/microservices/time-series-analytics/
rm -f temperature_classifier.tar
tar cf temperature_classifier.tar udfs/ tick_scripts/
curl -X POST http://localhost:5000/udfs/package \
  -F "file=@temperature_classifier.tar"

Activate the UDF Deployment Package

Run the following command to apply the configuration and activate the uploaded UDF:

cd edge-ai-libraries/microservices/time-series-analytics/

curl -s -X POST http://localhost:5000/config \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d @config.json

Ingesting Temperature Data into the Time Series Analytics Microservice

Run the following script to ingest temperature data into the Time Series Analytics Microservice:

python3 -m venv venv
source venv/bin/activate
pip3 install -r simulator/requirements.txt
python3 simulator/temperature_input.py --port 5000

Verify the Temperature Classifier Results

Run the following commands to see the filtered temperature results:

docker logs -f ia-time-series-analytics-microservice

Accessing the Swagger UI

The Time Series Analytics Microservice provides an interactive Swagger UI at http://<host_ip>:5000/docs. Please refer API documentation.

Bring down the microservice

docker compose down -v

Troubleshooting

• Check container logs to catch any failures:

  docker logs -f ia-time-series-analytics-microservice
  docker logs -f ia-time-series-analytics-microservice | grep -i error
  
  # Debugging UDF errors if container is not restarting and providing expected results
  docker exec -it ia-time-series-analytics-microservice bash
  $ cat /tmp/log/kapacitor/kapacitor.log | grep -i error
  

Other Deployment options

• How to Deploy with Helm: Guide for deploying the application on a k8s cluster using Helm.

Supporting Resources

• Overview

• System Requirements