长期支持版本

    社区创新版本

      oeAware用户指南

      简介

      oeAware是在openEuler上实现低负载采集感知调优的框架,目标是动态感知系统行为后智能使能系统的调优特性。传统调优特性都以独立运行且静态打开关闭为主,oeAware将调优拆分采集、感知和调优三层,每层通过订阅方式关联,各层采用插件式开发尽可能复用。

      安装

      配置openEuler的yum源,使用yum命令安装。在openEuler-22.03-LTS-SP4版本中会默认安装。

      yum install oeAware-manager
      

      使用方法

      首先启动oeaware服务,然后通过oeawarectl命令进行使用。

      服务启动

      通过systemd服务启动。安装完成后会默认启动。

      systemctl start oeaware
      

      配置文件

      配置文件路径:/etc/oeAware/config.yaml

      log_path: /var/log/oeAware #日志存储路径
      log_level: 1 #日志等级 1:DEBUG 2:NFO 3:WARN 4:ERROR
      enable_list: #默认使能插件
      	- name: libtest.so #只配置插件,使能本插件的所有实例
      	- name: libtest1.so #配置插件实例,使能配置的插件实例
      	  instances:
      		- instance1 
      		- instance2
      		...
      	...
      plugin_list: #可支持下载的包
        - name: test #名称需要唯一,如果重复取第一个配置
          description: hello world
          url: https://gitee.com/openeuler/oeAware-manager/raw/master/README.md #url非空
        ...
      

      修改配置文件后,通过以下命令重启服务。

      systemctl restart oeaware
      

      插件说明

      插件定义:一个插件对应一个.so文件,插件分为采集插件、感知插件和调优插件。

      实例定义:服务中的调度单位是实例,一个插件中包括多个实例。例如,一个采集插件包括多个采集项,每个采集项是一个实例。

      插件加载

      服务会默认加载插件存储路径下的插件。

      插件路径:/usr/lib64/oeAware-plugin/

      另外也可以通过手动加载的方式加载插件。

      oeawarectl -l | --load <插件名>
      

      示例

      [root@localhost ~]# oeawarectl -l libthread_collect.so
      Plugin loaded successfully.
      

      失败返回错误说明。

      插件卸载

      oeawarectl -r <插件名> | --remove <插件名>
      

      示例

      [root@localhost ~]# oeawarectl -r libthread_collect.so
      Plugin remove successfully.
      

      失败返回错误说明。

      插件查询

      查询插件状态信息

      oeawarectl -q  #查询系统中已经加载的所有插件
      oeawarectl --query <插件名> #查询指定插件
      

      示例

      [root@localhost ~]# oeawarectl -q
      Show plugins and instances status.
      ------------------------------------------------------------
      libsystem_tune.so
              stealtask_tune(available, close, count: 0)
              smc_tune(available, close, count: 0)
              xcall_tune(available, close, count: 0)
              seep_tune(available, close, count: 0)
      libpmu.so
              pmu_counting_collector(available, close, count: 0)
              pmu_sampling_collector(available, close, count: 0)
              pmu_spe_collector(available, close, count: 0)
              pmu_uncore_collector(available, close, count: 0)
      libdocker_tune.so
              docker_cpu_burst(available, close, count: 0)
      libthread_scenario.so
              thread_scenario(available, close, count: 0)
      libsystem_collector.so
              thread_collector(available, close, count: 0)
              kernel_config(available, close, count: 0)
              command_collector(available, close, count: 0)
      libdocker_collector.so
              docker_collector(available, close, count: 0)
      libub_tune.so
              unixbench_tune(available, close, count: 0)
      libanalysis_oeaware.so
              analysis_aware(available, close, count: 0)
      ------------------------------------------------------------
      format:
      [plugin]
              [instance]([dependency status], [running status], [enable cnt])
      dependency status: available means satisfying dependency, otherwise unavailable.
      running status: running means that instance is running, otherwise close.
      enable cnt: number of instances enabled.
      

      失败返回错误说明。

      查询运行实例订阅关系

      oeawarectl -Q  #查询所有运行实例的订阅关系图
      oeawarectl --query-dep= <插件实例>  #查询运行实例订阅关系图
      

      在当前目录下生成dep.png,显示订阅关系。

      实例未运行,不会显示订阅关系。

      示例

      oeawarectl -e thread_scenario
      oeawarectl -Q
      

      img

      插件实例使能

      使能插件实例

      oeawarectl -e | --enable <插件实例>
      

      使能某个插件实例,会将其订阅的topic实例一起使能。

      失败返回错误说明。

      推荐使能插件列表:

      • libsystem_tune.so:stealtask_tune,smc_tune,xcall_tune,seep_tune。
      • libub_tune.so:unixbench_tune。
      • libtune_numa.so:tune_numa_mem_access。

      其他插件主要用来提供数据,可通过sdk获取插件数据。

      关闭插件实例

      oeawarectl -d | --disable <插件实例>
      

      关闭某个插件实例,会将其订阅的topic实例一起关闭。

      失败返回错误说明。

      插件下载安装

      通过--list命令查询支持下载的rpm包和已安装的插件。

      oeawarectl --list
      

      查询结果如下。

      Supported Packages: #可下载的包
      [name1] #config中配置的plugin_list
      [name2]
      ...
      Installed Plugins: #已安装的插件
      [name1]
      [name2]
      ...
      

      通过--install命令下载安装rpm包。

      oeawarectl -i | --install <rpm包名> #指定--list下查询得到的包名称(Supported Packages下的包)
      

      失败返回错误说明。

      分析模式

      oeawarectl analysis -h
      usage: oeawarectl analysis [options]...
        options
         -t|--time <s>              set analysis duration in seconds(default 30s), range from 1 to 100.
         -r|--realtime              show real time report.
         -v|--verbose               show verbose information.
         -h|--help                  show this help message.
      

      示例

      执行以下命令,输出系统分析报告。

      oeawarectl analysis -t 10
      

      结果如下

      ============================================================================================
                                           Summary Analysis Report
      ============================================================================================
       ========================================= Suggest =========================================
       Tune Instance                  | Suggest    | Note
       stealtask_tune                 | No         | CpuRatio(average) :   0.17%
       smc_tune                       | No         | Collecting very little network access
       gazelle                        | No         | Collecting very little network access
       tune_numa_mem_access           | No         | No access
       ========================================= Network =========================================
      
       Local network communication distribution
        Node0   Node1   Node2   Node3
        0.00%   0.00%   0.00%   0.00%
       Remote network communication distribution(receive)
       matrix representation of network thread nodes to irq nodes
               Node0   Node1   Node2   Node3
       Node0 100.00%   0.00%   0.00%   0.00%
       Node1   0.00%   0.00%   0.00%   0.00%
       Node2   0.00%   0.00%   0.00%   0.00%
       Node3   0.00%   0.00%   0.00%   0.00%
       ======================================== Solution ========================================
       No solution.
      

      报告分为三部分

      • Suggest:根据系统运行状态,给出调优建议。
      • Network:网络使用情况。
      • Solution:给出具体调优方法。

      帮助

      通过--help查看帮助。

      usage: oeawarectl [options]...
        options
          -l|--load [plugin]      load plugin.
          -r|--remove [plugin]    remove plugin from system.
          -e|--enable [instance]  enable the plugin instance.
          -d|--disable [instance] disable the plugin instance.
          -q                      query all plugins information.
          --query [plugin]        query the plugin information.
          -Q                      query all instances dependencies.
          --query-dep [instance]  query the instance dependency.
          --list                  the list of supported plugins.
          -i|--install [plugin]   install plugin from the list.
          --help                  show this help message.
      

      插件开发说明

      基础数据结构

      typedef struct {
          char *instanceName; // 实例名称
          char *topicName; // 主题名称
          char *params; // 参数
      } CTopic;
      
      typedef struct {
          CTopic topic;
          unsigned long long len; // data数组的长度
          void **data; // 存储的数据
      } DataList;
      
      const int OK = 0;
      const int FAILED = -1;
      
      typedef struct {
          int code; // 成功返回OK,失败返回FAILED
          char *payload; // 附带信息
      } Result;
      

      实例基类

      namespace oeaware {
      // Instance type.
      const int TUNE = 0b10000;
      const int SCENARIO = 0b01000;
      const int RUN_ONCE = 0b00010;
      class Interface {
      public:
          virtual Result OpenTopic(const Topic &topic) = 0;
          virtual void CloseTopic(const Topic &topic) = 0;
          virtual void UpdateData(const DataList &dataList) = 0;
          virtual Result Enable(const std::string &param = "") = 0;
          virtual void Disable() = 0;
          virtual void Run() = 0;
      protected:
          std::string name;
          std::string version;
          std::string description;
          std::vector<Topic> supportTopics;
          int priority;
          int type;
          int period;
      }
      }
      

      实例开发继承实例基类,实现6个虚函数,并对类的7个属性赋值。

      实例采用订阅发布模式,通过Subscribe获取数据,通过Publish接口发布数据。

      属性说明

      属性类型说明
      namestring实例名称
      versionstring实例版本(预留)
      descriptionstring实例描述
      supportTopicsvector支持的topic
      priorityint实例执行的优先级 (调优 > 感知 > 采集)
      typeint实例类型,通过比特位标识,第二位表示单次执行实例,第三位表示采集实例,第四位表示感知实例,第5位表示调优实例
      periodint实例执行周期,单位ms,period为10的倍数

      接口说明

      函数名参数返回值说明
      Result OpenTopic(const Topic &topic)topic:打开的主题打开对应的topic
      void CloseTopic(const Topic &topic)topic:关闭的主题关闭对应的topic
      void UpdateData(const DataList &dataList)dataList:订阅的数据当订阅topic时,被订阅的topic每周期会通过UpdateData更新数据
      Result Enable(const std::string &param = "")param:预留使能本实例
      void Disable()关闭本实例
      void Run()每周期会执行run函数

      实例示例

      #include <oeaware/interface.h>
      #include <oeaware/data/thread_info.h>
      
      class Test : public oeaware::Interface {
      public:
          Test() {
              name = "TestA";
              version = "1.0";
              description = "this is a test plugin";
              supportTopics;
              priority = 0;
              type = 0;
              period = 20;
          }
          oeaware::Result OpenTopic(const oeaware::Topic &topic) override {
              return oeaware::Result(OK);
          }
          void CloseTopic(const oeaware::Topic &topic) override {
      
          }
          void UpdateData(const DataList &dataList) override {
              for (int i = 0; i < dataList.len; ++i) {
                  ThreadInfo *info = static_cast<ThreadInfo*>(dataList.data[i]);
                  INFO(logger, "pid: " << info->pid << ", name: " << info->name);
              }
          }
          oeaware::Result Enable(const std::string &param = "") override {
              Subscribe(oeaware::Topic{"thread_collector", "thread_collector", ""});
              return oeaware::Result(OK);
          }
          void Disable() override {
              
          }
          void Run() override {
              DataList dataList;
              oeaware::SetDataListTopic(&dataList, "test", "test", "");
              dataList.len = 1;
              dataList.data = new void* [1];
              dataList.data[0] = &pubData; 
              Publish(dataList);
          }
      private:
          int pubData = 1;
      };
      
      extern "C" void GetInstance(std::vector<std::shared_ptr<oeaware::Interface>> &interfaces)
      {
          interfaces.emplace_back(std::make_shared<Test>());
      }
      

      内部插件

      libpmu.so

      实例名称架构说明topic
      pmu_counting_collectoraarch64采集count相关事件cycles,net:netif_rx,L1-dcache-load-misses,L1-dcache-loads,L1-icache-load-misses,L1-icache-loads,branch-load-misses,branch-loads,dTLB-load-misses,dTLB-loads,iTLB-load-misses,iTLB-loads,cache-references,cache-misses,l2d_tlb_refill,l2d_cache_refill,l1d_tlb_refill,l1d_cache_refill,inst_retired,instructions
      pmu_sampling_collectoraarch64采集sample相关事件cycles, skb:skb_copy_datagram_iovec,net:napi_gro_receive_entry
      pmu_spe_collectoraarch64采集spe事件spe
      pmu_uncore_collectoraarch64采集uncore事件uncore

      限制条件

      采集spe事件需要依赖硬件能力,此插件运行依赖 BIOS 的 SPE,运行前需要将 SPE 打开。

      运行perf list | grep arm_spe查看是否已经开启SPE,如果开启,则有如下显示

      arm_spe_0//                                      [Kernel PMU event]
      

      如果没有开启,则按下述步骤开启。

      检查BIOS配置项 MISC Config --> SPE 的状态, 如果状态为 Disable,则需要更改为 Enable。如果找不到这个选项,可能是BIOS版本过低。

      进入系统 vim /etc/grub2-efi.cfg,定位到内核版本对应的开机启动项,在末尾增加“kpti=off”。例如:

      linux   /vmlinuz-4.19.90-2003.4.0.0036.oe1.aarch64 root=/dev/mapper/openeuler-root ro rd.lvm.lv=openeuler/root rd.lvm.lv=openeuler/swap video=VGA-1:640x480-32@60me rhgb quiet  smmu.bypassdev=0x1000:0x17 smmu.bypassdev=0x1000:0x15 crashkernel=1024M,high video=efifb:off video=VGA-1:640x480-32@60me kpti=off
      

      按“ESC”,输入“:wq”,按“Enter”保存并退出。执行reboot命令重启服务器。

      libsystem_collector.so

      系统信息采集插件。

      实例名称架构说明topic
      thread_collectoraarch64/x86采集系统中的线程信息thread_collector
      kernel_configaarch64/x86采集内核相关参数,包括sysctl所有参数、lscpu、meminfo等get_kernel_config,get_cmd,set_kernel_config
      command_collectoraarch64/x86采集sysstat相关数据mpstat,iostat,vmstat,sar,pidstat

      libdocker_collector.so

      docker信息采集插件。

      实例名称架构说明topic
      docker_collectoraarch64/x86采集docker相关信息docker_collector

      libthread_scenario.so

      线程感知插件。

      实例名称架构说明订阅
      thread_scenarioaarch64/x86通过配置文件获取对应线程信息thread_collector::thread_collector

      配置文件

      thread_scenario.conf

      redis
      fstime
      fsbuffer
      fsdisk
      

      libanalysis_oeaware.so

      实例名称架构说明订阅
      analysis_aware分析当前环境的业务特征,并给出优化建议aarch64pmu_spe_collector::spe, pmu_counting_collector::net:netif_rx, pmu_sampling_collector::cycles, pmu_sampling_collector::skb:skb_copy_datagram_iovec, pmu_sampling_collector::net:napi_gro_receive_entry

      libsystem_tune.so

      系统调优插件。

      实例名称架构说明订阅
      stealtask_tuneaarch64高负载场景下,通过轻量级搜索算法,实现多核间快速负载均衡,最大化cpu资源利用率
      smc_tuneaarch64使能smc加速,对使用tcp协议的连接无感加速
      xcall_tuneaarch64通过减少系统调用底噪,提升系统性能thread_collector::thread_collector
      seep_tuneaarch64使能智能功耗模式,降低系统能耗

      配置文件

      xcall.yaml

      redis: # 线程名称
          - xcall_1: 1 #xcall_1表示xcall优化方式,目前只有xcall_1; 1表示需要优化系统调用号
      mysql:
          - xcall_1: 1
      node:
          - xcall_1: 1
      

      限制条件

      xcall_tune依赖内核特性,需要开启FAST_SYSCALL编译内核,并且增加在cmdline里增加xcall字段。

      libub_tune.so

      unixbench调优插件。

      实例名称架构说明订阅
      unixbench_tuneaarch64/x86通过减少远端内存访问,优化ub性能thread_collector::thread_collector

      libdocker_tune.so

      实例名称架构说明订阅
      docker_cpu_burstaarch64在出现突发负载时,CPUBurst可以为容器临时提供额外的CPU资源,缓解CPU限制带来的性能瓶颈pmu_counting_collector::cycles,docker_collector::docker_collector

      外部插件

      外部插件需要通过以下命令安装,例如安装numafast相关插件

      oeawarectl -i numafast
      

      libscenario_numa.so

      实例名称架构说明订阅topic
      scenario_numaaarch64感知当前环境跨NUMA访存比例,用于实例或sdk订阅(无法单独使能)pmu_uncore_collector::uncoresystem_score

      libtune_numa.so

      实例名称架构说明订阅
      tune_numa_mem_accessaarch64周期性迁移线程和内存,减少跨NUMA内存访问scenario_numa::system_score, pmu_spe_collector::spe, pmu_counting_collector::cycles

      SDK使用说明

      typedef int(*Callback)(const DataList *);
      int OeInit(); // 初始化资源,与server建立链接
      int OeSubscribe(const CTopic *topic, Callback callback); // 订阅topic,异步执行callback
      int OeUnsubscribe(const CTopic *topic); // 取消订阅topic
      int OePublish(const DataList *dataList); // 发布数据到server
      void OeClose(); // 释放资源
      

      示例

      #include "oe_client.h"
      #include "command_data.h"
      int f(const DataList *dataList)
      {
          int i = 0;
          for (; i < dataList->len; i++) {
              CommandData *data = (CommandData*)dataList->data[i];
              for (int j = 0; j < data->attrLen; ++j) {
                  printf("%s ", data->itemAttr[j]);
              }
              printf("\n");
          }
          return 0;
      }
      int main() {
          OeInit();
          CTopic topic = {
              "command_collector",
              "sar",
              "-q 1",
          };
          if (OeSubscribe(&topic, f) < 0) {
              printf("failed\n");
          } else {
              printf("success\n");
          }
          sleep(10);
          OeClose();
      }
      

      约束限制

      功能约束

      oeAware默认集成了arm的微架构采集libkperf模块,该模块同一时间只能有一个进程进行调用,如其他进程调用或者使用perf命令可能存在冲突。

      操作约束

      当前oeAware仅支持root组用户进行操作,sdk支持root组和oeaware组用户使用。

      注意事项

      oeAware的配置文件和插件用户组和权限有严格校验,不要对oeAware的相关文件进行权限和用户组进行修改。

      权限说明:

      • 插件文件:440

      • 客户端执行文件:750

      • 服务端执行文件:750

      • 服务配置文件:640

      文档捉虫

      “有虫”文档片段

      问题描述

      提交类型 issue

      有点复杂...

      找人问问吧。

      PR

      小问题,全程线上修改...

      一键搞定!

      问题类型
      规范和低错类

      ● 错别字或拼写错误;标点符号使用错误;

      ● 链接错误、空单元格、格式错误;

      ● 英文中包含中文字符;

      ● 界面和描述不一致,但不影响操作;

      ● 表述不通顺,但不影响理解;

      ● 版本号不匹配:如软件包名称、界面版本号;

      易用性

      ● 关键步骤错误或缺失,无法指导用户完成任务;

      ● 缺少必要的前提条件、注意事项等;

      ● 图形、表格、文字等晦涩难懂;

      ● 逻辑不清晰,该分类、分项、分步骤的没有给出;

      正确性

      ● 技术原理、功能、规格等描述和软件不一致,存在错误;

      ● 原理图、架构图等存在错误;

      ● 命令、命令参数等错误;

      ● 代码片段错误;

      ● 命令无法完成对应功能;

      ● 界面错误,无法指导操作;

      风险提示

      ● 对重要数据或系统存在风险的操作,缺少安全提示;

      内容合规

      ● 违反法律法规,涉及政治、领土主权等敏感词;

      ● 内容侵权;

      您对文档的总体满意度

      非常不满意
      非常满意
      提交
      根据您的反馈,会自动生成issue模板。您只需点击按钮,创建issue即可。
      文档捉虫
      编组 3备份