README.rst
1.. zephyr:code-sample:: prometheus
2 :name: Prometheus Sample
3 :relevant-api: http_service http_server tls_credentials prometheus
4
5 Implement a Prometheus Metric Server demonstrating various metric types.
6
7Overview
8--------
9
10This sample application demonstrates the use of the ``prometheus`` library.
11This library provides prometheus client library(pull method) implementation.
12By integrating this library into your code, you can expose internal metrics
13via an HTTP endpoint on your application's instance, enabling Prometheus to
14scrape and collect the metrics.
15
16Requirement
17-----------
18
19`QEMU Networking <https://docs.zephyrproject.org/latest/connectivity/networking/qemu_setup.html#networking-with-qemu>`_
20
21Building and running the server
22-------------------------------
23
24To build and run the application:
25
26.. zephyr-app-commands::
27 :zephyr-app: samples/net/prometheus
28 :board: <board to use>
29 :conf: <config file to use>
30 :goals: build
31 :compact:
32
33When the server is up, we can make requests to the server using HTTP/1.1.
34
35**With HTTP/1.1:**
36
37- Using a browser: ``http://192.0.2.1/metrics``
38
39See `Prometheus client library documentation
40<https://prometheus.io/docs/instrumenting/clientlibs/>`_.
41
42Metric Server Customization
43---------------------------
44
45The server sample contains several parameters that can be customized based on
46the requirements. These are the configurable parameters:
47
48- ``CONFIG_NET_SAMPLE_HTTP_SERVER_SERVICE_PORT``: Configures the service port.
49
50- ``CONFIG_HTTP_SERVER_MAX_CLIENTS``: Defines the maximum number of HTTP/2
51 clients that the server can handle simultaneously.
52
53- ``CONFIG_HTTP_SERVER_MAX_STREAMS``: Specifies the maximum number of HTTP/2
54 streams that can be established per client.
55
56- ``CONFIG_HTTP_SERVER_CLIENT_BUFFER_SIZE``: Defines the buffer size allocated
57 for each client. This limits the maximum length of an individual HTTP header
58 supported.
59
60- ``CONFIG_HTTP_SERVER_MAX_URL_LENGTH``: Specifies the maximum length of an HTTP
61 URL that the server can process.
62
63To customize these options, we can run ``west build -t menuconfig``, which provides
64us with an interactive configuration interface. Then we could navigate from the top-level
65menu to: ``-> Subsystems and OS Services -> Networking -> Network Protocols``.
66
67
68Prometheus Configuration
69------------------------
70
71.. code-block:: yaml
72
73 scrape_configs:
74 - job_name: 'your_server_metrics'
75 static_configs:
76 - targets: ['your_server_ip:your_server_port']
77 # Optional: Configure scrape interval
78 # scrape_interval: 15s
79
80Replace ``'your_server_metrics'`` with a descriptive name for your job,
81``'your_server_ip'`` with the IP address or hostname of your server, and
82``'your_server_port'`` with the port number where your server exposes Prometheus metrics.
83
84Make sure to adjust the configuration according to your server's setup and requirements.
85
86After updating the configuration, save the file and restart the Prometheus server.
87Once restarted, Prometheus will start scraping metrics from your server according
88to the defined scrape configuration. You can verify that your server's metrics are
89being scraped by checking the Prometheus targets page or querying Prometheus for
90metrics from your server.
91
92See `Prometheus configuration docs
93<https://prometheus.io/docs/prometheus/latest/configuration/configuration>`_.
94
