Docs: Add manual pages using ronn.

This adds several new manual pages to the project, ships them using `dist` and has a simple target to recreate the new roff files using the `ronn` utility: `make manpages`. These man pages are still very crude and contain the absolute minimum amount of information. I've attempted to cross link them as much as is reasonable. The telemetry API is documented in `telemetry(3)`. The important functions themselves are `linked` with a ref link that should make `man tm_create_record` (etc.) link to telemetry(3). I attempted to make this pass `make distcheck` and `make install` properly, but this should still be checked.
Validation for classification to ensure 2 slashes (#4 )
2026-09-01 11:15:51 +00:00 · 2016-12-08 17:47:25 -08:00 · 2016-09-02 00:43:48 -07:00 · 2016-08-17 21:09:33 +00:00 · 2016-08-17 21:08:24 +00:00 · 2016-08-17 13:42:39 -07:00
28 changed files with 785 additions and 23 deletions
@@ -14,6 +14,7 @@ DISTCHECK_CONFIGURE_FLAGS = \

 include $(top_srcdir)/build-aux/make/cflags.make
 include $(top_srcdir)/build-aux/make/ldflags.make
+include $(top_srcdir)/docs/local.mk
 include $(top_srcdir)/scripts/local.mk
 include $(top_srcdir)/src/local.mk
 include $(top_srcdir)/src/data/local.mk
@@ -30,9 +30,3 @@ Build dependencies
 - (optional) libsystemd, for syslog-style logging to the systemd journal, and
  socket/path activation of telemd by systemd.

-
-Generating HTML documentation
-=============================
-
-At toplevel, run 'doxygen docs/Doxyfile'. The documentation is generated in
-the docs/html/ directory.
@@ -0,0 +1,13 @@
+
+## Notes on manual pages
+
+The manual pages are generated using `ronn(1)`. To recreate them,
+run `make manpages` in the toplevel  folder. If you want to edit
+the documentation for upstream changes, make sure to edit the `*.md`
+files and not the shipped nroff output files.
+
+
+## Generating HTML documentation
+
+At toplevel, run 'doxygen docs/Doxyfile'. The documentation is
+generated in the docs/html/ directory.
@@ -0,0 +1,23 @@
+MANPAGES = \
+	docs/man/telemctl.1 \
+	docs/man/telemd.1 \
+	docs/man/telem-record-gen.1 \
+	docs/man/telemetry.3 \
+	docs/man/telemetrics.conf.5
+
+MANLINKS = \
+	docs/man/tm_create_record.3 \
+	docs/man/tm_send_record.3 \
+	docs/man/tm_set_config_file.3 \
+	docs/man/tm_set_payload.3
+
+manpages:
+	for MANPAGE in $(MANPAGES); do \
+		ronn --roff < $${MANPAGE}.md > $${MANPAGE}; \
+		ronn --html < $${MANPAGE}.md > $${MANPAGE}.html; \
+	done
+
+dist_man_MANS = \
+	$(MANPAGES) $(MANLINKS)
+
+# vim: filetype=automake tabstop=8 shiftwidth=8 noexpandtab
@@ -0,0 +1 @@
+*.html
@@ -0,0 +1,81 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEM\-RECORD\-GEN" "1" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelem\-record\-gen\fR \- Create custom telemetry record
+.
+.SH "SYNOPSIS"
+\fBtelem\-record\-gen\fR \fIoptions\fR
+.
+.SH "DESCRIPTION"
+Generate and attempt to send a telemetry record to \fBtelemd(1)\fR\. This program can be used to create a telemetry record from a shell script or from another program using e\.g\. \fBsystem()\fR\. The program connects to a local \fBtelemd(1)\fR daemon to spool the record for delivery to the actual collection service\.
+.
+.P
+The payload can be provided as standard input, as a file with the \fB\-\-payload\-file\fR option, or as a string argument with the \fB\-\-payload\fR option\. If neither the \fB\-\-payload\fR or \fB\-\-payload\-file\fR is provided, the payload is assumed to be on \fIstdin\fR\.
+.
+.P
+Each record is expected to have a class identifier, a record version number, and a severity level\. A class identifier is required to be provided\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help options\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print the program version\.
+.
+.TP
+\fB\-f\fR, \fB\-\-config\-file\fR \fIfile\fR
+Path to configuration file (not implemented yet)\.
+.
+.TP
+\fB\-s\fR, \fB\-\-severity\fR
+Severity level (1\-4) \- (default 1)\.
+.
+.TP
+\fB\-c\fR, \fB\-\-class\fR
+Classification \fBlevel_1\fR/\fBlevel_2\fR/\fBlevel_3\fR\.
+.
+.TP
+\fB\-p\fR, \fB\-\-payload\fR \fIpayload\fR
+Record body (max size = 8k)\.
+.
+.TP
+\fB\-P\fR, \fB\-\-payload\-file\fR \fIfile\fR
+File to read payload from\.
+.
+.TP
+\fB\-R\fR, \fB\-\-record\-version\fR \fIversion\fR
+Version number for format of payload (default 1)\.
+.
+.SH "RETURN VALUES"
+0 on success\. A non\-zero exit code indicates a failure occurred\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemd(1)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+
@@ -0,0 +1,70 @@
+telem-record-gen(1) -- Create custom telemetry record
+=====================================================
+
+## SYNOPSIS
+
+`telem-record-gen` <options>
+
+## DESCRIPTION
+
+Generate and attempt to send a telemetry record to `telemd(1)`. This
+program can be used to create a telemetry record from a shell script
+or from another program using e.g. `system()`. The program connects
+to a local `telemd(1)` daemon to spool the record for delivery to
+the actual collection service.
+
+The payload can be provided as standard input, as a file with the
+`--payload-file` option, or as a string argument with the `--payload`
+option. If neither the `--payload` or `--payload-file` is provided,
+the payload is assumed to be on <stdin>.
+
+Each record is expected to have a class identifier, a record version
+number, and a severity level. A class identifier is required to be
+provided.
+
+## OPTIONS
+ * `-h`, `--help`:
+   Show help options.
+
+ * `-V`, `--version`:
+   Print the program version.
+
+ * `-f`, `--config-file` <file>:
+   Path to configuration file (not implemented yet).
+
+ * `-s`, `--severity`:
+   Severity level (1-4) - (default 1).
+
+ * `-c`, `--class`:
+   Classification `level_1`/`level_2`/`level_3`.
+
+ * `-p`, `--payload` <payload>:
+   Record body (max size = 8k).
+
+ * `-P`, `--payload-file` <file>:
+   File to read payload from.
+
+ * `-R`, `--record-version` <version>:
+   Version number for format of payload (default 1).
+
+## RETURN VALUES
+
+0 on success. A non-zero exit code indicates a failure occurred.
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemd(1)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/
@@ -0,0 +1,58 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEMCTL" "1" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelemctl\fR \- Telemetry service administration tool
+.
+.SH "SYNOPSIS"
+\fBtelemctl\fR
+.
+.P
+\fB/etc/telemetrics/opt\-out\fR
+.
+.SH "DESCRIPTION"
+Control actions for telemetry services\. The command can be used to start, restart, or stop \fBtelemd(1)\fR, or to opt\-in or opt\-out of telemetry delivery of records to a central telemetry service\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fBstart\fR|\fBstop\fR|\fBrestart\fR
+Starts, stops or restarts all running telemetry services\.
+.
+.TP
+\fBopt\-in\fR
+Opts in to telemetry, and starts telemetry services\. The opt\-out file \fB/etc/telemetrics/opt\-out\fR is removed\.
+.
+.TP
+\fBopt\-out\fR
+Opts out of telemetry, and stops telemetry services\. The opt\-out file \fB/etc/telemetrics/opt\-out\fR is created\.
+.
+.SH "RETURN VALUES"
+0 on success\. A non\-zero exit code indicates a failure occurred\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemd(1)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+
@@ -0,0 +1,49 @@
+telemctl(1) -- Telemetry service administration tool
+====================================================
+
+## SYNOPSIS
+
+`telemctl`
+
+`/etc/telemetrics/opt-out`
+
+## DESCRIPTION
+
+Control actions for telemetry services. The command can be used to start,
+restart, or stop `telemd(1)`, or to opt-in or opt-out of telemetry delivery
+of records to a central telemetry service.
+
+## OPTIONS
+
+ * `start`|`stop`|`restart`:
+   Starts, stops or restarts all running telemetry services.
+
+ * `opt-in`: 
+   Opts in to telemetry, and starts telemetry services. The opt-out file
+   `/etc/telemetrics/opt-out` is removed.
+
+ * `opt-out`: 
+   Opts out of telemetry, and stops telemetry services. The opt-out file
+   `/etc/telemetrics/opt-out` is created.
+
+## RETURN VALUES
+
+0 on success. A non-zero exit code indicates a failure occurred.
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemd(1)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/
@@ -0,0 +1,55 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEMD" "1" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelemd\fR \- Telemetry client service
+.
+.SH "SYNOPSIS"
+\fBtelemd\fR \fIflags\fR \fB/etc/telemetrics/telemetrics\.conf\fR
+.
+.SH "DESCRIPTION"
+The \fBtelemd\fR program delivers locally generated telemetry records to a remote telemetry service\. Telemetry data can be in any format, and is relayed as\-is\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-f\fR, \fB\-\-config_file\fR [\fIfile\fR]
+Configuration file\. This overides the other parameters\.
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display this help message\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print the program version\.
+.
+.SH "EXIT STATUS"
+0 when no errors occurred\. A non\-zero exit status indicates a failure occurred\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemetry(3)\fR \fBtelemetrics\-client\.conf(5)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+
@@ -0,0 +1,47 @@
+telemd(1) -- Telemetry client service
+=====================================
+
+## SYNOPSIS
+
+`telemd` <flags> 
+`/etc/telemetrics/telemetrics.conf`
+
+## DESCRIPTION
+
+The `telemd` program delivers locally generated telemetry records to a remote
+telemetry service. Telemetry data can be in any format, and is relayed as-is.
+
+## OPTIONS
+
+  * `-f`, `--config_file` [<file>]:
+    Configuration file. This overides the other parameters.
+
+  * `-h`, `--help`:
+    Display this help message.
+
+  * `-V`, `--version`:
+    Print the program version.
+
+
+## EXIT STATUS
+
+0 when no errors occurred. A non-zero exit status indicates a failure occurred.
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemetry(3)`
+`telemetrics-client.conf(5)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/
@@ -0,0 +1,105 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEMETRICS\.CONF" "5" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelemetrics\.conf\fR \- Telemetry service configuration file
+.
+.SH "SYNOPSIS"
+.
+.nf
+
+/etc/telemetrics/telemetrics\.conf
+/usr/share/defaults/telemetrics/telemetrics\.conf
+.
+.fi
+.
+.SH "DESCRIPTION"
+This file contains configuration parameters for the \fBtelemd(1)\fR telemetry service daemon\. The daemon reads this file at startup if it exists\.
+.
+.SH "SYNTAX"
+The configuration file contains \fBkey=value\fR pairs, formatted as plain text, one option per line\. Comments can be added by preceding them with the \fB#\fR character\. All configuration options should be in a section marked with \fB[settings]\fR\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fBserver\fR=\fIurl\fR
+Server URL including protocol designator\.
+.
+.TP
+\fBsocket_path\fR=\fIpath\fR
+Path to the socket that \fBtelemd\fR will listen on\.
+.
+.TP
+\fBcainfo\fR=\fIpath\fR
+Certificate file to use for validation of SSL endpoint\.
+.
+.TP
+\fBtidheader\fR=\fIheader\fR
+Telemetry ID in header format, usually \fBtidheader=X\-Telemetry\-TID:<uuid>\fR post header used to group records in ingestion service, which may be ingesting for more than one set of clients\. Can be set to any string\.
+.
+.TP
+\fBrecord_expiry\fR=\fIminutes\fR
+Record expiry time in minutes\.
+.
+.TP
+\fBspool_dir\fR=\fI\fBdir\fR\fR
+Local spool directory used to store records being processed\.
+.
+.TP
+\fBspool_max_size\fR=\fIkB\fR
+maximum size of the spool directory in kB\. A value of \fB\-1\fR indicates no limit\. The block size of the files in this directory is considered, and not the actual size of the record itself\.
+.
+.TP
+\fBspool_process_time\fR=\fIseconds\fR
+Time in seconds for processing spool\. Valid range: 120\.\.3600\. Values outside this range are clamped\.
+.
+.TP
+\fBrate_limit_enabled\fR=\fI\fBtrue\fR|\fBfalse\fR\fR
+Enable rate limiting\. If this is set to false then all rate\-limiting disabled\. It is possible to disable each rate\-limit individually below\.
+.
+.TP
+\fBrecord_burst_limit\fR=\fIlimit\fR
+Rate limiting record burst limit\. Valid Range: 0\.\.\fBINT_MAX\fR, \-1 = disabled\.
+.
+.TP
+\fBrecord_window_length\fR=\fIminutes\fR
+Rate limiting record window length in minutes\. Valid Range: 0\.\.59\.
+.
+.TP
+\fBbyte_burst_limit\fR=\fIlimit\fR
+Rate limiting byte burst limit\. Valid Range: 0\.\.\fBINT_MAX\fR, \-1 = disabled\.
+.
+.TP
+\fBbyte_window_length\fR=\fIminutes\fR
+Rate limiting byte window length in minutes\. Valid Range: 0\.\.59\.
+.
+.TP
+\fBrate_limit_strategy\fR=\fIstrategy\fR
+Rate limit strategy \- what to do with record if rate\-limiting prevents delivery over network\. Valid stategies: \fBspool\fR, \fBdrop\fR\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemd(1)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0
+
@@ -0,0 +1,92 @@
+telemetrics.conf(5) -- Telemetry service configuration file
+===========================================================
+
+## SYNOPSIS
+
+```
+/etc/telemetrics/telemetrics.conf
+/usr/share/defaults/telemetrics/telemetrics.conf
+```
+
+## DESCRIPTION
+
+This file contains configuration parameters for the `telemd(1)` telemetry
+service daemon. The daemon reads this file at startup if it exists.
+
+## SYNTAX
+
+The configuration file contains `key=value` pairs, formatted as plain
+text, one option per line. Comments can be added by preceding them with the
+`#` character. All configuration options should be in a section marked
+with `[settings]`.
+
+## OPTIONS
+
+ * `server`=<url>:
+   Server URL including protocol designator.
+
+ * `socket_path`=<path>:
+   Path to the socket that `telemd` will listen on.
+
+ * `cainfo`=<path>:
+  Certificate file to use for validation of SSL endpoint.
+
+ * `tidheader`=<header>:
+  Telemetry ID in header format, usually
+    `tidheader=X-Telemetry-TID:<uuid>`
+  post header used to group records in ingestion service, which may be
+  ingesting for more than one set of clients. Can be set to any string.
+
+ * `record_expiry`=<minutes>:
+  Record expiry time in minutes.
+
+ * `spool_dir`=<`dir`>:
+  Local spool directory used to store records being processed.
+
+ * `spool_max_size`=<kB>:
+  maximum size of the spool directory in kB. A value of `-1` indicates
+  no limit. The block size of the files in this directory is considered,
+  and not the actual size of the record itself.
+
+ * `spool_process_time`=<seconds>:
+  Time in seconds for processing spool. Valid range: 120..3600. Values
+  outside this range are clamped.
+
+ * `rate_limit_enabled`=<`true`|`false`>:
+  Enable rate limiting. If this is set to false then all rate-limiting
+  disabled. It is possible to disable each rate-limit individually below.
+
+ * `record_burst_limit`=<limit>:
+  Rate limiting record burst limit. Valid Range:  0..`INT_MAX`, -1 = disabled.
+
+ * `record_window_length`=<minutes>:
+  Rate limiting record window length in minutes. Valid Range: 0..59.
+
+ * `byte_burst_limit`=<limit>:
+  Rate limiting byte burst limit. Valid Range:  0..`INT_MAX`, -1 = disabled.
+
+ * `byte_window_length`=<minutes>:
+  Rate limiting byte window length in minutes. Valid Range: 0..59.
+
+ * `rate_limit_strategy`=<strategy>:
+  Rate limit strategy - what to do with record if rate-limiting prevents
+  delivery over network. Valid stategies: `spool`, `drop`.
+
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemd(1)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/
@@ -1,15 +1,69 @@
-.TH TELEMETRY 3 "April 2015" Telemetrics
-.SH NAME
-telemetry \- Telemetry record creation and sending
-.SH SYNOPSIS
-#include <telemetry.h>
-.sp
-tm_create_record()
-.br
-tm_set_payload()
-.br
-tm_send_record()
-.br
-tm_set_config_File()
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TELEMETRY" "3" "December 2016" "" ""
+.
+.SH "NAME"
+\fBtelemetry\fR \- C programming interface for telemetrics\-client
+.
+.SH "SYNOPSIS"
+.
+.nf

+#include "telemetry\.h"
+
+struct telem_ref {
+        struct telem_record *record;
+};
+
+int tm_create_record(struct telem_ref **t_ref, uint32_t severity,
+                     char *classification, uint32_t payload_version)
+int tm_set_payload(struct telem_ref *t_ref, char *payload)
+int tm_send_record(struct telem_ref *t_ref)
+void tm_free_record(struct telem_ref *t_ref)
+void tm_set_config_file(char *c_file)
+.
+.fi
+.
+.SH "DESCRIPTION"
+The functions in the telemetry library facilitate the delivery of telemetry data to the \fBtelemd(1)\fR service\.
+.
+.P
+The function \fBtm_create_record()\fR initializes a telemetry record and sets the severity and classification of that record, as well as the payload version number\. The memory needed to store the telemetry record is allocated and should be freed with \fBtm_free_record()\fR when no longer needed\.
+.
+.P
+The function \fBtm_set_payload()\fR attaches the provided telemetry record data to the telemetry record\. The current maximum payload size is 8192b\.
+.
+.P
+The function \fBtm_send_record()\fR delivers the record to the local \fBtelemd(1)\fR service\.
+.
+.P
+The function \fBtm_set_config_file()\fR can be used to provide an alternate configuration path to the telemetry library\.
+.
+.SH "RETURN VALUES"
+All these functions return \fB0\fR on success, or a non\-zero return value if an error occurred\. The functions \fBtm_free_record()\fR and \fBtm_set_config_file()\fR do not return any values\.
+.
+.SH "COPYRIGHT"
+.
+.IP "\(bu" 4
+Copyright (C) 2016 Intel Corporation, License: CC\-BY\-SA\-3\.0
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+\fBtelemd(1)\fR
+.
+.P
+https://github\.com/clearlinux/telemetrics\-client
+.
+.P
+https://clearlinux\.org/documentation/
+.
+.SH "NOTES"
+Creative Commons Attribution\-ShareAlike 3\.0 Unported
+.
+.IP "\(bu" 4
+http://creativecommons\.org/licenses/by\-sa/3\.0/
+.
+.IP "" 0

@@ -0,0 +1,63 @@
+telemetry(3) -- C programming interface for telemetrics-client
+==============================================================
+
+## SYNOPSIS
+
+```
+#include "telemetry.h"
+
+struct telem_ref {
+        struct telem_record *record;
+};
+
+int tm_create_record(struct telem_ref **t_ref, uint32_t severity,
+                     char *classification, uint32_t payload_version)
+int tm_set_payload(struct telem_ref *t_ref, char *payload)
+int tm_send_record(struct telem_ref *t_ref)
+void tm_free_record(struct telem_ref *t_ref)
+void tm_set_config_file(char *c_file)
+```
+
+## DESCRIPTION
+
+The functions in the telemetry library facilitate the delivery of
+telemetry data to the `telemd(1)` service.
+
+The function `tm_create_record()` initializes a telemetry record and
+sets the severity and classification of that record, as well as the
+payload version number. The memory needed to store the telemetry record
+is allocated and should be freed with `tm_free_record()` when no longer
+needed.
+
+The function `tm_set_payload()` attaches the provided telemetry record
+data to the telemetry record. The current maximum payload size is 8192b.
+
+The function `tm_send_record()` delivers the record to the local
+`telemd(1)` service.
+
+The function `tm_set_config_file()` can be used to provide an alternate
+configuration path to the telemetry library.
+
+## RETURN VALUES
+
+All these functions return `0` on success, or a non-zero return value
+if an error occurred. The functions `tm_free_record()` and `tm_set_config_file()`
+do not return any values.
+
+## COPYRIGHT
+
+ * Copyright (C) 2016 Intel Corporation, License: CC-BY-SA-3.0
+
+## SEE ALSO
+
+`telemd(1)`
+
+https://github.com/clearlinux/telemetrics-client
+
+https://clearlinux.org/documentation/
+
+## NOTES
+
+Creative Commons Attribution-ShareAlike 3.0 Unported
+
+ * http://creativecommons.org/licenses/by-sa/3.0/
@@ -0,0 +1 @@
+.so man3/telemetry.3
@@ -0,0 +1 @@
+.so man3/telemetry.3
@@ -0,0 +1 @@
+.so man3/telemetry.3
@@ -0,0 +1 @@
+.so man3/telemetry.3
@@ -44,7 +44,8 @@ const char *config_key_int[] = { NULL, "record_expiry", "spool_max_size",
                                 "byte_window_length", "record_burst_limit",
                                 "byte_burst_limit", NULL };

-const char *config_key_bool[] = { NULL, "rate_limit_enabled", NULL };
+const char *config_key_bool[] = { NULL, "rate_limit_enabled",
+				  "daemon_recycling_enabled", NULL };

 static struct configuration config = { { 0 }, { 0 }, { 0 }, false, NULL };

@@ -334,4 +335,10 @@ const char *rate_limit_strategy_config()

        return val;
 }
