遥测

本指南描述了 Clear Linux* OS 遥测解决方案。

重要

Clear Linux OS 中的遥测为 opt-in。遥测客户端未处于活动状态，且在您将其显式启用之前不发送任何数据。

注解

遥测功能遵从涉及收集和使用 PII 的 英特尔隐私条款，同时也是开源功能。

系统不会蓄意收集涉及用户或系统所有者的可识别身份的信息。

概述

Clear Linux OS 中的遥测是用于收集来自正在运行的 Clear Linux OS 系统的数据的客户端/服务器解决方案，有助于快速确定和修复操作系统中的错误。客户端和服务器均可定制，而客户端则可使用 API 检测代码，进行调试和分析。

借助遥测这一 Clear Linux OS 的主要功能，开发人员可在最终用户受到影响之前观察并主动解决操作系统中存在的问题。

遥测 (Telemetrics) 是由以下项组成的组合词：

• 遥测 (Telemetry)，即感知和报告数据。
• 分析 (Analytics)，即使用可视化和统计推理探究报告数据的意义。

Clear Linux OS 遥测使用专用探针来报告系统级调试/崩溃信息。探针可监控系统任务，例如 swupd、内核 oops、机器错误检查以及未处理硬件故障的 BIOS 错误报告表。遥测可以实时报告问题，以便系统开发人员快速关注问题并监控更正措施。

Clear Linux OS 遥测支持完全定制，可在软件开发期间用于调试。可以在代码中使用 libtelemetry 库来创建定制遥测记录。还可以在脚本文件中使用 telem-record-gen 实用程序创建轻触记录，其中检测代码文件并无作用。

Clear Linux OS 遥测解决方案是客户端上的一个选择启用选项。默认情况下，禁用遥测客户端，直到用户选择将其启用。本指南介绍如何启用客户端。

体系架构

Clear Linux OS 遥测有两大基本组件，如图 1 所示：

• 客户端：通过网络生成记录并将其传送到后端服务器。
• 后端：接收客户端发来的记录，通过专门的 Web 界面显示累积的内容。

图 1： |CL| Telemetry Architecture

遥测客户端提供遥测解决方案的前端，同时还包括以下组件：

• telemprobd 是一个守护程序，用于接收并准备探针的遥测记录，并将其假脱机至磁盘。
• telempostd 是一个守护程序，根据可配置设置管理假脱机的遥测记录并提供这些记录。
• probes，从操作系统收集特定类型的数据。
• libtelemetry，遥测探针用于创建记录的 API。

遥测后端提供遥测解决方案的服务器端组件且包括：

• Nginx Web 服务器。
• 两个 Flask 应用：
  • Collector，针对从客户端探针所接收记录的接入式网络应用。
  • TelemetryUI，通过不同视图实现遥测数据可视化的网络应用。
• PostgreSQL 作为底层数据库服务器。

注解

默认遥测后端服务器由英特尔 Clear Linux OS 开发团队托管，且无法在英特尔防火墙之外查看。要收集个人记录，必须设置自己的遥测后端服务器。

使用方法

从工作流角度来看，Clear Linux OS 遥测系统非常简单。在客户端，安装和启用遥测技术之后的主要决策涉及如何处理探针生成的记录数据。可以将数据发送到默认或定制后端服务器，也可将此数据保留在系统本地，或同时执行二者。后端服务器的设置更为复杂，但一旦运行，它就极易使用和配置。

本节介绍配置 Clear Linux OS 遥测系统的部分潜在场景，并根据需求提供有意义的建议。

场景

1. 启用遥测技术：

   必须启用遥测客户端守护程序，探针才能生成记录。创建定制 telemetrics.conf 文件，将其存储在 /etc/telemetrics 目录中，可以在启用前配置客户端。如果选择使用默认设置，则会将记录发送到英特尔 Clear Linux OS 开发团队所管理的遥测后端服务器。

2. 本地保存记录数据：

   可以配置遥测客户端，在本地保存记录。在开发周期中需要即时反馈或是认为存在特定于计算机的问题以便跟踪系统问题时，此功能非常方便。可以将客户端设为完全不发送记录，或是将记录保存在本地并发送到后端服务器。

