oeAware User Guide

Introduction

oeAware is a framework for implementing low-load collection, sensing, and tuning on openEuler. It aims to intelligently enable optimization features after dynamically detecting system behaviors. Traditional optimization features run independently and are statically enabled or disabled. oeAware divides optimization into three layers: collection, sensing, and tuning. Each layer is associated through subscription and is developed as plugins.

Installation

Configure the openEuler Yum repository and run the yum commands to install oeAware.

yum install oeAware-manager

Usage

Start the oeaware service. Use the oeawarectl command to control the service.

Service Startup

Run the systemd command to start the service.

systemctl start oeaware

Configuration file

Configuration file path: /etc/oeAware/config.yaml

log_path: /var/log/oeAware # Log storage path
log_level: 1 # Log level. 1: DUBUG; 2: INFO; 3: WARN; 4: ERROR.
enable_list: # Plugins are enabled by default.
	- name: libtest.so # Configure the plugin and enable all instances of the plugin.
	- name: libtest1.so # Configure the plugin and enable the specified plugin instances.
	  instances:
		- instance1 
		- instance2
		...
	...
plugin_list: # Downloaded packages are supported.
  - name: test #The name must be unique. If the name is repeated, the first occurrence is used.
    description: hello world
    url: https://gitee.com/openeuler/oeAware-manager/raw/master/README.md #url must not be empty.
  ...

After modifying the configuration file, run the following commands to restart the service:

systemctl daemon-reload
systemctl restart oeaware

Plugin Description

Plugin definition: Each plugin corresponds to an .so file. Plugins are classified into collection plugins, sensing plugins, and tuning plugins.

Instance definition: The scheduling unit in the service is instance. A plugin contains multiple instances. For example, a collection plugin includes multiple collection items, and each collection item is an instance.

Dependencies Between Instances

Before running an instance, ensure that the dependency between the instances is met.

A collection instance does not depend on any other instance.
A sensing instance depends on a collection instance and other sensing instances.
A tuning instance depends on a collection instance, sensing instance, and other tuning instances.

Plugin Loading

By default, the service loads the plugins in the plugin storage paths.

Collection plugin path: /usr/lib64/oeAware-plugin/collector

Sensing plugin path: /usr/lib64/oeAware-plugin/scenario

Tuning plugin path: /usr/lib64/oeAware-plugin/tune

You can also manually load the plugins.

oeawarectl -l | --load <plugin name> -t | --type <plugin type> # plugin type can be collector, scenario, or tune

Example

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

If the operation fails, an error description is returned.

Plugin Unloading

oeawarectl -r <plugin name> | --remove <plugin name>

Example

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

If the operation fails, an error description is returned.

Plugin Query

Query the cell status

oeawarectl -q # Query all loaded plugins.
oeawarectl --query <plugin name> # Query a specified plugin.

Example

[root@localhost ~]# oeawarectl -q
Show plugins and instances status.
------------------------------------------------------------
libthread_scenario.so
	thread_scenario(available, close)
libpmu.so
	collector_pmu_sampling(available, close)
	collector_pmu_counting(available, close)
	collector_pmu_uncore(available, close)
	collector_spe(available, close)
libthread_collector.so
	thread_collector(available, close)
------------------------------------------------------------
format:
[plugin]
	[instance]([dependency status], [running status])
dependency status: available means satisfying dependency, otherwise unavailable.
running status: running means that instance is running, otherwise close.

If the operation fails, an error description is returned.

Querying Plugin Dependencies

oeawarectl -Q # Query the dependency graph of loaded instances.
oeawarectl --query-dep= <plugin instance> # Query the dependency graph of a specified instance.

A dep.png file will be generated in the current directory to display the dependencies.

Example

Relationship diagram when dependencies are met

Relationship diagram when dependencies are not met

If the operation fails, an error description is returned.

Enabling Plugins

Enabling a Plugin Instance

oeawarectl -e | --enable <plugin instance>

If the operation fails, an error description is returned.

Disabling a Plugin Instance

