diff --git a/Makefile.am b/Makefile.am index 5e13b23..dc01629 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 diff --git a/README b/README index 4030bec..44dc674 100644 --- a/README +++ b/README @@ -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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..cdb42da --- /dev/null +++ b/docs/README.md @@ -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. diff --git a/docs/local.mk b/docs/local.mk new file mode 100644 index 0000000..ef952f9 --- /dev/null +++ b/docs/local.mk @@ -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 diff --git a/docs/man/.gitignore b/docs/man/.gitignore new file mode 100644 index 0000000..2d19fc7 --- /dev/null +++ b/docs/man/.gitignore @@ -0,0 +1 @@ +*.html diff --git a/docs/man/telem-record-gen.1 b/docs/man/telem-record-gen.1 new file mode 100644 index 0000000..7e3ead7 --- /dev/null +++ b/docs/man/telem-record-gen.1 @@ -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 + diff --git a/docs/man/telem-record-gen.1.md b/docs/man/telem-record-gen.1.md new file mode 100644 index 0000000..9830081 --- /dev/null +++ b/docs/man/telem-record-gen.1.md @@ -0,0 +1,70 @@ +telem-record-gen(1) -- Create custom telemetry record +===================================================== + +## SYNOPSIS + +`telem-record-gen` + +## 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 . + +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` : + 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` : + Record body (max size = 8k). + + * `-P`, `--payload-file` : + File to read payload from. + + * `-R`, `--record-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/ diff --git a/docs/man/telemctl.1 b/docs/man/telemctl.1 new file mode 100644 index 0000000..1e48ad7 --- /dev/null +++ b/docs/man/telemctl.1 @@ -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 + diff --git a/docs/man/telemctl.1.md b/docs/man/telemctl.1.md new file mode 100644 index 0000000..e68e6d4 --- /dev/null +++ b/docs/man/telemctl.1.md @@ -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/ diff --git a/docs/man/telemd.1 b/docs/man/telemd.1 new file mode 100644 index 0000000..058c361 --- /dev/null +++ b/docs/man/telemd.1 @@ -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 + diff --git a/docs/man/telemd.1.md b/docs/man/telemd.1.md new file mode 100644 index 0000000..1867220 --- /dev/null +++ b/docs/man/telemd.1.md @@ -0,0 +1,47 @@ +telemd(1) -- Telemetry client service +===================================== + +## SYNOPSIS + +`telemd` +`/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` []: + 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/ diff --git a/docs/man/telemetrics.conf.5 b/docs/man/telemetrics.conf.5 new file mode 100644 index 0000000..3f4a119 --- /dev/null +++ b/docs/man/telemetrics.conf.5 @@ -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:\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 + diff --git a/docs/man/telemetrics.conf.5.md b/docs/man/telemetrics.conf.5.md new file mode 100644 index 0000000..c122c34 --- /dev/null +++ b/docs/man/telemetrics.conf.5.md @@ -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`=: + Server URL including protocol designator. + + * `socket_path`=: + Path to the socket that `telemd` will listen on. + + * `cainfo`=: + Certificate file to use for validation of SSL endpoint. + + * `tidheader`=
: + Telemetry ID in header format, usually + `tidheader=X-Telemetry-TID:` + 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`=: + Record expiry time in minutes. + + * `spool_dir`=<`dir`>: + Local spool directory used to store records being processed. + + * `spool_max_size`=: + 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`=: + 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`=: + Rate limiting record burst limit. Valid Range: 0..`INT_MAX`, -1 = disabled. + + * `record_window_length`=: + Rate limiting record window length in minutes. Valid Range: 0..59. + + * `byte_burst_limit`=: + Rate limiting byte burst limit. Valid Range: 0..`INT_MAX`, -1 = disabled. + + * `byte_window_length`=: + Rate limiting byte window length in minutes. Valid Range: 0..59. + + * `rate_limit_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/ diff --git a/docs/man/telemetry.3 b/docs/man/telemetry.3 index 0e237c5..7c3bf7c 100644 --- a/docs/man/telemetry.3 +++ b/docs/man/telemetry.3 @@ -1,15 +1,69 @@ -.TH TELEMETRY 3 "April 2015" Telemetrics -.SH NAME -telemetry \- Telemetry record creation and sending -.SH SYNOPSIS -#include -.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 diff --git a/docs/man/telemetry.3.md b/docs/man/telemetry.3.md new file mode 100644 index 0000000..27d06d9 --- /dev/null +++ b/docs/man/telemetry.3.md @@ -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/ diff --git a/docs/man/tm_create_record.3 b/docs/man/tm_create_record.3 index e69de29..ff0dc73 100644 --- a/docs/man/tm_create_record.3 +++ b/docs/man/tm_create_record.3 @@ -0,0 +1 @@ +.so man3/telemetry.3 diff --git a/docs/man/tm_send_record.3 b/docs/man/tm_send_record.3 index e69de29..ff0dc73 100644 --- a/docs/man/tm_send_record.3 +++ b/docs/man/tm_send_record.3 @@ -0,0 +1 @@ +.so man3/telemetry.3 diff --git a/docs/man/tm_set_config_file.3 b/docs/man/tm_set_config_file.3 index e69de29..ff0dc73 100644 --- a/docs/man/tm_set_config_file.3 +++ b/docs/man/tm_set_config_file.3 @@ -0,0 +1 @@ +.so man3/telemetry.3 diff --git a/docs/man/tm_set_payload.3 b/docs/man/tm_set_payload.3 index e69de29..ff0dc73 100644 --- a/docs/man/tm_set_payload.3 +++ b/docs/man/tm_set_payload.3 @@ -0,0 +1 @@ +.so man3/telemetry.3