Introduce Telemetry & AppFs example

CMakeLists.txt

@@ -14,6 +14,7 @@ option(TELEMETRY_BUILD_SHARED "Build shared library" ON)
 option(TELEMETRY_PACKAGE_BUILDER "Enable RPM package builder (make rpm)" ON)
 option(TELEMETRY_INSTALL_TARGETS "Generate the install target" ON)
 option(TELEMETRY_ENABLE_TESTS "Build Unit tests (make test)" OFF)
+option(TELEMETRY_BUILD_EXAMPLE "Build included example files (make example)" OFF)
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -33,6 +34,10 @@ endif()
 
 include(cmake/dependencies.cmake)
 
+if (TELEMETRY_BUILD_EXAMPLE)
+	add_subdirectory(example)
+endif()
+
 if (TELEMETRY_ENABLE_TESTS)
 	include(cmake/googletest.cmake)
 	include(GoogleTest)

Makefile

@@ -14,7 +14,7 @@ ifeq ($(RUN_CLANG_TIDY),)
 RUN_CLANG_TIDY := run-clang-tidy
 endif
 
-SOURCE_DIR = src/ include/
+SOURCE_DIR = src/ include/ examples/
 SOURCE_REGEX = '.*\.\(cpp\|hpp\)'
 
 .PHONY: all
@@ -52,3 +52,6 @@ test: build
 	@$(MAKE) --no-print-directory -C build
 	@$(MAKE) test --no-print-directory -C build
 
+example: build
+	@cd build && $(CMAKE) $(CMAKE_ARGS) -DTELEMETRY_BUILD_EXAMPLES=ON ..
+	@$(MAKE) --no-print-directory -C build

example/CMakeLists.txt

@@ -0,0 +1,10 @@
+add_executable(example
+	main.cpp
+	dataCenter.cpp
+	server.cpp
+)
+
+target_link_libraries(example PRIVATE
+	telemetry::telemetry
+	telemetry::appFs
+)

example/README.md