3. 设置服务器以收集数据：

   无论是管理 Clear Linux OS 系统网络，还是不想将记录发送到默认遥测服务器，均可设置后端服务器来收集个人记录。后端服务器可安装在任意 Linux 系统上，并为您提供与默认服务器相同的控制台。

4. 通过 libtelemetry API 检测代码：

   telemetrics bundle 文件包括 libtelemetry C 库，可以提供 telemprobd 和 telempostd 守护程序所用的 API。同时，也可以在应用程序中使用这些守护程序。相关 API 文档位于 Telemetrics client 存储库的 telemetry.h 文件中。

示例

启用或禁用遥测

1. 在安装期间启用：

   在初始安装 Clear Linux OS 期间，系统会要求加入稳定性增强计划，允许 Clear Linux OS 收集匿名报告，提高系统稳定性。如果选择不加入此计划，则不会将遥测软件 bundle 文件添加到系统中。选择加入此计划，则会在安装完成后自动在系统上启用遥测技术。

2. 安装后启用：

   要在系统上启动遥测，请运行以下命令：

   sudo telemctl start
   

   此命令将启用并启动 telemprobd 和 telempostd 守护程序。系统随即开始将遥测数据发送到文件 /etc/telemetrics/telemetrics.conf 中所定义的服务器。如果此文件不存在，telemprobd 和 telempostd 守护程序则会使用文件 /usr/share/defaults/telemetrics/telemetrics.conf。

3. 安装后禁用：

   要禁用这两个遥测守护程序，请运行以下命令：

   sudo telemctl stop
   

4. 选择启用遥测技术：

   要选择启用遥测服务，只需输入选择启用命令，也会启动服务：

   sudo telemctl opt-in
   

   此操作将删除 /etc/telemetrics/opt-out 文件（如果存在）并启动遥测服务。

   注解

   要选择启用而非立即启动遥测服务，则需在输入 opt-in 命令后运行命令 sudo telemctl stop。准备好启动服务后，输入命令 sudo telemctl start。

5. 选择禁用遥测技术：

   要停止发送来自系统的遥测数据，请选择禁用遥测服务：

   sudo telemctl opt-out
   

   此操作将创建文件 /etc/telemetrics/opt-out 并停止遥测服务。

本地保存数据

本例要求安装 Clear Linux OS 并在系统上启用遥测技术。

要更改记录的管理方式，请将默认的 /usr/share/defaults/telemetrics/telemetrics.conf 文件复制到 /etc/telemetrics/telemetrics.conf 并对其进行编辑。/etc/telemetrics/telemetrics.conf 文件中的更改会覆盖 /usr/share/defaults/telemetrics/telemetrics.conf 文件中的默认值。您可能需要 root 权限才能在 /etc 中创建和编辑文件。在每个示例中，每次对配置文件进行更改时，均需重新启动客户端守护程序才能接受更改：

sudo telemctl restart

使用 telemctl journal 命令可以访问遥测日志的各项功能和选项，有助于进行系统分析和调试。telemctl journal 提供众多选项来协助过滤记录。使用 -h 或 --help 查看使用情况选项。

1. 保留本地副本并将记录发送到后端服务器：

   要保留遥测记录的本地副本并将其发送到后端服务器，需将 record_retention_enabled 配置键值更改为 true。

2. 保留所有记录 - 不发送到后端服务器：

   要保留系统上的记录而不将其发送到后端服务器，请将 record_server_delivery_enabled 键值设为 false。请注意，您可能还需确保 record_retention_enabled 配置键值已设为 true，否则系统不会保留本地副本。

3. 保留记录并将其发送到定制服务器：

   此操作假设您已根据下例设置了定制服务器。

   此服务器通过 server 设置确定，且默认将记录发送到 Clear Linux OS 服务器 server=https://clr.telemetry.intel.com/v2/collector。要更改此设置，可使用 IP 地址或完全限定域名。

设置后端服务器以收集遥测记录

