1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>prometheus-client-c: Welcome to the documentation site for prometheus-client-c!</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">prometheus-client-c
 <span id="projectnumber">0.1.1</span>
</div>
<div id="projectbrief">Prometheus client for the C programming language</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Welcome to the documentation site for prometheus-client-c! </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#Introduction">Introduction</a></li>
<li class="level1"><a href="#Creating-and-Registering-Metrics">Creating and Registering Metrics</a></li>
<li class="level1"><a href="#Updating-Metric-Sample-Values">Updating Metric Sample Values</a></li>
<li class="level1"><a href="#Program-Initialization">Program Initialization</a></li>
<li class="level1"><a href="#Metric-Exposition-Over-HTTP">Metric Exposition Over HTTP</a></li>
<li class="level1"><a href="#Where-To-Go-From-Here">Where to Go From Here?</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="Introduction"></a>
Introduction</h1>
<p>prometheus-client-c is a small suite of Prometheus client libraries targeted for the C programming language. In this brief tutorial you will learn how to create and register metrics, update metric samples, and expose metrics over HTTP.</p>
<h1><a class="anchor" id="Creating-and-Registering-Metrics"></a>
Creating and Registering Metrics</h1>
<p>prometheus-client-c supports the following metric types:</p>
<ul>
<li><a href="https://prometheus.io/docs/concepts/metric_types/#counter">Counter</a></li>
<li><a href="https://prometheus.io/docs/concepts/metric_types/#gauge">Gauge</a></li>
<li><a href="https://prometheus.io/docs/concepts/metric_types/#histogram">Histogram</a></li>
</ul>
<p>To get started using one of the metric types, declare the metric at file scope. For example:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#incldue "prom.h"</span></div><div class="line"></div><div class="line"><a class="code" href="prom__counter_8h.html#a814ceed99a1d618334e51f4d0e160606">prom_counter_t</a> *my_counter;</div></div><!-- fragment --><p>Next, create a metric initialization function. You can create the metric and register it with the default metric collector registry in one chain of functions. A metric collector is responsible for collecting metrics and returning them. A metric collector registry is declared in global scope and contains metric collectors. More on this later...</p>
<p>To create a metric and register it with the default metric collector registry in one shot, you may chain the metric constructor into the prom_collector_registry_must_register_metric function. For example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> foo_metric_init(<span class="keywordtype">void</span>) {</div><div class="line"> my_counter = <a class="code" href="prom__collector__registry_8h.html#a113683f4e15ad9240a37ed2139ddaea6">prom_collector_registry_must_register_metric</a>(<a class="code" href="prom__counter_8h.html#a3302a9f1a3556d17af9af29729be2651">prom_counter_new</a>(<span class="stringliteral">"my_counter"</span>, <span class="stringliteral">"counts things"</span>, 0, NULL));</div><div class="line">}</div></div><!-- fragment --><p>The first argument to prom_counter_new is the counter name. The second argument is the counter description. The third argument is the number of metric labels. In this case, we will only have one metric sample for this metric so we pass 0 to specify that no labels will be used. The 4th argument is an array of strings storing the metric labels. Since we have none, we pass NULL. A call to foo_metric_init within the program's main function will initialize the metrics for the file we just created to the default prometheus metric collector registery called PROM_COLLECTOR_REGISTRY_DEFAULT</p>
<h1><a class="anchor" id="Updating-Metric-Sample-Values"></a>
Updating Metric Sample Values</h1>
<p>Now that we have a metric configured for creation and registration, we can update our metric within any of the functions of the file in which it was declared. For example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> my_lib_do_something(<span class="keywordtype">void</span>) {</div><div class="line"> printf(<span class="stringliteral">"I did a really important thing!\n"</span>);</div><div class="line"> <a class="code" href="prom__counter_8h.html#a315695fdd8b9b6fa59904bb2e35bfa35">prom_counter_inc</a>(my_counter, NULL);</div><div class="line">}</div></div><!-- fragment --><p>This function will increment the default metric sample for my_counter. Since we are not using metric labels, we pass NULL as the second argument.</p>
<h1><a class="anchor" id="Program-Initialization"></a>
Program Initialization</h1>
<p>At the start of the program's main function you need to do two things:</p>
<ul>
<li>Initialize the default metric collector registry:</li>
</ul>
<div class="fragment"><div class="line"><a class="code" href="prom__collector__registry_8h.html#aaf1421bd744f0dbbdaba7e64cec11f54">prom_collector_registry_default_init</a>();</div></div><!-- fragment --><ul>
<li>For each file containing prometheus metrics, call its corresponding metric initialization function</li>
</ul>
<div class="fragment"><div class="line">foo_metric_init()</div></div><!-- fragment --><p>After initialization is complete, you may proceed to do work and update your metrics.</p>
<h1><a class="anchor" id="Metric-Exposition-Over-HTTP"></a>
Metric Exposition Over HTTP</h1>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000001">Todo:</a></b></dt><dd>Describe how to use libpromhttp to expose metrics over HTTP</dd></dl>
<h1><a class="anchor" id="Where-To-Go-From-Here"></a>
Where to Go From Here?</h1>
<p>Take a look at the <a href="https://github.internal.digitalocean.com/pages/timeseries/prometheus-client-c/files.html">Files</a> tab in this documentation site for more information about the public API available to you. Also, you can take a look at the examples directory at the <a href="https://github.internal.digitalocean.com/timeseries/prometheus-client-c">Github repository</a> for inspiration. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
|