oeawarectl -d | --disable <plugin instance>

If the operation fails, an error description is returned.

Downloading and Installing Plugins

Use the --list command to query the RPM packages that can be downloaded and installed plugins.

oeawarectl --list

The query result is as follows:

Supported Packages: # Downloadable packages
[name1] # plugin_list configured in config
[name2]
...
Installed Plugins: # Installed plugins
[name1]
[name2]
...

Use the --install command to download and install the RPM package.

oeawarectl -i | --install <RPM package name > # Name of a package queried using --list (package in Supported Packages)

If the operation fails, an error description is returned.

Help

Use the --help command for help information.

usage: oeawarectl [options]...
  options
    -l|--load [plugin]      load plugin and need plugin type.
    -t|--type [plugin_type] assign plugin type. there are three types:
                            collector: collection plugin.
                            scenario: awareness plugin.
                            tune: tune 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.

Plugin Development

Common Data Structures of Plugins

struct DataBuf {
    int len;
    void *data;
};

struct DataBuf is the data buffer.

data: specific data. data is an array. The data type can be defined as required.
len: size of data.

struct DataHeader {
    char type[DATA_HEADER_TYPE_SIZE];
    int index;
    uint64_t count;
    struct DataBuf *buf;
    int buf_len;
};

struct DataHeader is the structure for transferring data between plugins. It contains a cyclic buffer.

type: type of the input data. For example, when data is transferred to a sensing plugin, this parameter is used to identify the collection item of the collection plugin.
index: location of the data that is being written. For example, after a data collection, index increases by one.
count: number of times that an instance is executed. The value is accumulated.
buf: data buffer. For example, some collection items are used by a sensing plugin only after being sampled for multiple times. Therefore, the collection items are saved in a buffer array.
buf_len: size of the data buffer. buf_len is a fixed value after the data buffer is initialized.

Collection Plugin

A collection plugin must have the int32_t get_instance(CollectorInterface *ins) interface to return all collection items contained in the plugin. CollectorInterface contains the following content:

struct CollectorInterface {
    char* (*get_version)();
    char* (*get_name)();
    char* (*get_description)();
    char* (*get_type)();
    int (*get_cycle)();
    char* (*get_dep)();
    void (*enable)();
    void (*disable)();
    void* (*get_ring_buf)();
    void (*reflash_ring_buf)();
};

Obtaining the version number

Interface definition
```
char* (*get_version)();
```
Interface description
Parameter description
Return value description
The specific version number is returned. This interface is reserved.

Obtaining the instance name

Interface definition
```
char* (*get_name)();
```
Interface description
Obtains the name of a collection instance. When you run the -q command on the client, the instance name is displayed. In addition, you can run the --enable command to enable the instance.
Parameter description
Return value description
The name of the collection instance is returned. Ensure that the instance name is unique.

Obtaining description information

Interface definition
```
char* (*get_description)();
```
Interface description
Parameter description
Return value description
The detailed description is returned. This interface is reserved.

Obtaining the type

Interface definition
```
char* (*get_type)();
```
Interface description
Parameter description
Return value description
The specific type information is returned. This interface is reserved.

Obtaining the sampling period

Interface definition
```
int (*get_cycle)();
```
Interface description
Obtains the sampling period. Different collection items can use different collection periods.
Parameter description
Return value description
The specific sampling period is returned. The unit is ms.

Obtaining dependencies

Interface definition
```
char* (*get_dep)();
```
Interface description
Parameter description
Return value description
Information about the dependent instances is returned. This interface is reserved.

Enabling a collection instance

Interface definition
```
void (*enable)();
```
Interface description
Enables a collection instance.
Parameter description
Return value description

Disabling a collection instance

Interface definition
```
void (*disable)();
```
Interface description
Disables a collection instance.
Parameter description
Return value description

Obtaining the collection data buffer

Interface definition
```
void* (*get_ring_buf)();
```
Interface description
Obtains the buffer management pointer of the collection data (the memory is applied for by the plugin). The pointer is used by sensing plugins.
Parameter description
Return value description
The struct DataHeader management pointer is returned, which stores the data of multiple samples.