在本例中，请先使用 使用实时服务器将 Clear Linux* OS 安装在裸机上 入门指南和以下内容在新系统上完整安装 Clear Linux OS：

1. 加入 Stability Enhancement Program，安装和启用遥测组件。

2. 选择采用以下设置的手动安装方法：

   • 将主机名设为 clr-telem-server。
   • 创建名为 clear 的管理用户并将其添加到 sudo 用户组

3. 以管理用户身份登录，在 $HOME 目录中运行 git，将 telemetrics-backend 存储库克隆到 $HOME/telemetrics-backend 目录：

   git clone https://github.com/clearlinux/telemetrics-backend
   

   注解

   如果访问 github.com 时出现问题，则最好设置 https_proxy 环境变量。

4. 将当前工作目录更改为 telemetrics-backend/scripts。

5. 在下一步利用 deploy.sh 脚本文件安装遥测后端之前，请查看此处关于指定选项的说明：

   • -a install 用于安装
   • -d clr 用于安装到 Clear Linux OS 发行版
   • -H localhost 用于将域设为 localhost

   警告

   deploy.sh shell 脚本附带小规模错误检查机制，并可对系统进行某些更改。在继续操作之前，请确保您在命令行上定义的选项正确无误。

6. 在 $HOME/telemetrics-backend/scripts 目录中运行此 shell 脚本：

   ./deploy.sh -H localhost -a install -d clr
   

   此脚本将启动并列出所有已定义的选项并提示输入 PostgreSQL 数据库密码。

   Options:
    host: localhost
    distro: clr
    action: install
    repo: https://github.com/clearlinux/telemetrics-backend
    source: master
    type: git
    DB password: (default: postgres):
   

7. 对于 DB password:，请按 Enter 键接受默认密码 postgres。

   注解

   deploy.sh 脚本使用 sudo 运行命令，而系统在执行脚本时则随时可能会提示您输入用户密码。如果出现此情况，请输入用户密码，执行 sudo 命令。

8. 所有服务器组件均已安装后，系统将提示输入 PostgreSQL 数据库密码，如下所示对其进行更改：

   Enter password for 'postgres' user:
   New password:
   Retype new password:
   passwd: password updated successfully
   

   输入此密码的当前值 postgres，然后输入新密码。接着，再次输入此密码进行验证， PostgreSQL 数据库密码随即更新。

9. 安装完成后，可以打开系统浏览器，在地址栏中输入 localhost，使用 Web 浏览器查看新服务器。您应看到下面图 2 所示的网页。

   

   图 2： Telemetry UI

使用 telem-record-gen 创建记录

遥测 bundle 文件提供名为 telem-record-gen 的记录生成器工具。无法以 C 语言编写探针时，便可使用此工具从 shell 脚本或命令行创建记录。记录将发送到后端服务器，同时还可返回 stdout。

有三种方法可将有效负载提供给记录。

1. 在命令行中，使用 -p <string> 选项：

   telem-record-gen -c a/b/c -n -o -p 'payload goes here'
   

   record_format_version: 4
   classification: a/b/c
   severity: 1
   machine_id: FFFFFFFF
   creation_timestamp: 1539023189
   arch: x86_64
   host_type: innotek GmbH|VirtualBox|1.2
   build: 25180
   kernel_version: 4.14.71-404.lts
   payload_format_version: 1
   system_name: clear-linux-os
   board_name: VirtualBox|Oracle Corporation
   cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
   bios_version: VirtualBox
   event_id: 2236710e4fc11e4a646ce956c7802788
   
   payload goes here
   

2. 通过 -P path/to/file 选项指定包含此有效负载的文件。

   telem-record-gen -c a/b/c -n -o -P ./payload_file.txt
   

   record_format_version: 4
   classification: a/b/c
   severity: 1
   machine_id: FFFFFFFF
   creation_timestamp: 1539023621
   arch: x86_64
   host_type: innotek GmbH|VirtualBox|1.2
   build: 25180
   kernel_version: 4.14.71-404.lts
   payload_format_version: 1
   system_name: clear-linux-os
   board_name: VirtualBox|Oracle Corporation
   cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
   bios_version: VirtualBox
   event_id: d73d6040afd7693cccdfece479df9795
   
   payload read from file
   

