diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 855bc2e..ae50ad9 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -74,11 +74,9 @@ reviews: should be easily understandable for a wide audience, and we should avoid using any jargon or technical terms that are not commonly used. - **Anchor Links**: For headings that contain Unicode characters (emojis, special - characters) or backticks, use HTML anchor tags to ensure consistent linking behavior - across different platforms (GitHub, VS Code, etc.). Add a separate line with - `` before the heading, and update the table of contents to - reference this manual anchor. + Headings should not include special characters like emojis or backticks. The table + of contents should be generated with the `markdown-toc` tool, meaning that we should + use the `` and `` tags. - path: "**/*" instructions: >- This repository serves FixedIT Data Agent users across a spectrum from plug-and-play diff --git a/README.md b/README.md index 6eeeda0..0fed25f 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,17 @@ This repository provides resources for the [FixedIT Data Agent ACAP](https://fix ## Table of Contents -- [FixedIT Data Agent Examples](#fixedit-data-agent-examples) - - [Table of Contents](#table-of-contents) - - [📊 Server-side Dashboards](#server-side-dashboards) - - [System Monitoring with InfluxDB2 and Grafana](#system-monitoring-with-influxdb2-and-grafana) - - [🛠️ Edge Device Customization](#edge-device-customization) - - [Creating a Timelapse with AWS S3 Upload](#creating-a-timelapse-with-aws-s3-upload) + - +- [Server-side Dashboards](#server-side-dashboards) + - [System Monitoring with InfluxDB2 and Grafana](#system-monitoring-with-influxdb2-and-grafana) +- [Edge Device Customization Examples](#edge-device-customization-examples) + - [Hello, World!](#hello-world) + - [Creating a Timelapse with AWS S3 Upload](#creating-a-timelapse-with-aws-s3-upload) -## 📊 Server-side Dashboards + + +## Server-side Dashboards The [dashboard-deployments](./dashboard-deployments) directory contains visualization dashboards that work with the FixedIT Data Agent. Some work directly with the bundled configurations (just spin them up and start visualizing), while others can be used as-is or customized for your needs. Advanced users often combine edge device customization with dashboard modifications to visualize new data types. @@ -23,12 +24,35 @@ The dashboard stack in the image below is the system monitoring example for the ![Grafana Dashboard Overview](./dashboard-deployments/system-monitoring-influxdb2-flux-grafana/.images/laptop-with-grafana-for-monitoring.png) - - -## 🛠️ Edge Device Customization +## Edge Device Customization Examples Project implementation examples that show how to extend and customize the FixedIT Data Agent by uploading custom configuration files and scripts. This makes it easy to create tailored edge applications for Axis devices without starting from scratch using the AXIS ACAP SDK. +### Hello, World! + +The [Hello, World!](./project-hello-world) project demonstrates how to use the FixedIT Data Agent to upload custom config files and print messages to the standard output of the Telegraf process, which will be captured by the FixedIT Data Agent and displayed in the `Logs` tab. + +The following diagram shows the data flow of the "Hello, World!" project. For more details see the [README](./project-hello-world/README.md) in the `project-hello-world` directory. + +```mermaid +flowchart TD + X0["⚙️ Configuration Variables:
SYNC_INTERVAL_SECONDS, TELEGRAF_DEBUG"] --> X1 + X1["Telegraf Agent"] + + X2["Configuration override:
'interval'"] --> A2 + + A1["📥 Hello World Input 1
Global Interval"] --> C + A2["📥 Hello World Input 2
5s Override Interval"] --> C + C["📤 Output to stdout
JSON format"] + + style X0 fill:#f5f5f5,stroke:#9e9e9e + style X1 fill:#f5f5f5,stroke:#9e9e9e + style X2 fill:#f5f5f5,stroke:#9e9e9e + style A1 fill:#90EE90,stroke:#43a047 + style A2 fill:#90EE90,stroke:#43a047 + style C fill:#ffebee,stroke:#e53935 +``` + ### Creating a Timelapse with AWS S3 Upload The [Timelapse with AWS S3 Upload](./project-timelapse-s3) project demonstrates automated timelapse video creation using the FixedIT Data Agent. This solution captures images at regular intervals from an AXIS device and uploads them to AWS S3 with timestamped filenames, creating a chronological sequence perfect for timelapse generation. Perfect for construction sites, environmental monitoring, safety applications, or any scenario requiring periodic visual documentation. @@ -37,6 +61,8 @@ The [Timelapse with AWS S3 Upload](./project-timelapse-s3) project demonstrates _Click the image above to watch the timelapse video on YouTube_ +The following diagram shows the data flow of the "Timelapse with AWS S3 Upload" project. For more details see the [README](./project-timelapse-s3/README.md) in the `project-timelapse-s3` directory. + ```mermaid flowchart TD A["⏳ Wait
Sleep for interval"] --> B1["📥 VAPIX API Call
Fetch JPEG image"] diff --git a/project-hello-world/.images/bundled-configs.png b/project-hello-world/.images/bundled-configs.png new file mode 100644 index 0000000..9519123 Binary files /dev/null and b/project-hello-world/.images/bundled-configs.png differ diff --git a/project-hello-world/.images/config-page.png b/project-hello-world/.images/config-page.png new file mode 100644 index 0000000..51d63a8 Binary files /dev/null and b/project-hello-world/.images/config-page.png differ diff --git a/project-hello-world/.images/influxdb.png b/project-hello-world/.images/influxdb.png new file mode 100644 index 0000000..2d7b057 Binary files /dev/null and b/project-hello-world/.images/influxdb.png differ diff --git a/project-hello-world/.images/logs-page.png b/project-hello-world/.images/logs-page.png new file mode 100644 index 0000000..7621bce Binary files /dev/null and b/project-hello-world/.images/logs-page.png differ diff --git a/project-hello-world/.images/settings.png b/project-hello-world/.images/settings.png new file mode 100644 index 0000000..a782dd1 Binary files /dev/null and b/project-hello-world/.images/settings.png differ diff --git a/project-hello-world/README.md b/project-hello-world/README.md new file mode 100644 index 0000000..0f75858 --- /dev/null +++ b/project-hello-world/README.md @@ -0,0 +1,179 @@ +# Hello, World! + +This is a simple "Hello, world!" project that demonstrates how to use the [FixedIT Data Agent](https://fixedit.ai/products-data-agent/) to print messages to the standard output of the Telegraf process, which will be captured by the FixedIT Data Agent and displayed in the `Logs` tab. + +## How It Works + +This project defines two inputs that will run on an interval and produce a "Hello, World!" message. We make use of the `inputs.exec` plugin to run the `echo` command which will output the message. One input runs on the globally configured interval, and the other input runs on a more frequent interval. The `outputs.file` plugin is used to print all metrics to the standard output of the Telegraf process, which will be captured by the FixedIT Data Agent and displayed in the `Logs` tab. + +```mermaid +flowchart TD + X0["⚙️ Configuration Variables:
SYNC_INTERVAL_SECONDS, TELEGRAF_DEBUG"] --> X1 + X1["Telegraf Agent"] + + X2["Configuration override:
'interval'"] --> A2 + + A1["📥 Hello World Input 1
Global Interval"] --> C + A2["📥 Hello World Input 2
5s Override Interval"] --> C + C["📤 Output to stdout
JSON format"] + + style X0 fill:#f5f5f5,stroke:#9e9e9e + style X1 fill:#f5f5f5,stroke:#9e9e9e + style X2 fill:#f5f5f5,stroke:#9e9e9e + style A1 fill:#90EE90,stroke:#43a047 + style A2 fill:#90EE90,stroke:#43a047 + style C fill:#ffebee,stroke:#e53935 +``` + +Color scheme: + +- Light green: Input nodes / data ingestion +- Red: Output nodes / notifications +- Light gray: Configuration data + +## Why Choose This Approach? + +With the FixedIT Data Agent, you can create your own edge-based workflows and automations that run directly in the Axis devices. You can do this without knowing anything about the Axis ACAP SDK, C and C++ programming. This makes the edge available to a much wider audience of developers, system integrators and IT professionals. + +This simple project demonstrates how to configure different inputs with different intervals in the FixedIT Data Agent and how to propagate that data to the logs tab of the FixedIT Data Agent. It's a great starting point for understanding the basics of the agent's configuration system. + +## Table of Contents + + + +- [Compatibility](#compatibility) + - [AXIS OS Compatibility](#axis-os-compatibility) + - [FixedIT Data Agent Compatibility](#fixedit-data-agent-compatibility) +- [Quick Setup](#quick-setup) +- [Files](#files) +- [Configuration Details](#configuration-details) +- [Running the Example Together with the Default Config Files](#running-the-example-together-with-the-default-config-files) +- [Local Testing on Host](#local-testing-on-host) + - [Prerequisites](#prerequisites) + - [Test Commands](#test-commands) + + + +## Compatibility + +### AXIS OS Compatibility + +- **Minimum AXIS OS version**: No special requirements +- **Required tools**: None + +### FixedIT Data Agent Compatibility + +- **Minimum Data Agent version**: 1.1 +- **Required features**: `SYNC_INTERVAL_SECONDS` environment variable (added in FixedIT Data Agent v1.1). + +## Quick Setup + +1. **Disable the default config files** + +The FixedIT Data Agent comes with default config files for collecting system metrics and sending them to a database. Since we don't want to use those now, click the `Disable` button next to the "Bundled config files" +in the "Configuration" tab of the FixedIT Data Agent. + +![Disable bundled config files](.images/bundled-configs.png) + +2. **Upload and enable the `config.conf` file to the FixedIT Data Agent** + +Click the `Upload Config` button in the "Configuration" tab of the FixedIT Data Agent and upload the `config.conf` file. Then press the `Enable` button next to the `config.conf` file. + +![Upload config](.images/config-page.png) + +3. **Go to the "Logs" tab and verify the data** + +It might take a few seconds before Telegraf has been restarted with the new config file. After this, you should see the "Hello, World!" messages appearing as JSON in the Logs tab at two different intervals: + +- One message following the global interval (default 60 seconds) +- Another message every 5 seconds + +![Logs tab](.images/logs-page.png) + +4. **Reconfigure the FixedIT Data Agent variables:** + + The `config.conf` file is making use of the `SYNC_INTERVAL_SECONDS` and `TELEGRAF_DEBUG` environment variables. You can configure these in the "Settings" tab of the FixedIT Data Agent by going back to the camera web interface, going to the "Apps" section, pressing the three dots next to the FixedIT Data Agent and selecting "Settings". Try changing the "Sync interval seconds" to 10 seconds and the "Debug mode" to true. + + ![Plain settings](.images/settings.png) + + You should now see the global interval message appearing every 10 seconds instead. By scrolling down to the bottom of the logs where you find the internal Telegraf logs (by default printed to the "Standard Error" section), you will now see more verbose log messages such as `Wrote batch of 3 metrics in 4.322833ms` and `Buffer fullness: 0 / 10000 metrics`. This means that the metrics was successfully written to the output (`output.file` plugin) and that the buffer is now empty waiting for the next batch of metrics. + +## Files + +- `config.conf` - Combined configuration file containing both inputs and the output configuration + +## Configuration Details + +The project uses the following components: + +1. **Input Configurations** + - Global interval input: Uses the exec input plugin to run an echo command every `SYNC_INTERVAL_SECONDS` seconds. + - Override interval input: Same as above, but every 5 seconds regardless of the value of the `SYNC_INTERVAL_SECONDS` variable. + +2. **Output Configuration** + - Uses the file output plugin configured to write to stdout + - Data format is set to "json" + +3. **Data Flow** + - By default, all inputs are connected to all outputs. + +## Running the Example Together with the Default Config Files + +One of the steps in the quick setup was to disable the default config files. The reason for doing this is that the default behavior of Telegraf is to connect all inputs to all outputs. You can upload the same config file to the FixedIT Data Agent while having the bundled config files enabled. This will work assuming that you have already configured the InfluxDB variables according to the quick start guide for the FixedIT Data Agent. + +When doing this, you will see a lot of output in the "Logs" tab. This is because your new "output everything to stdout" plugin will consume all metrics from all configuration files and print all of them to stdout. The same is true for the new inputs that you created, the "Hello, World!" messages will also be sent to InfluxDB using the output defined in the bundled config files. + +![The data explorer in InfluxDB](.images/influxdb.png) + +All inputs are sent to all outputs (bundled plugins with blue border, new plugins with red border): + +```mermaid +flowchart TD + A1["📥 Hello World Input 1
Global Interval"] --> C + A2["📥 Hello World Input 2
5s Override Interval"] --> C + C["📤 Output to stdout
JSON format"] + + D1["📥 System metric 1"] --> C + D2["📥 System metric 2"] --> C + D3["📥 System metric ..."] --> C + + C2["📤 Output to InfluxDB"] + A1 --> C2 + A2 --> C2 + D1 --> C2 + D2 --> C2 + D3 --> C2 + + style A1 fill:#F1FCF1,stroke:#ff0000 + style A2 fill:#F1FCF1,stroke:#ff0000 + style D1 fill:#F1FCF1,stroke:#24a9e1 + style D2 fill:#F1FCF1,stroke:#24a9e1 + style D3 fill:#F1FCF1,stroke:#24a9e1 + style C fill:#FFF9FA,stroke:#ff0000 + style C2 fill:#FFF9FA,stroke:#24a9e1 +``` + +## Local Testing on Host + +You can test this project locally using Telegraf before deploying to your Axis device. + +### Prerequisites + +- Install Telegraf on your development machine + +### Test Commands + +First, set up the two environment variables (which are automatically set by the FixedIT Data Agent when running the project in the Axis device): + +```bash +export SYNC_INTERVAL_SECONDS="10" +export TELEGRAF_DEBUG="true" +``` + +Then run Telegraf with the configuration file: + +```bash +telegraf --config config.conf +``` + +You should now see some internal Telegraf logs on `stderr` and the JSON messages with the "Hello, World!" string appearing every now and then on `stdout`. diff --git a/project-hello-world/config.conf b/project-hello-world/config.conf new file mode 100644 index 0000000..c043322 --- /dev/null +++ b/project-hello-world/config.conf @@ -0,0 +1,78 @@ +# This section configures global settings for Telegraf. +# For more details about global configuration, read at: +# https://docs.influxdata.com/telegraf/v1/configuration/#agent-configuration +[agent] + +# The default interval at which metrics are collected. We make use of the +# ${SYNC_INTERVAL_SECONDS} environment variable which is set by the +# FixedIT Data Agent. This interval can be configured from the Apps tab +# by pressing the three dots next to the FixedIT Data Agent and selecting +# "Settings". The field is called "Sync interval seconds" and will be +# 60 seconds by default. +interval = "${SYNC_INTERVAL_SECONDS}s" + +# The debug mode (true/false) which controls the verbosity of Telegraf. +# This is set by the FixedIT Data Agent based on the "Debug mode" field +# in the "Settings" tab. Enabling this will produce more verbose logging +# from Telegraf which will be visible in the "Logs" tab of the FixedIT Data +# Agent. +debug = ${TELEGRAF_DEBUG} + + +# This section defines the first input. Every collection interval (controlled +# by the global 'interval' setting) this will produce a metric with the +# message "Hello, World! (Global Interval)". +# Read more about the exec input plugin here: +# https://github.com/influxdata/telegraf/tree/master/plugins/inputs/exec +[[inputs.exec]] + # Command to execute for metric collection + commands = ["echo 'Hello, World! (Global Interval)'"] + + # Data format to consume. This tells Telegraf which parser to use + # to interpret the output of the command. In this case, the output + # is a simple string that we want to collect as is. + data_format = "value" + data_type = "string" + + # Name override for the metric. By default, the metric name is set + # to the name of the plugin. We change it to something that better + # identifies this metric. + name_override = "hello_world_global" + +# This section defines another input. This input will also produce the +# same string on every collection interval, but we are overriding the +# global 'interval' and setting a more frequent interval for this input. +[[inputs.exec]] + # Command to execute for metric collection + commands = ["echo 'Hello, World! (5s Override Interval)'"] + + # Override global interval for more frequent execution + interval = "5s" + + # Data format to consume. This tells Telegraf which parser to use + # to interpret the output of the command. In this case, the output + # is a simple string that we want to collect as is. + data_format = "value" + data_type = "string" + + # Name override for the metric. By default, the metric name is set + # to the name of the plugin. We change it to something that better + # identifies this metric. + name_override = "hello_world_override" + + +# This section defines an output that will print all collected metrics +# to the standard output of the Telegraf process. The standard output +# is then collected by the FixedIT Data Agent and displayed in the "Logs" +# tab. +# Read more about the file output plugin here: +# https://github.com/influxdata/telegraf/tree/master/plugins/outputs/file +[[outputs.file]] + # Files to write to, "stdout" is a specially handled file. + files = ["stdout"] + + # Data format to output. We use JSON format since many people are + # familiar with it. Even though the metric is just a simple string, + # the output data will contain other metadata such as the timestamp, + # the name of the metric and tags automatically added by Telegraf. + data_format = "json"