@@ -0,0 +1,68 @@
+# Telemetry Example
+
+## Overview
+
+This example demonstrates a telemetry data structure that organizes and stores metrics from multiple servers located in different data centers. The structure allows for efficient retrieval and monitoring of key telemetry metrics such as CPU usage, memory usage, latency, and disk usage.
+
+## AppFs Directory Structure
+
+The resulting directory structure after running the application 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
+```
+## Components
+
+- **Data Centers**: The project currently supports three data centers: New York, Prague, and Tokyo.
+- **Servers**: Each data center contains multiple servers (three in this example), each with its own set of telemetry metrics.
+- **Telemetry Metrics**: For each server, metrics such as CPU usage, memory usage, latency, and disk usage are generated and stored.
+- **Random Data Generation**: All telemetry metrics are generated randomly to simulate server performance in different conditions.
+- **Summary Stats**: Each data center has a summary directory that aggregates the statistics from its servers.
+
+## Example of Telemetry Output
+
+Here is an example of the contents of the `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
+```

example/dataCenter.cpp

@@ -0,0 +1,96 @@
+/**
+ * @file
+ * @author Pavel Siska <[email protected]>
+ * @brief Implementation of the DataCenter class for managing multiple servers and their telemetry
+ * data.
+ *
+ * This source file implements the methods of the `DataCenter` class, which manages a collection
+ * of `Server` objects and their associated telemetry data. It includes functionalities for adding
+ * servers, setting up telemetry reporting, and aggregating data across all servers for summary
+ * statistics.
+ *
+ * @copyright Copyright (c) 2024 CESNET, z.s.p.o.
+ */
+
+#include "dataCenter.hpp"
+
+namespace telemetry::example {
+
+/**
+ * @brief Creates a summary file with aggregated telemetry data.
+ *
+ * @param filename The name of the summary file to be created.
+ * @param filePattern The pattern to match server telemetry files.
+ * @param patternRootDir Shared pointer to the working directory for patterns.
+ * @param dir Shared pointer to the directory where the summary file will be added.
+ * @return A shared pointer to the created aggregated file.
+ */
+static std::shared_ptr<telemetry::AggregatedFile> createSummaryFile(
+	const std::string& filename,
+	const std::string& filePattern,
+	std::shared_ptr<telemetry::Directory>& patternRootDir,
+	std::shared_ptr<telemetry::Directory>& dir)
+{
+	const std::vector<telemetry::AggOperation> aggOps {
+		{telemetry::AggMethodType::AVG, "cpu_usage", "avg_cpu_usage"},
+		{telemetry::AggMethodType::AVG, "memory_usage", "avg_memory_usage"},
+		{telemetry::AggMethodType::AVG, "latency", "avg_latency"},
+		{telemetry::AggMethodType::AVG, "disk_usage", "avg_disk_usage"},
+	};
+
+	return dir->addAggFile(filename, filePattern, aggOps, patternRootDir);
+}
+
+DataCenter::DataCenter(std::string location, std::shared_ptr<telemetry::Directory>& dataCenterDir)
+	: m_rootDir(dataCenterDir)
+	, m_location(std::move(location))
+{
+	setupTelemetry(dataCenterDir);
+}
+
+void DataCenter::addServer(Server server)
+{
+	auto serverDir = m_rootDir->addDirs("servers/" + server.getId());
+	server.setupTelemetry(serverDir);
+
+	m_servers.emplace_back(std::move(server));
+}
+
+/**
+ * @brief Sets up telemetry reporting for the data center.
+ *
+ * This method initializes the telemetry reporting structure for the data center. It creates
+ * the necessary directories for storing server-specific telemetry data and summary statistics.
+ *
+ * It performs the following actions:
+ * - Creates a directory to hold all server directories (`servers`).
+ * - Creates a directory to store aggregated summary statistics (`summary`).
+ * - Adds a file that tracks the count of servers currently managed by the data center.
+ * - Creates an aggregated summary file that calculates average telemetry metrics (such as
+ *   CPU usage, memory usage, latency, and disk usage) across all servers.
+ *
+ * The generated directories and files are added to the telemetry holder to manage their lifecycle
+ * and ensure they are updated as telemetry data is collected from individual servers.
+ *
+ * @param dataCenterDir Shared pointer to the telemetry directory where the telemetry structure will
+ * be established.
+ */
+void DataCenter::setupTelemetry(std::shared_ptr<telemetry::Directory>& dataCenterDir)
+{
+	auto serversDir = dataCenterDir->addDir("servers");
+	auto summaryDir = dataCenterDir->addDir("summary");
+
+	const auto serverCountFile = dataCenterDir->addFile(
+		"server_count",
+		{[&]() -> telemetry::Scalar { return m_servers.size(); }, nullptr});
+
+	const auto summaryFile
+		= createSummaryFile("summary_stats", "server_\\d+/stats", serversDir, summaryDir);
+
+	m_holder.add(serversDir);
+	m_holder.add(summaryDir);
+	m_holder.add(serverCountFile);
+	m_holder.add(summaryFile);
+}
+
+} // namespace telemetry::example

example/dataCenter.hpp

@@ -0,0 +1,65 @@
+/**
+ * @file
+ * @author Pavel Siska <[email protected]>
+ * @brief Declaration of the DataCenter class for managing multiple servers and their telemetry
+ * data.
+ *
+ * This header file defines the `DataCenter` class, which is responsible for managing a collection
+ * of `Server` objects and their associated telemetry data. The `DataCenter` allows adding servers,
+ * setting up their telemetry reporting, and aggregating data across all servers for summary
+ * statistics.
+ *
+ * The telemetry data is organized in a hierarchical directory structure and can include information
+ * such as CPU usage, memory usage, latency, and disk usage for each server.
+ *
+ * @copyright Copyright (c) 2024 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include "server.hpp"
+
+#include <memory>
+#include <string>
+#include <telemetry.hpp>
+#include <vector>
+
+namespace telemetry::example {
+
+/**
+ * @brief Class representing a data center that manages multiple servers.
+ *
+ * This class provides functionality to add servers, setup telemetry reporting,
+ * and aggregate telemetry data across all managed servers.
+ */
+class DataCenter {
+public:
+	/**
+	 * @brief Constructs a new DataCenter object with a specified location and telemetry directory.
+	 *
+	 * @param location The physical location of the data center.
+	 * @param dataCenterDir Shared pointer to the telemetry directory for this data center.
+	 */
+	DataCenter(std::string location, std::shared_ptr<telemetry::Directory>& dataCenterDir);
+
+	/**
+	 * @brief Adds a server to the data center.
+	 * @param server The server to be added.
+	 */
+	void addServer(Server server);
+
+private:
+	/**
+	 * @brief Sets up telemetry reporting for the data center.
+	 * @param dataCenterDir Shared pointer to the telemetry directory.
+	 */
+	void setupTelemetry(std::shared_ptr<telemetry::Directory>& dataCenterDir);
+
+	std::shared_ptr<telemetry::Directory>
+		m_rootDir; ///< Pointer to the root data center telemetry directory.
+	std::string m_location; ///< The location of the data center.
+	telemetry::Holder m_holder; ///< Holder for managing telemetry files.
+	std::vector<Server> m_servers; ///< Vector to store added servers.
+};
+
+} // namespace telemetry::example