3. 如果不使用 -p 或 -P 选项，此工具则会从 stdin 读取，以便您在脚本的 heredoc 中使用。

   #telem-record-gen -c a/b/c -n -o << HEOF
   payload read from stdin
   HEOF
   

   record_format_version: 4
   classification: a/b/c
   severity: 1
   machine_id: FFFFFFFF
   creation_timestamp: 1539023621
   arch: x86_64
   host_type: innotek GmbH|VirtualBox|1.2
   build: 25180
   kernel_version: 4.14.71-404.lts
   payload_format_version: 1
   system_name: clear-linux-os
   board_name: VirtualBox|Oracle Corporation
   cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
   bios_version: VirtualBox
   event_id: 2f070e8e71679f2b1f28794e3a6c42ee
   
   payload read from stdin
   

设置静态计算机 ID

出于隐私，遥测客户端报告的计算机 ID 每三天轮换一次。如果希望获得测试用的静态计算机 ID，则可在 /etc/telemetrics/ 目录中创建名为 opt-in-static-machine-id 的文件来选择启用。

1. 创建 telemetrics 目录。

   sudo mkdir -p /etc/telemetrics
   

2. 创建文件并将 “unique machine ID” 替换为所需的静态计算机 ID。

   echo "unique machine ID" | sudo tee /etc/telemetrics/opt-in-static-machine-id
   

注解

该计算机 ID 不同于系统主机名。

通过 libtelemetry API 检测代码

必备条件

确认遥测头文件位于系统上的 usr/include/telemetry.h。此文件的 latest version 也可在 Github 上找到，以供参考，但安装 telemetry bundle 文件会安装匹配 Clear Linux OS 版本的头文件。

1. include 与变量：

   必须在代码中包含以下标头才能使用 API：

   #define _GNU_SOURCE
   #include <stdlib.h>
   #include <stdio.h>
   #include <string.h>
   #include <telemetry.h>
   

   使用下述代码创建所需变量，以容纳用于创建记录的数据：

   uint32_t severity = 1;
   uint32_t payload_version = 1;
   char classification[30] = "org.clearlinux/hello/world";
   struct telem_ref *tm_handle = NULL;
   char *payload;
   int ret = 0;
   

   严重性：

   类型：uint32_t 值：“严重性”字段值。可接受值介于 1-4 之间，其中 1 表示严重性最低，4 则表示严重性最高。超出此范围的值将被限定为 1 或 4。[low, med, high, crit]

   Payload_version：

   类型：uint32_t 值：有效负载格式版本。目前唯一支持的值为 1，表示有效负载为自由格式化（非结构化）的字符串。大于 1 的值将保留以供未来使用。

   分类：

   类型：字符数组值：它应采用 DOMAIN/PROBENAME/REST 形式：DOMAIN 是用作探针命名空间的反向域（例如 org.clearlinux），PROBENAME 是探针的名称，REST 则是探针用于对记录进行分类的任意值。分类字符串的最大长度为 122 个字节。每个子类别的长度不超过 40 个字节。需使用两个斜线 (/) 分隔符。

   Tm_handle：

   类型：Telem_ref 结构指针值：调用者声明的结构指针。如果函数返回成功，则初始化此结构。

   有效负载：

   类型：结构指针值：要设置的有效负载

2. 在本例中，我们使用 asprintf() 将有效负载设为“hello”：

   if (asprintf(&payload, "hello\n") < 0) {
     exit(EXIT_FAILURE);
      }
   

   函数 asprintf() 和 vasprintf() 与 sprintf(3) 和 vsprintf(3) 类似，除了它们分配一个足够大的字符串来容纳包括终止空字节 (‘0’) 在内的输出，并通过第一个自变量向其返回一个指针。该指针应传递给 free(3)，以便在不再需要时释放已分配的存储空间。

