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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
|
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Statistics - NNG Reference Manual (DRAFT)</title>
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="../theme/pagetoc.css">
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "light";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">NNG Reference Manual (DRAFT)</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<style>
.mdbook-alerts {
padding: 8px 16px;
margin-bottom: 16px;
border-left: 0.25em solid var(--mdbook-alerts-color);
}
.mdbook-alerts > *:first-child {
margin-top: 0;
}
.mdbook-alerts > *:last-child {
margin-bottom: 0;
}
.mdbook-alerts-title {
display: flex;
font-weight: 600;
align-items: center;
line-height: 1;
color: var(--mdbook-alerts-color);
text-transform: capitalize;
}
.mdbook-alerts-icon {
display: inline-block;
width: 1em;
height: 1em;
margin-right: 0.2em;
background-color: currentColor;
-webkit-mask: no-repeat center / 100%;
mask: no-repeat center / 100%;
-webkit-mask-image: var(--mdbook-alerts-icon);
mask-image: var(--mdbook-alerts-icon);
}
.mdbook-alerts-note {
--mdbook-alerts-color: rgb(9, 105, 218);
/* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-tip {
--mdbook-alerts-color: rgb(26, 127, 55);
/* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-important {
--mdbook-alerts-color: rgb(130, 80, 223);
/* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-warning {
--mdbook-alerts-color: rgb(154, 103, 0);
/* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-caution {
--mdbook-alerts-color: rgb(207, 34, 46);
/* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
}
</style>
<h1 id="statistics"><a class="header" href="#statistics">Statistics</a></h1>
<p>To facilitate debugging and support situations, the <em>NNG</em> library
provides for collection and reporting of numerous <a name="a001"></a>statistics.</p>
<p>These statistics are organized in a tree, and include both values,
and metadata describing the statistics. In order to be efficient and
minimize the impact of maintaining statistics, an explicit snapshot
of statistics must be taken, and that snapshot can then be processed.</p>
<div class="mdbook-alerts mdbook-alerts-note">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
note
</p>
<p>Statistics may be disabled by build-time configuration options,
in order to reduce program size and run-time overheads.</p>
</div>
<h2 id="statistic-structure"><a class="header" href="#statistic-structure">Statistic Structure</a></h2>
<pre><code class="language-c">typedef struct nng_stat nng_stat;
</code></pre>
<p>The <a name="a002"></a><code>nng_stat</code> structure represents a statistic, which is a single value
collected at a specific point in time.</p>
<p>This structure has meta-data describing the value, the value itself, and links
to any sibling or child statistics.</p>
<div class="mdbook-alerts mdbook-alerts-note">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
note
</p>
<p>The presence, name, and semantics of any given statistic are
subject to change at any time and without notice.</p>
</div>
<h2 id="collecting-a-snapshot"><a class="header" href="#collecting-a-snapshot">Collecting a Snapshot</a></h2>
<pre><code class="language-c">int nng_stats_get(nng_stat **statsp);
</code></pre>
<p>The <a name="a003"></a><code>nng_stats_get</code> function takes a snapshot of the statistics for
the system and returns it through the pointer <em>statsp</em>.
This function may return <a href="/api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if memory is exhausted, or <a href="/api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> if the statistics
support is not enabled in the build, but is otherwise expected to return zero.</p>
<h2 id="freeing-a-snapshot"><a class="header" href="#freeing-a-snapshot">Freeing a Snapshot</a></h2>
<pre><code class="language-c">void nng_stats_free(nng_stat *stat);
</code></pre>
<p>The <a name="a004"></a><code>nng_stats_free</code> function deallocates the snapshot referenced by <em>stat</em>.</p>
<div class="mdbook-alerts mdbook-alerts-important">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
important
</p>
<p>The <em>stat</em> must be root of the statistics tree, i.e. the value that was returned
through <em>statsp</em> using the function <code>nng_stats_get</code>.</p>
</div>
<h2 id="traversing-the-tree"><a class="header" href="#traversing-the-tree">Traversing the Tree</a></h2>
<pre><code class="language-c">const nng_stat *nng_stat_child(const nng_stat *stat);
const nng_stat *nng_stat_next(const nng_stat *stat);
const nng_stat *nng_stat_parent(const nng_stat *stat);
</code></pre>
<p>Traversing the tree of statistics is done using the <a name="a005"></a><code>nng_stat_child</code> and
<a name="a006"></a><code>nng_stat_next</code> functions.</p>
<p>The <code>nng_stat_child</code> function returns either the first child of <em>stat</em>,
or <code>NULL</code> if the <em>stat</em> has no children.</p>
<p>The <code>nng_stat_next</code> function returns the nearest sibling to the right of <em>stat</em>,
or <code>NULL</code> if <em>stat</em> has no more siblings to the right.</p>
<p>The <a name="a007"></a><code>nng_stat_parent</code> function returns the parent of <em>stat</em>, or <code>NULL</code> if
<em>stat</em> is the root of the statistics tree.</p>
<h2 id="finding-a-statistic"><a class="header" href="#finding-a-statistic">Finding a Statistic</a></h2>
<pre><code class="language-c">const nng_stat *nng_stat_find(const nng_stat *stat, const char *name);
const nng_stat *nng_stat_find_dialer(const nng_stat *stat, nng_dialer dialer);
const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener);
const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
</code></pre>
<p>Sometimes it is easiest to search for a specific statistic, matching by name,
or possibly to find the tree of statistics associated with a specific <a href="/TODO.html">socket</a>,
<a href="/TODO.html">dialer</a>, or <a href="/TODO.html">listener</a>.</p>
<p>The <code>nng_stat_find</code> functions are provided for this purpose.</p>
<p>The <a name="a008"></a><code>nng_stat_find</code> function returns the first statistic within the subtree of
statistics <em>stat</em>, with the given <em>name</em>. If no such statistic can be found, <code>NULL</code>
is returned.</p>
<p>The <a name="a009"></a><code>nng_stat_find_dialer</code>, <a name="a010"></a><code>nng_stat_find_listener</code>, and <a name="a011"></a><code>nng_stat_find_socket</code>
return the statistics subtree for the given dialer, listener, or socket object. If no such
statistic can be found, then they return <code>NULL</code>.
These functions should be provided the root of the statistic tree, in order to ensure
that they can find the desired object.</p>
<h2 id="statistic-identification"><a class="header" href="#statistic-identification">Statistic Identification</a></h2>
<pre><code class="language-c">const char *nng_stat_name(const nng_stat *stat);
const char *nng_stat_desc(const nng_stat *stat);
</code></pre>
<p>Every statistic has a name, returned by <a name="a012"></a><code>nng_stat_name</code>, and a description, returned by
<a name="a013"></a><code>nng_stat_desc</code>. Descriptions are human-readable text, which might be useful for display.</p>
<h2 id="statistic-type"><a class="header" href="#statistic-type">Statistic Type</a></h2>
<pre><code class="language-c">int nng_stat_type(const nng_stat *stat);
</code></pre>
<p>The function <a name="a014"></a><code>nng_stat_type</code> returns the type of the statistic.
The type of a statistic determines the nature of the value, and which
function can be used to obtain that value.</p>
<ul>
<li>
<p><a name="a015"></a><code>NNG_STAT_SCOPE</code>: <a name="NNG_STAT_SCOPE"></a>
The statistic does not carry any real value, but is
used for grouping related statistics together. This is a nexus in the
statistics tree.</p>
</li>
<li>
<p><a name="a016"></a><code>NNG_STAT_COUNTER</code>: <a name="NNG_STAT_COUNTER"></a>
The statistic is a counter that only increments.
Usually the change in the value of the statistic is more interesting
(as a rate) than the absolute value at any given time. The value should
be obtained using <a href="/api/stats.html#statistic-value"><code>nng_stat_value</code></a>.
The units will be given by the value returned from <a href="/api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p>
</li>
<li>
<p><a name="a017"></a><code>NNG_STAT_LEVEL</code>: <a name="NNG_STAT_LEVEL"></a>
The statistic represents a measured value which corresponds
to a specific value at a specific time. For example, this may represent the
number of messages currently queued for some operation, or the link speed
of a network interface. Most often the absolute value is more interesting
than the change in the value over time. Again the value can be obtained with
<a href="/api/stats.html#statistic-value"><code>nng_stat_value</code></a>, and any appropriate unit of measurement
with <a href="/api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p>
</li>
<li>
<p><a name="a018"></a><code>NNG_STAT_STRING</code>: <a name="NNG_STAT_STRING"></a>
The statistic is a string, such as a name. The value
of the string can be obtained with <a href="/api/stats.html#statistic-value"><code>nng_stat_string</code></a>.
The value of this string
will remain valid until the snapshot is deallocated with <a href="/api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>.</p>
</li>
<li>
<p><a name="a019"></a><code>NNG_STAT_BOOLEAN</code>: <a name="NNG_STAT_BOOLEAN"></a>
The value of the statistic is a truth value (either <code>true</code>
or <code>false</code>) and can be obtained with <a href="/api/stats.html#statistic-value"><code>nng_stat_bool</code></a>.</p>
</li>
<li>
<p><a name="a020"></a><code>NNG_STAT_ID</code>: <a name="NNG_STAT_ID"></a>
The value of the statistic is a numeric identifier, such as a socket
identifier. The value can be obtained with <a href="/api/stats.html#statistic-value"><code>nng_stat_value</code></a>,
and will be fixed for the life of the statistic.</p>
</li>
</ul>
<h2 id="statistic-value"><a class="header" href="#statistic-value">Statistic Value</a></h2>
<pre><code class="language-c">uint64_t nng_stat_value(const nng_stat *stat);
const char *nng_stat_string(const nng_stat *stat);
bool nng_stat_bool(const nng_stat *stat);
</code></pre>
<p>These functions return the value associated with the statistic.</p>
<p>The <a name="a021"></a><code>nng_stat_value</code> function returns the the numeric value for the statistic <em>stat</em>
of type <a href="/api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a>, <a href="/api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>, or <a href="/api/stats.html#NNG_STAT_ID"><code>NNG_STAT_ID</code></a>.
If <em>stat</em> is not one of these types, then it returns zero.</p>
<p>The <a name="a022"></a><code>nng_stat_bool</code> function returns the Boolean value (either <code>true</code> or <code>false</code>) for the statistic <em>stat</em> of
type <a href="/api/stats.html#NNG_STAT_BOOLEAN"><code>NNG_STAT_BOOLEAN</code></a>. If the statistics is not of this type, then it returns <code>false</code>.</p>
<p>The <a name="a023"></a><code>nng_stat_string</code> function returns a pointer to a string value for the statistic <em>stat</em>,
of type <a href="/api/stats.html#statistic-value"><code>NNG_STAT_STRING</code></a>. This string will remain valid until the snapshot that
<em>stat</em> was collected with is deallocated with <a href="/api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>. If the statistic
is not of type <code>NNG_STAT_STRING</code>, then <code>NULL</code> is returned.</p>
<h2 id="statistic-units"><a class="header" href="#statistic-units">Statistic Units</a></h2>
<pre><code class="language-c">int nng_stat_unit(const nng_stat *stat);
</code></pre>
<p>For statistics of type <a href="/api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a> or <a href="/api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>,
it is often useful to know what that quantity being reported measures.
The following units may be returned from <a name="a024"></a><code>nng_stat_unit</code> for such a statistic:</p>
<ul>
<li><a name="a025"></a><code>NNG_UNIT_NONE</code>: No unit is known or applies.</li>
<li><a name="a026"></a><code>NNG_UNIT_BYTES</code>: A count of bytes.</li>
<li><a name="a027"></a><code>NNG_UNIT_MESSAGES</code>: A count of messages.</li>
<li><a name="a028"></a><code>NNG_UNIT_MILLIS</code>: A count of milliseconds.</li>
<li><a name="a029"></a><code>NNG_UNIT_EVENTS</code>: A count of events of some type.</li>
</ul>
<h2 id="statistic-timestamp"><a class="header" href="#statistic-timestamp">Statistic Timestamp</a></h2>
<pre><code class="language-c">uint64_t nng_stat_timestamp(const nng_stat *stat);
</code></pre>
<p>Statistics have a timestamp indicating when the value was sampled,
obtained via <a name="a030"></a><code>nng_stat_timestamp</code>. The timestamp is given in
in milliseconds since a reference time, and the reference time used
here is the same reference time used for <a href="/api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p>
<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
<p><a href="/api/time.html#get-the-current-time"><code>nng_clock</code></a></p>
<!-- Symbol cross reference -->
<!-- HTTP -->
<!-- Macros -->
<!-- Protocols -->
<!-- Transports -->
<!-- Concept index -->
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../api/logging.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../api/errors.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../api/logging.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../api/errors.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
<script src="../theme/pagetoc.js"></script>
</div>
</body>
</html>
|
