[docs] Add page about telemetry

werf · Jul 22, 2022 · 1f6e10a · 1f6e10a
1 parent c76d6e4
commit 1f6e10a
Show file tree

Hide file tree

Showing 3 changed files with 154 additions and 0 deletions.
diff --git a/docs/_data/sidebars/_documentation.yml b/docs/_data/sidebars/_documentation.yml
@@ -219,6 +219,9 @@ entries:
               - title: Stapel image
                 url: /internals/development/stapel_image.html
 
+          - title: Telemetry
+            url: /internals/telemetry.html
+
       - title: What's new in v1.2
         f:
 
@@ -440,6 +443,9 @@ entries:
               - title: Образ Stapel
                 url: /internals/development/stapel_image.html
 
+          - title: Телеметрия
+            url: /internals/telemetry.html
+
       - title: Что нового в v1.2
         f:
 

diff --git a/docs/pages_en/internals/telemetry.md b/docs/pages_en/internals/telemetry.md
@@ -0,0 +1,74 @@
+---
+title: Telemetry
+permalink: internals/telemetry.html
+---
+
+Чтобы работать над улучшением функций werf и направлять разработку в правильное русло, мы собираем анонимные данные об использовании. Эти данные никак не привязываются к пользователям и не содержат никакой персонализированной информации.
+
+Они помогают понять, как используется werf, и бросить силы на улучшение нужных функций.
+
+На текущий момент телеметрия по умолчанию выключена. Управление осуществляется с помощью переменной окружения `WERF_TELEMETRY`.
+
+Для того, чтобы включить телеметрию и помочь нам улучшить werf, просто задайте ей значение `1`:
+
+```shell
+export WERF_TELEMETRY=1
+```
+
+Для выключения установите ее значение в `0`:
+
+```shell
+export WERF_TELEMETRY=0
+```
+
+> В ближайшее время планируется включить телеметрию по умолчанию, а выключение сделать опциональным по желанию пользователя.
+
+## Пример передаваемых данных и их расшифровка
+
+Ниже приведены примеры передаваемых данных:
+
+```
+ts=1658231825280
+executionID="2f75d020-684e-4224-9013-35e95e1b7721"
+projectID="b4c2d019070529344a6967d8c73d578101c6554fcdcae3d00bb93a9692523cb1"
+command="werf converge"
+attributes={"arch":"amd64","os":"linux","version":"dev"}"
+eventType="CommandStarted"
+eventData={"commandOptions":[{"name":"repo","asCli":false,"asEnv":false,"count":0}]}
+schemaVersion=1
+```
+```
+ts=1658231836102
+executionID="2f75d020-684e-4224-9013-35e95e1b7721"
+projectID="b4c2d019070529344a6967d8c73d578101c6554fcdcae3d00bb93a9692523cb1"
+command="werf converge"
+attributes={"arch":"amd64","os":"linux","version":"dev"}
+eventType="CommandExited"
+eventData="{"exitCode":0,"durationMs":10827}"
+schemaVersion=1
+```
+
+Здесь передаются следующие данные об использовании:
+
+* `ts` — timestamp;
+* `executionID` — UUID;
+* `projectID` — контрольная сумма (SHA-256) от git origin URL проекта;
+* `command` — название выполняемой команды werf;
+* `attributes` — атрибуты окружения:
+  * `os`;
+  * `arch`;
+  * `trdl group-channel`;
+  * `werf version`.
+* `eventType` — тип события:
+  * `CommandStarted`;
+  * `CommandExited`;
+* `eventData` — данные события, включают в себя:
+  * exit code;
+  * длительность работы команды;
+  * имена используемых опций.
+
+Вы можете сами убедиться в том, что мы собираем только обезличенную информацию, как указано в примере выше. Для этого см. исходные код werf, отвечающий за телеметрию: файлы [event.go](https://github.com/werf/werf/blob/main/pkg/telemetry/event.go) и [telemetrywerfio.go](https://github.com/werf/werf/blob/main/pkg/telemetry/telemetrywerfio.go) пакета [telemetry](https://github.com/werf/werf/tree/main/pkg/telemetry).
+
+## Выгрузка отчета телеметрии
+
+Мы доверяем нашим пользователям и хотим, чтобы они так же доверяли нам, поэтому сделали все максимально прозрачно. Используя переменную окружения `WERF_TELEMETRY_LOG_FILE`, можно задать путь к лог-файлу, куда будут складываться все данные, передаваемые телеметрией.
diff --git a/docs/pages_ru/internals/telemetry.md b/docs/pages_ru/internals/telemetry.md
@@ -0,0 +1,74 @@
+---
+title: Телеметрия
+permalink: internals/telemetry.html
+---
+
+Чтобы работать над улучшением функций werf и направлять разработку в правильное русло, мы собираем анонимные данные об использовании. Эти данные никак не привязываются к пользователям и не содержат никакой персонализированной информации.
+
+Они помогают понять, как используется werf, и бросить силы на улучшение нужных функций.
+
+На текущий момент телеметрия по умолчанию выключена. Управление осуществляется с помощью переменной окружения `WERF_TELEMETRY`.
+
+Для того, чтобы включить телеметрию и помочь нам улучшить werf, просто задайте ей значение `1`:
+
+```shell
+export WERF_TELEMETRY=1
+```
+
+Для выключения установите ее значение в `0`:
+
+```shell
+export WERF_TELEMETRY=0
+```
+
+> В ближайшее время планируется включить телеметрию по умолчанию, а выключение сделать опциональным по желанию пользователя.
+
+## Пример передаваемых данных и их расшифровка
+
+Ниже приведены примеры передаваемых данных:
+
+```
+ts=1658231825280
+executionID="2f75d020-684e-4224-9013-35e95e1b7721"
+projectID="b4c2d019070529344a6967d8c73d578101c6554fcdcae3d00bb93a9692523cb1"
+command="werf converge"
+attributes={"arch":"amd64","os":"linux","version":"dev"}"
+eventType="CommandStarted"
+eventData={"commandOptions":[{"name":"repo","asCli":false,"asEnv":false,"count":0}]}
+schemaVersion=1
+```
+```
+ts=1658231836102
+executionID="2f75d020-684e-4224-9013-35e95e1b7721"
+projectID="b4c2d019070529344a6967d8c73d578101c6554fcdcae3d00bb93a9692523cb1"
+command="werf converge"
+attributes={"arch":"amd64","os":"linux","version":"dev"}
+eventType="CommandExited"
+eventData="{"exitCode":0,"durationMs":10827}"
+schemaVersion=1
+```
+
+Здесь передаются следующие данные об использовании:
+
+* `ts` — timestamp;
+* `executionID` — UUID;
+* `projectID` — контрольная сумма (SHA-256) от git origin URL проекта;
+* `command` — название выполняемой команды werf;
+* `attributes` — атрибуты окружения:
+  * `os`;
+  * `arch`;
+  * `trdl group-channel`;
+  * `werf version`.
+* `eventType` — тип события:
+  * `CommandStarted`;
+  * `CommandExited`;
+* `eventData` — данные события, включают в себя:
+  * exit code;
+  * длительность работы команды;
+  * имена используемых опций.
+
+Вы можете сами убедиться в том, что мы собираем только обезличенную информацию, как указано в примере выше. Для этого см. исходные код werf, отвечающий за телеметрию: файлы [event.go](https://github.com/werf/werf/blob/main/pkg/telemetry/event.go) и [telemetrywerfio.go](https://github.com/werf/werf/blob/main/pkg/telemetry/telemetrywerfio.go) пакета [telemetry](https://github.com/werf/werf/tree/main/pkg/telemetry).
+
+## Выгрузка отчета телеметрии
+
+Мы доверяем нашим пользователям и хотим, чтобы они так же доверяли нам, поэтому сделали все максимально прозрачно. Используя переменную окружения `WERF_TELEMETRY_LOG_FILE`, можно задать путь к лог-файлу, куда будут складываться все данные, передаваемые телеметрией.