+
+bool daemon_recycling_enabled_config(void)
+{
+	initialize_config();
+	return config.boolValues[CONF_DAEMON_RECYCLING_ENABLED];
+}
 /* vi: set ts=8 sw=8 sts=4 et tw=80 cino=(0: */
@@ -46,6 +46,7 @@ enum config_int_keys {
 enum config_bool_keys {
        CONF_BOOL_MIN = 0,
        CONF_RATE_LIMIT_ENABLED,
+	CONF_DAEMON_RECYCLING_ENABLED,
        CONF_BOOL_MAX
 };

@@ -113,4 +114,7 @@ const char *get_cainfo_config(void);
 /* Gets tidheader */
 const char *get_tidheader_config(void);

+/* Gets whether recycling is enabled */
+bool daemon_recycling_enabled_config(void);
+
 /* vi: set ts=8 sw=8 sts=4 et tw=80 cino=(0: */
@@ -35,3 +35,6 @@ rate_limit_enabled=true

 #rate limit strategy if record not send
 rate_limit_strategy=spool
+
+#daemon recycling enabled
+daemon_recycling_enabled=true
@@ -51,3 +51,7 @@ byte_window_length=20
 # Valid stategies: spool, drop
 rate_limit_strategy=spool

+# daemon recycling enabled - if daemon has been running for a while (2 hours),
+# has not any client nor spool data, then it exits.
+# this is to ensure that latest code runs.
+daemon_recycling_enabled=true
@@ -20,6 +20,7 @@

 #include "config.h"

+#ifdef TM_LOG_SYSTEMD
 #ifdef HAVE_SYSTEMD_SD_JOURNAL_H

 /* Certain static analysis tools do not understand GCC's __INCLUDE_LEVEL__
@@ -32,6 +33,7 @@
 #endif

 #include <systemd/sd-journal.h>
+#endif
 #else
 #include <errno.h>
 #include <string.h>
@@ -88,10 +90,10 @@
 #define telem_perror(msg) sd_journal_perror(msg)
 #endif
 #ifdef TM_LOG_SYSLOG
-#define telem_perror(msg) syslog(LOG_ERR, msg ": %s", strerror(errno))
+#define telem_perror(msg) syslog(LOG_ERR, msg ": %s\n", strerror(errno))
 #endif
 #ifdef TM_LOG_STDERR
-#define telem_perror(msg) fprintf(stderr, ": %s", msg)
+#define telem_perror(msg) fprintf(stderr, "ERROR: " msg ": %s\n", strerror(errno))
 #endif

 /* vi: set ts=8 sw=8 sts=4 et tw=80 cino=(0: */
@@ -232,6 +232,8 @@ int main(int argc, char **argv)
        time_t last_spool_run_time = time(NULL);
        time_t last_daemon_start_time = time(NULL);

+	bool daemon_recycling_enabled = daemon_recycling_enabled_config();
+
        ret = update_machine_id();
        if (ret == -1) {
                telem_log(LOG_ERR, "Unable to update machine id\n");
@@ -336,7 +338,7 @@ int main(int argc, char **argv)
                } else {
                        time_t now = time(NULL);
                        /* If spool is empty and time to recycle the daemon has elapsed*/
-                        if ((daemon.current_spool_size == 0) &&
+			if (daemon_recycling_enabled && (daemon.current_spool_size == 0) &&
                            difftime(now, last_daemon_start_time) >= TM_DAEMON_EXIT_TIME) {
                                /* Exit */
                                telem_log(LOG_INFO, "Daemon exiting for recycling\n");
@@ -380,6 +380,14 @@ int main(int argc, char **argv)
        GError *error = NULL;
        GOptionContext *context;

+        if (fcntl(STDERR_FILENO, F_GETFL) < 0) {
+                // redirect stderr to avoid bad things to happen with
+                // fd 2 when launched from kernel core pattern
+                if (freopen("/dev/null", "w", stderr) == NULL) {
+                        exit(EXIT_FAILURE);
+                }
+        }
+
        // Since this program handles core files, make sure it does not produce
        // core files itself, or else it will be invoked endlessly...
        prctl(PR_SET_DUMPABLE, 0);
@@ -56,6 +56,20 @@ static GOptionEntry options[] = {
        { NULL }
 };

+const unsigned int count_chars(const char *check, const char character)
+{
+        unsigned int count = 0U;
+        if (check == NULL) {
+                return count;
+        }
+        for (; *check != '\0'; ++check) {
+                if (*check == character) {
+                        ++count;
+                }
+        }
+        return count;
+}
+
 static void free_glib_strings(void)
 {
        if (config_file) {
@@ -122,6 +136,12 @@ int validate_opts(void)
                return ret;
        }

+        if (count_chars(opt_class, '/') != 2) {
+                fprintf(stderr, "Error: Classification needs to be in "
+                        "most/to/least specific format, 2 \'/\' required.\n");
+                return ret;
+        }
+
        /* Severity */
        if ((severity) < 1 || (severity > 4)) {
                fprintf(stderr, "Error: Valid range for severity is 1-4\n");
@@ -50,6 +50,7 @@ START_TEST(check_read_valid_config)
        ck_assert_str_eq(config.strValues[CONF_CAINFO], "/tmp/cacert.crt");
        ck_assert_str_eq(config.strValues[CONF_TIDHEADER],
                         "X-Telemetry-TID: 6907c830-eed9-4ce9-81ae-76daf8d88f0f");
+	ck_assert(config.boolValues[CONF_DAEMON_RECYCLING_ENABLED] == true);

 }
 END_TEST
@@ -75,6 +76,7 @@ START_TEST(check_config_initialised)
        ck_assert_str_eq(get_cainfo_config(), "/tmp/cacert.crt");
        ck_assert_str_eq(get_tidheader_config(),
                         "X-Telemetry-TID: 6907c830-eed9-4ce9-81ae-76daf8d88f0f");
+	ck_assert(daemon_recycling_enabled_config() == true);
 }
 END_TEST
Author	SHA1	Message	Date
Auke Kok	3e4360e2cb	Docs: Add manual pages using `ronn`. This adds several new manual pages to the project, ships them using `dist` and has a simple target to recreate the new roff files using the `ronn` utility: `make manpages`. These man pages are still very crude and contain the absolute minimum amount of information. I've attempted to cross link them as much as is reasonable. The telemetry API is documented in `telemetry(3)`. The important functions themselves are `linked` with a ref link that should make `man tm_create_record` (etc.) link to telemetry(3). I attempted to make this pass `make distcheck` and `make install` properly, but this should still be checked.	2016-12-08 17:47:25 -08:00
John Andersen	cb622a0eb0	Validation for classification to ensure 2 slashes (#4 ) * Validation for classification to ensure 2 slashes Signed-off-by: John Andersen <john.s.andersen@intel.com> * Update telem_record_gen.c Fixed code style issues	2016-09-02 00:43:48 -07:00
Jeremy Rocher	44e0d4d3c5	crashprobe: fix stderr when launched from kernel stderr could be used for logging or in libtelemetry in DEBUG mode but when crashprobe is launched through kernel core_pattern, stderr is not open, only stdin (fd 0), see this dump from gdb: (gdb) shell ls -l /proc/15478/fd total 0 lr-x------ 1 root root 64 24 juin 15:02 0 -> pipe:[82555] If stderr is not open, when socket to telemd is open it could take fd 2 and in this case all fprint to stderr are written to socket which is bad ... this is the case when doing static linking, which ends to telemd crashed. Fix it by ensuring stderr is open. Signed-off-by: Jeremy Rocher <jeremy.rocher@intel.com>	2016-08-17 21:09:33 +00:00
Loic Poulain	36f4854967	Make daemon recycling configurable The user may want to disable recycling (daemon auto exit). This can be the case if telemd daemon is not configured to respawn or if service is automatically restarted by the system after package update. This patch introduces the daemon_recycling_enabled config entry.	2016-08-17 21:08:24 +00:00
Jeremy Rocher	524d5d2345	fix telem_perror when logging to stderr When logging to stderr, telem_perror output is incomplete and badly formatted. Print errno correctly, fix newline and fix includes. Signed-off-by: Jeremy Rocher <jeremy.rocher@intel.com>	2016-08-17 13:42:39 -07:00