From ebcac9ff0ed933b593ce2ba85a19ac8b7ca354b6 Mon Sep 17 00:00:00 2001
From: Pavel Siska <siska@cesnet.cz>
Date: Wed, 24 Apr 2024 17:49:44 +0200
Subject: [PATCH] add README

---
 README.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 121 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 704cc81..8df8bd5 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,121 @@
-# 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 an example file in the `example` directory. You can use this to get started with the library and adapt the example code to fit your needs.
+
+Running the Example
+To run the example, first build it:
+
+```bash
+$ make example
+```
+Then, execute the example with the desired mount point:
+
+```bash
+$ ./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.
+
+
+### Directory Structure Example
+Once the example is running, it will create a directory structure similar to the following:
+
+```bash
+/tmp/telemetry
+└── data_centers
+    ├── new_york
+    │   └── servers
+    │       ├── server_0
+    │       │   └── stats
+    │       ├── server_1
+    │       │   └── stats
+    │       └── server_2
+    │           └── stats
+    ├── prague
+    │   └── servers
+    │       ├── server_0
+    │       │   └── stats
+    │       ├── server_1
+    │       │   └── stats
+    │       └── server_2
+    │           └── stats
+    └── tokyo
+        └── servers
+            ├── server_0
+            │   └── stats
+            ├── server_1
+            │   └── stats
+            └── server_2
+                └── 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 (%)
+```