{"id":19450814,"url":"https://github.com/clearlinux/telemetrics-client","last_synced_at":"2025-04-25T03:32:08.085Z","repository":{"id":142665762,"uuid":"61900532","full_name":"clearlinux/telemetrics-client","owner":"clearlinux","description":"Client telemetry components","archived":false,"fork":false,"pushed_at":"2025-04-17T22:37:32.000Z","size":716,"stargazers_count":16,"open_issues_count":6,"forks_count":26,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-18T12:24:24.518Z","etag":null,"topics":["telemetry"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clearlinux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-06-24T17:19:45.000Z","updated_at":"2025-04-17T22:36:50.000Z","dependencies_parsed_at":"2025-04-17T23:42:33.266Z","dependency_job_id":"a99e6ffe-ed99-452d-8612-77ac8b44fffc","html_url":"https://github.com/clearlinux/telemetrics-client","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearlinux%2Ftelemetrics-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearlinux%2Ftelemetrics-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearlinux%2Ftelemetrics-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearlinux%2Ftelemetrics-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clearlinux","download_url":"https://codeload.github.com/clearlinux/telemetrics-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250748094,"owners_count":21480778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["telemetry"],"created_at":"2024-11-10T16:39:11.003Z","updated_at":"2025-04-25T03:32:08.064Z","avatar_url":"https://github.com/clearlinux.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://github.com/clearlinux/telemetrics-client/workflows/C%2FC++%20CI/badge.svg)\n\nTelemetrics-client\n==================\n\nThis package provides the front end component of a complete telemetrics\nsolution for Linux-based operating systems. Specifically, the front end\ncomponent includes:\n\n- telemetrics probes that collect specific types of data from the operating\n  system. For more info on probes go [here](./src/probes).\n\n- a library, libtelemetry, that telemetrics probes use to create telemetrics\n  records and send them to the daemon for further processing.\n\n- telemprobd, a daemon that handles communication with probes and forwards records\n  to a second daemon.\n\n- telempostd, this daemon sends telemetry records to a telemetrics server\n  (not included in this source tree), or spools the records on disk in case\n  it's unable to successfully deliver them.\n\nA telemetrics server implementation that works with this component is available\nfrom\n[clearlinux/telemetrics-backend](https://github.com/clearlinux/telemetrics-backend).\n\n\nBuild dependencies\n---------------------\n\n- libcheck\n\n- libcurl\n\n- elfutils, which provides libelf and libdwfl libraries..\n\n- (optional) libsystemd, for syslog-style logging to the systemd journal, and\n  socket/path activation of telemprobd and telempostd by systemd.\n\n\nBuild and installation\n---------------------\n\n```{r, engine='bash', count_lines}\n$ ./autogen.sh\n$ ./configure\n$ make\n```\n\nSet up\n---------------------\n\nThere is a config file installed at\n\n```{r, engine='bash', count_lines}\n/usr/share/defaults/telemetrics/telemetrics.conf\n```\n\nTo make modifications, copy that file to\n\n```{r, engine='bash', count_lines}\n/etc/telemetrics/telemetrics.conf\n```\nand modify the /etc version.\n\nDescriptions of config options are listed below in the Usage section.\n\nStarting the client\n---------------------\nTo use the telemetrics client a one time explicit ```opt-in``` is required (this is\nalso true when the contents of the directory ```/etc/telemetrics/``` are removed).\nTo opt-in to telemetrics-client use the command:\n\n```{r, engine='bash', count_lines}\n telemctl opt-in\n```\n\n**Note** this is a change from previous versions, before 2.3.0 installation of\ntelemetrics client was enough to enable the client and if needed the client could\nbe disabled with ```telemctl opt-out```. This command in previous versions created\n```/etc/telemetrics/opt-out``` file (after telemetrics-client version 2.3.0 this\nfile can be safely removed).\n\nIf the client was compiled with systemd support the respective activation units\nshould be already in place (after a ```make install``` invocation). In this case\nthe client wil start automatically when data is made available to it. i.e. when\nexecuting an ```/usr/bin/hprobe``` command. Otherwise use the following command:\n\n```{r, engine='bash', count_lines}\n telemctl start\n```\nNote: the above invocation technically readies the service for both socket and\npath activation, so you may not see an \"active\" status. To check the status of\ntelemetrics-client use:\n\n```{r, engine='bash', count_lines}\n telemctl is-active\n   telemprobd : active\n   telempostd : active\n```\n\nStarting individual service units ```telempostd.service``` or ```telemeprobd.service```\nis discouraged.\n\nConfigure the client to autostart at boot\n---------------------\n\nAs longs as the first time ```opt-in``` was performed, the following methods are valid:\n\n\nMethod 1 (recommended):\n\nEnable the socket-activated service and path unit:\n\n```{r, engine='bash', count_lines}\nsystemctl enable telemprobd.socket telempostd.path\n```\n\nMethod 2:\n\nEnable services, which automatically enables the socket and path\nunits as well:\n\n```{r, engine='bash', count_lines}\nsystemctl enable telemprobd.service\nsystemctl enable telempostd.service\n```\n\nUsage\n---------------------\n\nOnce the client is running, the telemetrics probes will be ready to use.\n\nAvailable probes:\n\n* hprobe: A test program that utilizes libtelemetry to ensure\nthat telemetrics-client works. It sends a \"hello world\" record to the server.\n\n* crash probe: A handler for core files that sends the corresponding backtraces\nto the server.\n\nThe client uses the following configuration options from the configuration file:\n\n* server: This specifies the web server that the telempostd sends the telemetry records to\n* socket_path: This specifies the path of the unix domain socket that the\n  telemprobd listens on for connections from the probes\n* spool_dir: This config option is related to spooling. If the daemon is not\n  able to send the telemetry records to the backend server due to reasons such\n  as the network availability, then it stores the records in a spool directory.\n  This option specifies that path of the spool directory. This directory should\n  be owned by the same user that the daemon is running as.\n\n```{r, engine='bash', count_lines}\n    mkdir -p /var/spool/telemetry\n    chown -R telemetry:telemetry /var/spool/telemetry\n    systemctl restart telemprobd.service\n```\n\n* record_expiry: This is the time in minutes after which the records in the\n  spool directory are deleted by the daemon.\n* spool_max_size: This specifies the maximum size of the spool directory. When\n  the size of the spool directory reaches this limit, new telemetry records are\n  dropped by the daemon.\n* spool_process_time: This specifies the time interval in seconds that the\n  daemon waits for before checking the spool directory for records. The daemon\n  picks up the records in the order of modification date and tries to send the\n  record to the server. It sends a maximum of 10 records at a time. If it was\n  able to send a record successfully, it deletes the record from the spool.  If\n  the daemon finds a record older than the \"record_expiry\" time, then it\n  deletes that record. The daemon looks at a maximum of 20 records in a single\n  spool run loop.\n* rate_limit_enabled: This determines whether rate-limiting is enabled or\n  disabled. When enabled, there is a threshold on both records sent within a\n  window of time, and record bytes sent within a window a time.\n* record_burst_limit: This is the maximum amount of records allowed to be\n  passed by the daemon within the record_window_length of time. If set to -1,\n  the rate-limiting for record bursts is disabled.\n* record_window_length: This is the time, in minutes (0-59), that establishes\n  the window length for the record_burst_limit. EX: if record_burst_window=1000\n  and record_window_length=15, then no more than 1000 records can be passed\n  within any given fifteen minute window.\n* byte_burst_limit: This is the maximum amount of bytes that can be passed by\n  the daemon within the byte_window_length of time. If set to -1, the\n  rate-limiting for byte bursts is disabled.\n* byte_window_length: This is the time, in minutes (0-59), that establishes the\n  window length for the byte_burst_limit.\n* rate_limit_strategy: This is the strategy chosen once the rate-limiting\n  threshold has been reached. Currently the options are 'drop' or 'spool', with\n  spool being the default. If spool is chosen, records will be spooled and sent\n  at a later time.\n* record_retention_enabled: When this key is enabled (true) the daemon saves a\n  copy of the payload on disk from all valid records. To avoid the excessive use\n  of disk space only the latest 100 records are kept. The default value for this\n  configuration key is false.\n* record_server_delivery_enabled: This key controls the delivery of records to\n  ```server```, when enabled (default value) the record will be posted to the\n  address in the configuration file. If this configuration key is disabled (false)\n  records will not be spooled or posted to backend. This configuration key can\n  be used in combination with ```record_retention_enabled``` to keep copies of\n  telemetry records locally only.\n\n\nData reported\n---------------------\n\nThe data reported by the telemetry client could be understood as two main sets:\nmetadata and a payload.\n\nThe metadata is used to report details of a machine's architecture. The\nfollowing are the metadata values currently collected (Record Format Version 4):\n\n* record_format_version: version of the record, currently is 'Version 4'. This\n  value changes when new metadata is added.\n* classification: this field is used to identify the type of record sent by a\n  specific client probe; classifications use the format DOMAIN/PROBE/REST, where\n  DOMAIN is the vendor of the probe, PROBE is the probe name, and REST is a\n  probe-defined field to classify what is contained in the payload.\n* severity: this is an integer value between 1 and 4 where 1 is \"low\" and 4 is\n  \"critical\"\n* machine_id: a machine identifier that is rotate every 3 days for privacy reasons.\n* creation_timestamp: timestamp when the record was collected.\n* arch: a string describing machine architecture i.e. 'x86_64'.\n* host_type: a string with the combination of 'System Vendor', 'Product Name', and\n  'Product Version' read from dmi file system.\n* build: OS build number.\n* kernel_version: Kernel version.\n* payload_format_version: version of the payload, currently is 'Version 1'.\n* system_name: the value after 'ID=' from '/etc/os-release' (or distribution\n  provided folder)\n* board_name: a string read from dmi file system that combines 'Board Name' and\n  'Board Vendor'.\n* cpu_model: cpu model name extracted from '/proc/cpuinfo'.\n* bios_version: BIOS version.\n* event_id: an id to group multiple records if these were generated by a single\n  event occurrence.\n\nThe payload as mentioned above is reported by probes. The telemetry library adds\nthe metadata to the payload (done programatically when using library API) for\nmore information about probes go [here](./src/probes).\n\n\nMachine id\n---------------------\n\nThe machine id reported by the telemetry client is rotated every 3 days for\nprivacy reasons. If you wish to have a static machine id for testing purposes,\nyou can opt in by creating a static machine id file named\n\"opt-in-static-machine-id\" under the directory  \"/etc/telemetrics/\". Where\n\"unique machine ID\" is your desired static machine ID:\n\n```{r, engine='bash', count_lines}\n# mkdir -p /etc/telemetrics\n# echo \"unique machine ID\" \u003e /etc/telemetrics/opt-in-static-machine-id\n```\n\nThe telemetry client reads, at most, the first 32 characters from this file\nuses it for the machine id. You can put a string like 'my-machine-name' in this\nfile to easily identify your machine.  Restart telemprobd for the machine id\nchanges to take effect by running:\n\n```{r, engine='bash', count_lines}\n# systemctl restart telemprobd.service\n```\n\nYou can switch back to the rotating machine id by deleting the override file\nand restarting the client.  You can do a quick test to check that your\nmachine-id has changed by running \"hprobe\" and verifying that a record has\nlanded on your backend telemetrics server, with the specified machine id.\n\nEvent Id\n----------------------\n\nThis is a 32 character lowercase hexadecimal string i.e. '5de9de8d5f3c6a7d445d75ba01cc3322'.\nThis header is used to group multiple records by an event id. Before this header\nevery single record could have been thought of an event, however this is not always\nthe case. There are \"events\" that trigger the creation of multiple records (i.e.\nupdates). The ```event_id``` header was added for probes with the capability to\ndetect events and group records based on such events. This header was added to\n```telem-record-gen``` and can be specified using the ```-e``` (```--event-id```\nlong form) switch.\n\n```{r, engine=bash, count_lines}\n  -e, --event-id        Event id to use in the record\n```\n\nDebugging locally with telemetrics-client\n-----------------------------------------------\n\nThe function of the telemetrics-client is to handle the transport of information\nreported by a probe to a backend (see ```server``` key in configuration). This\ninformation is helpful for developers to debug and fix reported crashes, however\ndevelopers not always have access to the backend in these case users can leverage\nfeatures added for local debugging. The following is a list of steps to enable\nlocal debug:\n\n* *Enabling record retention*: this step configures telempostd to keep\ncopies of telemetry records locally. To enable record retention set the value of\n```record_retention_enabled``` from ```false``` to ```true```. Optionally set\n```record_server_delivery_enabled`` to ```false``` to keep records local only.\nRemember to restart the client after configuration values are updated\n(```telemctl restart```).\n\n* *Creating a record*: run ```hprobe``` command to create a record for the purposes\nof this step by step guide. Once we have the record or records that you need to\ncapture locally you can display the data.\n\n* *Displaying record metadata*: telempostd keeps metadata of any valid record,\nto display this data a new option to telemctl was added ```telemctl journal```.\nAssuming that the last record created was the record from previous step `hprobe` we\ncan use `tail -n 1` to print the last created record only, i.e.\n\n```\n$ sudo telemctl journal | tail -n 1\n$ org.clearlinux/hello/world     Mon 2018-04-02 17:48:01 UTC a19a0d41ba16788881e274b19b8a1be4 5de9de8d5f3c6a7d445d75ba01cc3322 60c014cd-4693-40f1-b334-548cd932949b\n```\n\nThe headers for the metadata (along with other information) can be printed using the\n```-V``` switch with ```telemctl journal``` command, i.e.\n\n```\n$ sudo telemctl journal -V | head -n 1\n$ Classification             Time stamp              Record ID                    Event ID                     Boot ID\n```\n\n* *Displaying record payload*: to print the content of a record payload you can use\nthe ```-i``` (```--include_record``` long format) option to ```telemctl journal```\ncommand. To print the specific record you created you can use the option ```-r```\n(```--record_id``` long format) with the Record Id of the generated record, i.e.\n\n```\n$ sudo telemctl journal --record_id a19a0d41ba16788881e274b19b8a1be4 --include_record\n$ org.clearlinux/hello/world     Mon 2018-04-02 17:48:01 UTC a19a0d41ba16788881e274b19b8a1be4 5de9de8d5f3c6a7d445d75ba01cc3322 60c014cd-4693-40f1-b334-548cd932949b\n$ hello\n```\n\n## Using tarball\n\nWhen building the telemetrics-client using the tarball, a signature is provided for\nvalidation. Please follow the steps outlined in the release's README.txt for guidance.\n\n## Security Disclosures\n\nTo report a security issue or receive security advisories please follow procedures\nin [link](security.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclearlinux%2Ftelemetrics-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclearlinux%2Ftelemetrics-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclearlinux%2Ftelemetrics-client/lists"}