Codebase Overview

The codebase for this project is written in Python, leveraging several key libraries for interacting with the Balena Cloud API and exporting metrics in Prometheus format.

Python Libraries

The requirements.txt file specifies the necessary Python libraries for the project:

• certifi (2024.7.4): Provides trusted certificates for verifying SSL connections, ensuring secure communication with the Balena Cloud API. Source: requirements.txt
• charset-normalizer (3.1.0): Facilitates proper character encoding handling, ensuring data integrity when working with the Balena Cloud API responses. Source: requirements.txt
• idna (3.4): Enables correct internationalized domain name (IDN) processing, essential for handling domain names in various languages. Source: requirements.txt
• prometheus-client (0.16.0): Provides the core functionality for exposing metrics in Prometheus format. Source: requirements.txt
• requests (2.31.0): Simplifies making HTTP requests to the Balena Cloud API, making it easier to retrieve data. Source: requirements.txt
• urllib3 (1.26.18): Provides a robust HTTP client library, offering enhanced functionality for handling network connections and data transfer. Source: requirements.txt

Environment Variables

The script utilizes two key environment variables:

• BALENA_TOKEN: Required for authentication with the Balena Cloud API. Source: README.md
• CRAWL_INTERVAL: Optional variable to set the interval (in seconds) between metric updates. Defaults to 60 seconds. Source: README.md

Running the Exporter

The exporter can be run as a Docker container:

$ docker build -t balena-exporter .
          $ docker run -d \
          --name balena-exporter \
          -p 8000:8000 \
          -e BALENA_TOKEN= \
          balena-exporter
          

Source: README.md

Code Structure

The core logic resides in the main.py file:

• main() Function:

  • Checks if the BALENA_TOKEN environment variable is set. If not, it exits the script. Source: main.py
  • Initializes the HTTP server for exposing metrics on port 8000.
  • Registers the BalenaCollector with the Prometheus registry.
  • Enters a loop that sleeps for the specified CRAWL_INTERVAL before collecting and updating metrics.

• BalenaCollector Class:

  • __init__: Initializes the collector instance (currently does nothing). Source: main.py
  • get_balena_fleets: Fetches all the fleets accessible by the user from the Balena Cloud API and returns a list of fleet IDs. Source: main.py
  • get_fleet_metrics: Retrieves online device count and fleet name for a given fleet ID from the Balena Cloud API. Source: main.py
  • collect: Generates a Gauge metric family (balena_devices_online) to represent the number of online devices per fleet. Source: main.py

Testing

The tests/test_exporter.py file contains unit tests for the BalenaCollector class:

• test_collect: Mocked test to verify the collect method’s functionality. Source: tests/test_exporter.py
• test_get_balena_fleets: Mocked test to validate the get_balena_fleets method. Source: tests/test_exporter.py

Dockerfile

The Dockerfile defines the Docker image build process:

• FROM python:3.10-alpine: Uses the Python 3.10 Alpine image as the base. Source: Dockerfile
• WORKDIR /usr/src/app: Sets the working directory. Source: Dockerfile
• COPY requirements.txt ./: Copies the requirements file. Source: Dockerfile
• RUN pip install --no-cache-dir -r requirements.txt: Installs the required Python libraries. Source: Dockerfile
• COPY main.py .: Copies the main script to the image. Source: Dockerfile
• USER nobody: Sets the user to nobody for security. Source: Dockerfile
• CMD [ "python", "./main.py" ]: Specifies the command to run when the container starts. Source: Dockerfile

Top-Level Directory Explanations

tests/ - This directory contains all the unit and integration tests for the project. It includes the __init__.py file which makes it a package, and specific test files like test_exporter.py.