Configuration

To configure the development environment for the Screenly/Balena Prometheus Exporter, follow these step-by-step instructions to set up the necessary environment variables and ensure the Docker container runs properly.

Step 1: Set Environment Variables

The exporter requires a few environment variables to function correctly, particularly BALENA_TOKEN. This token is essential for authenticating requests to the Balena API.

To set the environment variable, use the following command in your terminal:

export BALENA_TOKEN="your_balena_api_token"

Replace your_balena_api_token with the token you obtained from your Balena account.

Additionally, there is an optional environment variable CRAWL_INTERVAL that you can configure to adjust how frequently the exporter polls the Balena API. The default value is set to 60 seconds. Set this variable as follows if you want to change it:

export CRAWL_INTERVAL=30

This command changes the polling interval to every 30 seconds.

Step 2: Build the Docker Image

Once you have configured the environment variables, proceed to build the Docker image. Use the following command:

docker build -t balena-exporter .

This command uses the Dockerfile in the current directory to build the image labeled balena-exporter.

Step 3: Run the Docker Container

After the image is successfully built, run the Docker container using the command below:

docker run -d \
--name balena-exporter \
-p 8000:8000 \
-e BALENA_TOKEN=${BALENA_TOKEN} \
-e CRAWL_INTERVAL=${CRAWL_INTERVAL} \
balena-exporter

This command runs the container in detached mode, names it balena-exporter, and maps port 8000 of the container to port 8000 of the host. It also passes the required environment variables into the container.

Step 4: Verify the Exporter is Running

To ensure that the exporter is running and accessible, you can use curl to send a request to the specified port:

curl http://localhost:8000

If the exporter is properly set up, you should see a response indicating that it is exposing metrics in Prometheus format.

Code References

In the main.py file, the following code snippets show how the environment variable BALENA_TOKEN is utilized and the default value for CRAWL_INTERVAL:

BALENA_TOKEN = os.getenv("BALENA_TOKEN", False)

def main():
    if not BALENA_TOKEN:
        print("Please set the BALENA_TOKEN environment variable")
        sys.exit(1)

    start_http_server(8000)
    REGISTRY.register(BalenaCollector())
    while True:
        time.sleep(int(CRAWL_INTERVAL))

These snippets ensure that the application retrieves the token from the environment and uses it for API requests.

Additionally, the collect method within the BalenaCollector class shows how metrics are gathered and exposed:

def collect(self):
    gauge = GaugeMetricFamily(
        "balena_devices_online", "Devices by status", labels=["fleet_name"]
    )

    for fleet_id in self.get_balena_fleets():
        fleet_name, device_online_count = self.get_fleet_metrics(str(fleet_id))

        gauge.add_metric([fleet_name], float(device_online_count))

    return [gauge]

This functionality collects the number of online devices and exposes this metric to Prometheus, providing valuable insights into fleet health.

The source for this information includes code from requirements.txt, README.md, and main.py.