From e70fcc708e727ba6c2b0d4145b136ef3d75a42a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Fern=C3=A1ndez=20Haro?= Date: Fri, 3 Jul 2020 13:25:12 +0100 Subject: [PATCH] [Telemetry] Add documentation about Application Usage (#70624) Co-authored-by: Christiane (Tina) Heiligers Co-authored-by: Elastic Machine --- src/plugins/kibana_usage_collection/README.md | 2 +- .../collectors/application_usage/README.md | 37 +++++++++++++++++++ .../application_usage/saved_objects_types.ts | 13 ++----- 3 files changed, 41 insertions(+), 11 deletions(-) create mode 100644 src/plugins/kibana_usage_collection/server/collectors/application_usage/README.md diff --git a/src/plugins/kibana_usage_collection/README.md b/src/plugins/kibana_usage_collection/README.md index 1aade472c2326..6ef4f19c1570f 100644 --- a/src/plugins/kibana_usage_collection/README.md +++ b/src/plugins/kibana_usage_collection/README.md @@ -2,7 +2,7 @@ This plugin registers the basic usage collectors from Kibana: -- Application Usage +- [Application Usage](./server/collectors/application_usage/README.md) - UI Metrics - Ops stats - Number of Saved Objects per type diff --git a/src/plugins/kibana_usage_collection/server/collectors/application_usage/README.md b/src/plugins/kibana_usage_collection/server/collectors/application_usage/README.md new file mode 100644 index 0000000000000..1ffd01fc6fde7 --- /dev/null +++ b/src/plugins/kibana_usage_collection/server/collectors/application_usage/README.md @@ -0,0 +1,37 @@ +# Application Usage + +This collector reports the number of general clicks and minutes on screen for each registered application in Kibana. + +The final payload matches the following contract: + +```JSON +{ + "application_usage": { + "application_ID": { + "clicks_7_days": 10, + "clicks_30_days": 100, + "clicks_90_days": 300, + "clicks_total": 600, + "minutes_on_screen_7_days": 10.40, + "minutes_on_screen_30_days": 20.0, + "minutes_on_screen_90_days": 110.1, + "minutes_on_screen_total": 112.5 + } + } +} +``` + +Where `application_ID` matches the `id` registered when calling the method `core.application.register`. +This collection occurs by default for every application registered via the mentioned method and there is no need to do anything else to enable it or _opt-in_ for your plugin. + +**Note to maintainers in the Kibana repo:** At the moment of writing, the `usageCollector.schema` is not updated automatically ([#70622](https://github.com/elastic/kibana/issues/70622)) so, if you are adding a new app to Kibana, you'll need to give the Kibana Telemetry team a heads up to update the mappings in the Telemetry Cluster accordingly. + +## Developer notes + +In order to keep the count of the events, this collector uses 2 Saved Objects: + +1. `application_usage_transactional`: It stores each individually reported event (up to 90 days old). Grouped by `timestamp` and `appId`. +2. `application_usage_totals`: It stores the sum of all the events older than 90 days old per `appId`. + +Both of them use the shared fields `appId: 'keyword'`, `numberOfClicks: 'long'` and `minutesOnScreen: 'float'`. `application_usage_transactional` also stores `timestamp: { type: 'date' }`. +but they are currently not added in the mappings because we don't use them for search purposes, and we need to be thoughtful with the number of mapped fields in the SavedObjects index ([#43673](https://github.com/elastic/kibana/issues/43673)). diff --git a/src/plugins/kibana_usage_collection/server/collectors/application_usage/saved_objects_types.ts b/src/plugins/kibana_usage_collection/server/collectors/application_usage/saved_objects_types.ts index 8d6a2d110efe0..551c6e230972e 100644 --- a/src/plugins/kibana_usage_collection/server/collectors/application_usage/saved_objects_types.ts +++ b/src/plugins/kibana_usage_collection/server/collectors/application_usage/saved_objects_types.ts @@ -35,13 +35,10 @@ export function registerMappings(registerType: SavedObjectsServiceSetup['registe hidden: false, namespaceType: 'agnostic', mappings: { + // Not indexing any of its contents because we use them "as-is" and don't search by these fields + // for more info, see the README.md for application_usage dynamic: false, - properties: { - // Disabled the mapping of these fields since they are not searched and we need to reduce the amount of indexed fields (#43673) - // appId: { type: 'keyword' }, - // numberOfClicks: { type: 'long' }, - // minutesOnScreen: { type: 'float' }, - }, + properties: {}, }, }); @@ -53,10 +50,6 @@ export function registerMappings(registerType: SavedObjectsServiceSetup['registe dynamic: false, properties: { timestamp: { type: 'date' }, - // Disabled the mapping of these fields since they are not searched and we need to reduce the amount of indexed fields (#43673) - // appId: { type: 'keyword' }, - // numberOfClicks: { type: 'long' }, - // minutesOnScreen: { type: 'float' }, }, }, });