3. 创建新的遥测记录：

   函数 tm_create_record() 可初始化遥测记录并设置此记录的严重性和分类，以及有效负载版本号。存储遥测记录所需的内存已分配，且应在不再需要时通过 tm_free_record() 来释放。

   if ((ret = tm_create_record(&tm_handle, severity,    classification, payload_version)) < 0) {
   printf("Failed to create record: %s\n", strerror(-ret));
   ret = 1;
   goto fail;
   }
   

4. 设置遥测记录的有效负载字段：

   函数 tm_set_payload() 可将所提供的遥测记录数据附加到遥测记录中。当前最大有效负载大小为 8192b。

   if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
      printf("Failed to set record payload: %s\n", strerror(-ret));
      ret = 1;
      goto fail;
   }
   free(payload);
   

   函数 free() 可释放 ptr 指向的内存空间，而 ptr 必须通过先前对 malloc()、calloc() 或 realloc() 的调用返还。否则（或者如果此前曾调用 free(ptr)），则会出现未定义的行为。如果 ‘ptr’ 为空，则不会执行任何操作。

5. 将记录发送到遥测守护程序：

   函数 tm_send_record() 向本地 telemprobd(1) 服务提供记录。由于遥测记录是程序分配的，因此不再需要时，应通过 tm_free_record() 释放。

   if ((ret = tm_send_record(tm_handle)) < 0) {
      printf("Failed to send record to daemon: %s\n", strerror(-ret));
      ret = 1;
      goto fail;
   } else {
      printf("Successfully sent record to daemon.\n");
      ret = 0;
   }
   fail:
   tm_free_record(tm_handle);
   tm_handle = NULL;
   
   return ret;
   

6. 带编译标志的完整示例应用程序：

   创建新文件 test.c 并添加如下代码：

   #define _GNU_SOURCE
   #include <stdlib.h>
   #include <stdio.h>
   #include <string.h>
   #include <telemetry.h>
   
   int main(int argc, char **argv)
   {
         uint32_t severity = 1;
         uint32_t payload_version = 1;
         char classification[30] = "org.clearlinux/hello/world";
         struct telem_ref *tm_handle = NULL;
         char *payload;
   
         int ret = 0;
   
         if (asprintf(&payload, "hello\n") < 0) {
                 exit(EXIT_FAILURE);
         }
   
         if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) {
                 printf("Failed to create record: %s\n", strerror(-ret));
                 ret = 1;
                 goto fail;
         }
   
         if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
                 printf("Failed to set record payload: %s\n", strerror(-ret));
                 ret = 1;
                 goto fail;
         }
   
         free(payload);
   
         if ((ret = tm_send_record(tm_handle)) < 0) {
                 printf("Failed to send record to daemon: %s\n", strerror(-ret));
                 ret = 1;
                 goto fail;
         } else {
                 printf("Successfully sent record to daemon.\n");
                 ret = 0;
         }
   fail:
         tm_free_record(tm_handle);
         tm_handle = NULL;
   
         return ret;
    }
   

   使用以下命令通过 gcc 编译器进行编译：

   gcc test.c -ltelemetry -o test_telem
   

   测试以确保程序正在运行：

   ./test_telem
   Successfully sent record to daemon.
   

   注解

   源代码中记录了以 C 语言编写的 heartbeat probe 的完整示例。

参考

遥测 API

安装 telemetrics bundle 文件包括 libtelemetry C 库，可以提供 telemprobd 和 telempostd 守护程序所用的 API。同时，也可以在应用程序中使用这些守护程序。相关 API 文档位于 Telemetrics client 存储库的 telemetry.h 文件中。

客户端配置

遥测客户端会查找位于 /etc/telemetrics/telemetrics.conf 中的配置文件。如果存在，则会使用。如果此文件不存在，客户端则会使用位于 /usr/share/defaults telemetrics/telemetrics.conf 的默认配置。要修改或定制配置，请将此文件从 /usr/share/defaults/telemetrics 复制到 /etc/telemetrics 并对其进行编辑。

配置选项

客户端使用配置文件中的以下配置选项：

服务器

此选项指定接收 telempostd 发送的遥测记录的网络服务器。

