[llvm] [llvm]Add a simple Telemetry framework (PR #102323)
James Henderson via llvm-commits
llvm-commits at lists.llvm.org
Tue Dec 17 01:40:41 PST 2024
================
@@ -0,0 +1,246 @@
+===========================
+Telemetry framework in LLVM
+===========================
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+===========================
+Telemetry framework in LLVM
+===========================
+
+Objective
+=========
+
+Provides a common framework in LLVM for collecting various usage and performance
+metrics.
+It is located at ``llvm/Telemetry/Telemetry.h``
+
+Characteristics
+---------------
+* Configurable and extensible by:
+
+ * Tools: any tool that wants to use Telemetry can extend and customize it.
+ * Vendors: Toolchain vendors can also provide custom implementation of the
+ library, which could either override or extend the given tool's upstream
+ implementation, to best fit their organization's usage and privacy models.
+ * End users of such tool can also configure Telemetry (as allowed by their
+ vendor).
+
+Important notes
+----------------
+
+* There is no concrete implementation of a Telemetry library in upstream LLVM.
+ We only provide the abstract API here. Any tool that wants telemetry will
+ implement one.
+
+ The rationale for this is that all the tools in LLVM are very different in
+ what they care about (what/where/when to instrument data). Hence, it might not
+ be practical to have a single implementation.
+ However, in the future, if we see enough common pattern, we can extract them
+ into a shared place. This is TBD - contributions are welcomed.
+
+* No implementation of Telemetry in upstream LLVM shall store any of the
+ collected data due to privacy and security reasons:
+
+ * Different organizations have different privacy models:
+
+ * Which data is sensitive, which is not?
+ * Whether it is acceptable for instrumented data to be stored anywhere?
+ (to a local file, what not?)
+
+ * Data ownership and data collection consents are hard to accommodate from
+ LLVM developers' point of view:
+
+ * E.g., data collected by Telemetry is not necessarily owned by the user
+ of an LLVM tool with Telemetry enabled, hence the user's consent to data
+ collection is not meaningful. On the other hand, LLVM developers have no
+ reasonable ways to request consent from the "real" owners.
+
+
+High-level design
+=================
+
+Key components
+--------------
+
+The framework consists of four important classes:
+
+* ``llvm::telemetry::Manager``: The class responsible for collecting and
+ transmitting telemetry data. This is the main point of interaction between the
+ framework and any tool that wants to enable telemetry.
+* ``llvm::telemetry::TelemetryInfo``: Data courier
+* ``llvm::telemetry::Destination``: Data sink to which the Telemetry framework
+ sends data.
+ Its implementation is transparent to the framework.
+ It is up to the vendor to decide which pieces of data to forward and where
+ to forward them to for their final storage.
+* ``llvm::telemetry::Config``: Configurations for the ``Manager``.
+
+.. image:: llvm_telemetry_design.png
+
+How to implement and interact with the API
+------------------------------------------
+
+To use Telemetry in your tool, you need to provide a concrete implementation of the ``Manager`` class and ``Destination``.
+
+1) Define a custom ``Serializer``, ``Manager``, ``Destination`` and optionally a subclass of ``TelemetryInfo``
+
+.. code-block:: c++
+
+ class JsonSerializer : public Serializer {
+ public:
+ json::Object *getOutputObject() { return object.get(); }
+
+ llvm::Error init() override {
+ if (started)
+ return createStringError("Serializer already in use");
+ started = true;
+ object = std::make_unique<json::Object>();
+ return Error::success();
+ }
+
+ // Serialize the given value.
+ void write(StringRef KeyName, bool Value) override {
+ writeHelper(KeyName, Value);
+ }
+
+ void write(StringRef KeyName, int Value) override {
+ writeHelper(KeyName, Value);
+ }
+
+ void write(StringRef KeyName, size_t Value) override {
+ writeHelper(KeyName, Value);
+ }
+ void write(StringRef KeyName, StringRef Value) override {
+ writeHelper(KeyName, Value);
+ }
+
+ void write(StringRef KeyName,
+ const std::map<std::string, std::string>& Value) override {
+ json::Object Inner;
+ for (auto kv : Value) {
+ Inner.try_emplace(kv.first, kv.second);
+ }
+ writeHelper(KeyName, json::Value(std::move(Inner)));
+ }
+
+ Error finalize() override {
+ if (!started)
+ return createStringError("Serializer not currently in use");
+ started = false;
+ return Error::success();
+ }
+
+ private:
+ template <typename T> void writeHelper(StringRef Name, T Value) {
+ assert(started && "serializer not started");
+ object->try_emplace(Name, Value);
+ }
+ bool started = false;
+ std::unique_ptr<json::Object> object;
+ };
+
+ class MyManager : public telemery::Manager {
+ public:
+ static std::unique_ptr<MyManager> createInstatnce(telemetry::Config* config) {
+ // If Telemetry is not enabled, then just return null;
+ if (!config->EnableTelemetry) return nullptr;
----------------
jh7370 wrote:
Ping this comment.
https://github.com/llvm/llvm-project/pull/102323
More information about the llvm-commits
mailing list