From 10e045b77644d7c44d1a3a5e8c9096e58feeee5d Mon Sep 17 00:00:00 2001 From: Maxim Lapan Date: Tue, 18 Aug 2026 10:51:23 +0200 Subject: [PATCH] Protocol specification --- doc/index.rst | 1 + doc/protocol.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 doc/protocol.rst diff --git a/doc/index.rst b/doc/index.rst index 7edb639..37ee185 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -30,6 +30,7 @@ Documentation of telemetry user_guide client-python + protocol developer_guide api faq diff --git a/doc/protocol.rst b/doc/protocol.rst new file mode 100644 index 0000000..e3fca8f --- /dev/null +++ b/doc/protocol.rst @@ -0,0 +1,53 @@ +Telemetry Protocol Specification +================================ + +Exasol telemetry uses simplistic protocol sending events happened in the the software. +Every event has a timestamp attached to be used for server-side analytics. +All the data one the server are immediately aggregated and anonymized and no personal information +is transferred or stored. + +The data is transferred in json format and at the moment there are two versions of the protocol. + +Version 0.1 +----------- +.. code:: json + + { + "version": "0.1", + "timestamp": 1787036195, + "features": { + "mcp-server.started": [1787036195] + } + } + +Transferred data has the following fields: + +- ``version``: string specifying the protocol version +- ``timestamp``: UTC timestamp of the transmission attempt +- ``features``: dictionary with pairs ``feature-name`` and vector of timestamps when the event happened. + +Recording of both event timestamp and transmission timestamp allows to check the clock discrepancies on the client +side and filter out outliers. + +Version 0.2 +----------- + +This is an extension of version 0.1, sample data is below. +.. code:: json + + { + "version": "0.2", + "category": "mcp-server", + "productVersion": "0.22", + "timestamp": 1787036195, + "features": { + "started": [1787036195] + } + } + +In this version we have two new top-level fields added: + +- ``category``: name of the product +- ``productVersion``: version of the product + +The name of the product is no longer prepended to the features, which makes the data more compact. \ No newline at end of file