diff --git a/README.md b/README.md index 704cc81..a6fab89 100644 --- a/README.md +++ b/README.md @@ -1 +1,208 @@ -# telemetry +# Telemetry + +## About + +**Telemetry** is a comprehensive library designed for the collection and processing of telemetry data. +It offers data structures for representing directories, files, and their contents, along with methods +for reading and writing telemetry data. The library enables efficient management of telemetry data +in various applications. + +**AppFs** is a complementary library that integrates with Telemetry to expose telemetry data through +a FUSE (Filesystem in Userspace) interface. This integration allows telemetry data to be accessed and +manipulated as if it were part of the local filesystem, enabling standard filesystem operations such +as reading and writing files. This makes the telemetry data easy to manage and monitor using familiar +file-based tools and utilities. + +## Key Features: + +- Efficient telemetry data collection and management. +- Data structures to represent telemetry files, directories, and metrics. +- AppFs integration, providing a FUSE-based interface for filesystem-style telemetry data access. +- Flexibility for real-time monitoring and manipulation of telemetry data. + +## How to Build + +### Build Dependencies + +To build the Telemetry and AppFs libraries, ensure that you have the following build dependencies installed. + +#### RHEL/CentOS: + +```bash +yum install gcc-c++ make cmake3 fuse3-devel +# Optionally: rpm-build for RPM packaging +``` + +#### Clone and Build the Libraries +First, clone the repository and build the Telemetry and AppFs libraries: + +```bash +$ git clone https://github.com/CESNET/telemetry.git +$ cd telemetry +$ make install +``` + +This will install the necessary libraries, including both Telemetry and AppFs. + +#### Optional: Build RPM Package +If you prefer to create an RPM package for installation: + +```bash +$ git clone https://github.com/CESNET/telemetry.git +$ cd telemetry +$ make rpm +``` + +This will package the Telemetry library as an RPM, making installation easier across systems using package managers. + +## How to start + +The repository includes two example files: a simple example and an advanced example in the `examples` directory. +You can use these to get started with the library and adapt the example code to fit your needs. + +## Running the Examples + +To run the examples, first build them: + +```bash +$ make examples +``` + +Then, execute the simple example with the desired mount point: + +```bash +$ ./simple-example /tmp/telemetry +``` + +This will create a directory structure representing telemetry data in the specified mount point (e.g., /tmp/telemetry), +where data can be accessed and manipulated using standard filesystem operations. + +## Simple Example + +Once the simple example is running, it will create a directory structure similar to the following: + +```bash +/tmp/telemetry/ +├── parameters +├── pid +├── start_time +├── uptime +└── version +``` + +Example output from the files in the simple example: + +```bash +$ cat /tmp/telemetry/* +./simple-example /tmp/telemetry/ # parameters +1528349 # pid +2024-10-07 15:30:22 # start_time +154 (s) # uptime +1.0.0 # version +``` + +## Advanced Example + +The advanced example demonstrates a telemetry data structure that organizes and stores metrics +from multiple servers located in different data centers. + +### Advanced Example Directory Structure +After running the advanced example, the resulting directory structure is as follows: + +```bash +$ tree /tmp/telemetry +/tmp/telemetry +└── data_centers + ├── new_york + │ ├── server_count + │ ├── servers + │ │ ├── server_0 + │ │ │ └── stats + │ │ ├── server_1 + │ │ │ └── stats + │ │ └── server_2 + │ │ └── stats + │ └── summary + │ └── summary_stats + ├── prague + │ ├── server_count + │ ├── servers + │ │ ├── server_0 + │ │ │ └── stats + │ │ ├── server_1 + │ │ │ └── stats + │ │ └── server_2 + │ │ └── stats + │ └── summary + │ └── summary_stats + └── tokyo + ├── server_count + ├── servers + │ ├── server_0 + │ │ └── stats + │ ├── server_1 + │ │ └── stats + │ └── server_2 + │ └── stats + └── summary + └── summary_stats +``` + +### Example Telemetry Output +Telemetry metrics are stored in files such as stats, which contain real-time data. +Below is an example of the contents of a stats file for a specific server: + +```bash +$ cat /tmp/telemetry/data_centers/prague/servers/server_0/stats +cpu_usage: 74.28 (%) +disk_usage: 13.48 (%) +latency: 170.20 (ms) +memory_usage: 31.17 (%) +timestamp: 2024-10-03 15:18:41 +``` + +You can also view summary statistics for a data center by reading the summary_stats file: + +```bash +$ cat /tmp/telemetry/data_centers/prague/summary/summary_stats +cpu_usage [avg]: 44.20 (%) +disk_usage [avg]: 35.78 (%) +latency [avg]: 121.82 (ms) +latency [max]: 193.88 (ms) +latency [min]: 7.04 (ms) +memory_usage [avg]: 54.20 (%) +``` + +## Troubleshooting + +### **Problem: FUSE Error – `fusermount3: option allow_other only allowed if 'user_allow_other' is set in /etc/fuse.conf`** + +When running the application, you may encounter the following error: + +``` +fusermount3: option allow_other only allowed if 'user_allow_other' is set in /etc/fuse.conf +fuse_mount() has failed. +``` + +This error occurs because the FUSE configuration does not allow non-root users to use the allow_other option, +which permits other users to access the mounted filesystem. By default, this option is disabled for security reasons. + +### **Solution:** + +To resolve this, follow these steps: + +1. Open the `/etc/fuse.conf` file using a text editor: + ```bash + sudo nano /etc/fuse.conf + ``` + +2. Add the following line if it’s missing: + ```bash + user_allow_other + ``` + +3. Save the file and restart the application: + ```bash + ./example /tmp/telemetry + ``` +This will resolve the issue, allowing non-root users to access the FUSE filesystem.