Zephyr Prometheus Example Application

This repository contains a Zephyr Prometheus example application. The main purpose of this repository is to serve as a reference on how to structure Zephyr-based applications. Some of the features demonstrated in this example are:

• Basic Zephyr application skeleton
• Zephyr workspace applications
• Zephyr modules
• West T2 topology
• Custom boards
• Custom devicetree bindings
• Out-of-tree drivers
• Out-of-tree libraries
• Example CI configuration (using GitHub Actions)
• Custom west extension
• Doxygen and Sphinx documentation boilerplate
• Zephyr prometheus client library

This repository is versioned together with the Zephyr main tree. This means that every time that Zephyr is tagged, this repository is tagged as well with the same version number, and the manifest entry for zephyr will point to the corresponding Zephyr tag. For example, the example-application v2.6.0 will point to Zephyr v2.6.0. Note that the main branch always points to the development branch of Zephyr, also main.

Getting Started

Before getting started, make sure you have a proper Zephyr development environment. Follow the official Zephyr Getting Started Guide.

Initialization

The first step is to initialize the workspace folder (my-workspace) where the example-application and all Zephyr modules will be cloned. Run the following command:

# initialize my-workspace for the example-application (main branch)
west init -m https://github.com/mustafaabdullahk/zephyr-prometheus-example.git --mr main prom-workspace
# update Zephyr modules
cd prom-workspace
west update

Tested boards

boards	status
stm32h747disco	OK

Building and running

To build the application, run the following command:

cd example-application
west build -b $BOARD app

where $BOARD is the target board.

You can use the custom_plank board found in this repository. Note that Zephyr sample boards may be used if an appropriate overlay is provided (see app/boards).

A sample debug configuration is also provided. To apply it, run the following command:

west build -b $BOARD app -- -DOVERLAY_CONFIG=debug.conf

Once you have built the application, run the following command to flash it:

west flash

example output:

*** Booting Zephyr OS build v3.6.0-3205-g950382cb1717 ***
[00:00:00.001,000] <inf> net_config: Initializing network
[00:00:00.001,000] <inf> net_config: Waiting interface 1 (0x240010f0) to be up...
Prometheus exposer listening on port 8080
[00:00:01.686,000] <inf> net_config: Interface 1 (0x240010f0) coming up
[00:00:01.686,000] <inf> net_config: Running dhcpv4 client...
Zephyr Example Application 1.0.0
[00:00:04.688,000] <inf> net_dhcpv4: Received: 10.5.194.51
[00:00:04.688,000] <inf> net_config: IPv4 address: 10.5.194.51
[00:00:04.688,000] <inf> net_config: Lease time: 258944 seconds
[00:00:04.688,000] <inf> net_config: Subnet: 255.255.0.0
[00:00:04.688,000] <inf> net_config: Router: 10.5.0.1
Handling connection
metric->name: test_counter
metric->type: 0
counter->value: 1
counter->num_labels: 2
Handling connection
metric->name: test_counter
metric->type: 0
counter->value: 1
counter->num_labels: 2

Testing

To execute Twister integration tests, run the following command:

west twister -T tests --integration

Documentation

A minimal documentation setup is provided for Doxygen and Sphinx. To build the documentation first change to the doc folder:

cd doc

Before continuing, check if you have Doxygen installed. It is recommended to use the same Doxygen version used in CI. To install Sphinx, make sure you have a Python installation in place and run:

pip install -r requirements.txt

API documentation (Doxygen) can be built using the following command:

doxygen

The output will be stored in the _build_doxygen folder. Similarly, the Sphinx documentation (HTML) can be built using the following command:

make html

The output will be stored in the _build_sphinx folder. You may check for other output formats other than HTML by running make help.