Refreshing collection data

Interface definition
```
void (*reflash_ring_buf)();
```
Interface description
Periodically obtains sampled data based on the sampling period and saves the data to struct DataBuf.
Parameter description
Return value description

Sensing Plugin

A sensing plugin must have the int32_t get_instance(ScenarioInterface *ins) interface to return all collection items contained in the plugin. ScenarioInterface contains the following content:

struct ScenarioInterface {
    char* (*get_version)();
    char* (*get_name)();
    char* (*get_description)();
    char* (*get_dep)();
    int (*get_cycle)();
    void (*enable)();
    void (*disable)();
    void (*aware)(void*[], int);
    void* (*get_ring_buf)();
};

Obtaining the version number

Interface definition
```
char* (*get_version)();
```
Interface description
Parameter description
Return value description
The specific version number is returned. This interface is reserved.

The specific version number is returned. This interface is reserved.

Interface definition
```
char* (*get_name)();
```
Interface description
Obtains the name of a sensing instance. When you run the -q command on the client, the instance name is displayed. In addition, you can run the --enable command to enable the instance.
Parameter description
Return value description
The name of the sensing instance is returned. Ensure that the instance name is unique.

Obtaining description information

Interface definition
```
char* (*get_description)();
```
Interface description
Parameter description
Return value description
The detailed description is returned. This interface is reserved.

Obtaining dependencies

Interface definition
```
char* (*get_dep)();
```
Interface description
Parameter description
Return value description
Names of the dependent instances are returned. This interface is reserved. Multiple dependent instances are connected by hyphens (-). For example, if the sensing instance depends on collection instance A and collection instance B, A-B is returned. If instance A contains a hyphen in its name, an error is reported.

Obtaining the sensing period

Interface definition
```
int (*get_cycle)();
```
Interface description
Obtains the sensing period.
Parameter description
Return value description
The specific sensing period is returned. The unit is ms.

Enabling a sensing instance

Interface definition
```
void (*enable)();
```
Interface description
Enables a sensing instance.
Parameter description
Return value description

Disabling a sensing instance

Interface definition
```
void (*disable)();
```
Interface description
Disables a sensing instance.
Parameter description
Return value description

Performing Sensing

Interface definition
```
void (*aware)(void*[], int);
```
Interface description
Processes and analyzes collected data. For example, the collected uncore PMU data is processed and analyzed for NUMA issues.
Parameter description
- void[]*: array of struct DataHeader.
- int: array length of struct DataHeader.
Return value description

Obtaining the sensing data buffer

Interface definition
```
void* (*get_ring_buf)();
```
Interface description
Obtains the buffer management pointer of the sensing data (the memory is applied for by the plugin). The pointer is used by tuning plugins.
Parameter description
Return value description
The struct DataHeader management pointer is returned.

Tuning Plugin

Constraints

Function Constraints

By default, oeAware integrates the libkperf module for collecting Arm microarchitecture information. This module can be called by only one process at a time. If this module is called by other processes or the perf command is used, conflicts may occur.

Operation Constraints

Currently, only the root user can operate oeAware.

Notes

The user group and permission of the oeAware configuration file and plugins are strictly verified. Do not modify the permissions and user group of oeAware-related files.

Permissions:

Plugin files: 440
Client executable file: 750
Server executable file: 750
Service configuration file: 640

oeAware User Guide

Introduction

Installation

Usage

Service Startup

Plugin Description

Plugin Loading

Plugin Unloading

Plugin Query

Query the cell status

Querying Plugin Dependencies

Enabling Plugins

Enabling a Plugin Instance

Disabling a Plugin Instance

Downloading and Installing Plugins

Help

Plugin Development

Common Data Structures of Plugins

Collection Plugin

Sensing Plugin

Tuning Plugin

Constraints

Function Constraints

Operation Constraints

Notes

Bug Catching

Buggy Content

Bug Description

How satisfied are you with this document