socket_path

此选项指定 telemprobd 在其上侦听探针连接的 unix 域套接字路径。

spool_dir

此配置选项与假脱机相关。如果守护程序因网络可用性等原因无法将遥测记录发送到后端服务器，则会将记录存储在假脱机目录中。此选项指定了假脱机目录的路径。此目录的所有者应与守护程序的所有者为同一用户。

record_expiry

此选项为时间选项（以分钟为单位）。超过此时间后，守护程序会删除假脱机目录中的记录。

spool_process_time

此选项指定了在检查假脱机目录是否存在记录之前，守护程序等待的时间间隔（以秒为单位）。守护程序将按修改日期顺序选取记录，并尝试将记录发送到服务器。它一次最多可发送 10 条记录。如果无法成功发送记录，则会从假脱机目录中删除此记录。如果守护程序找到早于 “record_expiry” 时间的记录，则会删除此记录。守护程序在单个假脱机运行循环中最多会查找 20 条记录。

rate_limit_enabled

此选项将确定是启用还是禁用速率限制。启用后，在某一时间窗口内发送的两个记录均有一个阈值，同时记录在一个窗口内一次发送的字节数。

record_burst_limit

此选项是指守护程序在 record_window_length 时间内允许传递的最大记录数。如果将其设为 -1，则会禁用针对记录突发的速率限制。

record_window_length

此选项为时间选项（以分钟为单位 (0-59)），用于设定 record_burst_limit 的窗口长度。例如：如果 record_burst_window = 1000 且 record_window_length = 15，则在任意给定的 15 分钟窗口内可传递的记录数不会超过 1,000 条。

byte_burst_limit

此选项是指守护程序在 byte_window_length 时间内可传递的最大字节数。如果将其设为 -1，则会禁用针对字节突发的速率限制。

byte_window_length

此选项为时间选项（以分钟为单位 (0-59)），用于设定 byte_burst_limit 的窗口长度。

rate_limit_strategy

此选项是指在达到速率限制阈值后所选择的策略。目前，选项为“drop”或“spool”，其中 spool 为默认值。如果选择 spool，则会对记录进行假脱机并在以后发送。

record_retention_enabled

启用此键 (true) 后，守护程序会在磁盘上保存所有有效记录中有效负载的副本。为避免过多使用磁盘空间，系统仅保留最近的 100 条记录。此配置键的默认值为 false。

record_server_delivery_enabled

此键控制向服务器传送记录；启用（默认值）后，会将记录发送到配置文件中所列的地址。如果禁用此配置键 (false)，则不会对记录进行假脱机或将记录发布到后端。此配置键可与 record_retention_enabled 搭配使用，仅在本地保留遥测记录的副本。

注解

随着遥测客户端的发展，配置选项可能会发生变化。请使用文件自身所附带的注释，作为最准确的配置参考。

客户端运行时选项

Clear Linux OS 遥测客户端提供名为 telemctl 的管理工具，可用于管理遥测服务和探针。此工具位于 /usr/bin。如果不带参数运行此工具，则会导致如下情况：

sudo telemctl

/usr/bin/telemctl - Control actions for telemetry services
  stop       Stops all running telemetry services
  start      Starts all telemetry services
  restart    Restarts all telemetry services
  is-active  Checks if telemprobd and telempostd are active
  opt-in     Opts in to telemetry, and starts telemetry services
  opt-out    Opts out of telemetry, and stops telemetry services
  journal    Prints telemetry journal contents. Use -h argument for more
             options

start/stop/restart

用于启动、停止和重新启动遥测服务的命令可以管理系统上所有必要的服务和探针。无需单独启动/停止/重新启动两个客户端守护程序 telemprobd 和 telempostd。restart 命令选项将调用 telemctl stop，然后调用 telemctl start。

is-active

is-active 选项报告这两个客户端守护程序是否处于活动状态。这有助于验证 opt-in 和 opt-out 选项是否生效，或确保遥测正在系统上运行。请注意，系统会对两个守护程序都进行验证。

sudo telemctl is-active

telemprobd : active
telempostd : active