diff --git a/api_docs/telemetry.json b/api_docs/telemetry.json index bfb19a79bdb1e..61b984aad4882 100644 --- a/api_docs/telemetry.json +++ b/api_docs/telemetry.json @@ -1,1127 +1,415 @@ { "id": "telemetry", "client": { - "classes": [ + "classes": [], + "functions": [], + "interfaces": [ { - "id": "def-public.TelemetryNotifications", - "type": "Class", + "id": "def-public.TelemetryPluginConfig", + "type": "Interface", + "label": "TelemetryPluginConfig", + "description": [ + "\nPublic-exposed configuration" + ], "tags": [], - "label": "TelemetryNotifications", - "description": [], "children": [ { - "id": "def-public.TelemetryNotifications.Unnamed", - "type": "Function", - "label": "Constructor", - "signature": [ - "any" - ], - "description": [], - "children": [ - { - "id": "def-public.TelemetryNotifications.Unnamed.$1", - "type": "Object", - "label": "{ http, overlays, telemetryService }", - "isRequired": true, - "signature": [ - "TelemetryNotificationsConstructor" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 27 - } - } - ], "tags": [], - "returnComment": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 27 - } - }, - { - "id": "def-public.TelemetryNotifications.shouldShowOptedInNoticeBanner", - "type": "Function", - "children": [], - "signature": [ - "() => boolean" + "id": "def-public.TelemetryPluginConfig.enabled", + "type": "boolean", + "label": "enabled", + "description": [ + "Is the plugin enabled?" ], - "description": [], - "label": "shouldShowOptedInNoticeBanner", "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 33 - }, - "tags": [], - "returnComment": [] + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 84 + } }, { - "id": "def-public.TelemetryNotifications.renderOptedInNoticeBanner", - "type": "Function", - "children": [], - "signature": [ - "() => void" - ], - "description": [], - "label": "renderOptedInNoticeBanner", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 39 - }, "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryNotifications.shouldShowOptInBanner", - "type": "Function", - "children": [], - "signature": [ - "() => boolean" + "id": "def-public.TelemetryPluginConfig.url", + "type": "string", + "label": "url", + "description": [ + "Remote telemetry service's URL" ], - "description": [], - "label": "shouldShowOptInBanner", "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 49 - }, - "tags": [], - "returnComment": [] + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 86 + } }, { - "id": "def-public.TelemetryNotifications.renderOptInBanner", - "type": "Function", - "children": [], - "signature": [ - "() => void" - ], - "description": [], - "label": "renderOptInBanner", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 55 - }, "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryNotifications.setOptedInNoticeSeen", - "type": "Function", - "children": [], - "signature": [ - "() => Promise" + "id": "def-public.TelemetryPluginConfig.banner", + "type": "boolean", + "label": "banner", + "description": [ + "The banner is expected to be shown when needed" ], - "description": [], - "label": "setOptedInNoticeSeen", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 73 - }, - "tags": [], - "returnComment": [] - } - ], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts", - "lineNumber": 20 - }, - "initialIsOpen": false - }, - { - "id": "def-public.TelemetryService", - "type": "Class", - "tags": [], - "label": "TelemetryService", - "description": [], - "children": [ - { - "tags": [], - "id": "def-public.TelemetryService.currentKibanaVersion", - "type": "string", - "label": "currentKibanaVersion", - "description": [], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 28 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 88 } }, { - "id": "def-public.TelemetryService.Unnamed", - "type": "Function", - "label": "Constructor", - "signature": [ - "any" - ], - "description": [], - "children": [ - { - "id": "def-public.TelemetryService.Unnamed.$1", - "type": "Object", - "label": "{\n config,\n http,\n notifications,\n currentKibanaVersion,\n reportOptInStatusChange = true,\n }", - "isRequired": true, - "signature": [ - "TelemetryServiceConstructor" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 30 - } - } - ], "tags": [], - "returnComment": [], + "id": "def-public.TelemetryPluginConfig.allowChangingOptInStatus", + "type": "boolean", + "label": "allowChangingOptInStatus", + "description": [ + "Does the cluster allow changing the opt-in/out status via the UI?" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 30 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 90 } }, { - "id": "def-public.TelemetryService.config", - "type": "Object", - "label": "config", "tags": [], - "description": [], + "id": "def-public.TelemetryPluginConfig.optIn", + "type": "CompoundType", + "label": "optIn", + "description": [ + "Is the cluster opted-in?" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 44 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 92 }, "signature": [ - { - "pluginId": "telemetry", - "scope": "public", - "docId": "kibTelemetryPluginApi", - "section": "def-public.TelemetryPluginConfig", - "text": "TelemetryPluginConfig" - } + "boolean | null" ] }, { - "id": "def-public.TelemetryService.config", - "type": "Object", - "label": "config", "tags": [], - "description": [], + "id": "def-public.TelemetryPluginConfig.optInStatusUrl", + "type": "string", + "label": "optInStatusUrl", + "description": [ + "Opt-in/out notification URL" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 48 - }, - "signature": [ - { - "pluginId": "telemetry", - "scope": "public", - "docId": "kibTelemetryPluginApi", - "section": "def-public.TelemetryPluginConfig", - "text": "TelemetryPluginConfig" - } - ] + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 94 + } }, { - "id": "def-public.TelemetryService.isOptedIn", - "type": "CompoundType", - "label": "isOptedIn", "tags": [], - "description": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 52 - }, - "signature": [ - "boolean | null" - ] - }, - { - "id": "def-public.TelemetryService.isOptedIn", + "id": "def-public.TelemetryPluginConfig.sendUsageFrom", "type": "CompoundType", - "label": "isOptedIn", - "tags": [], - "description": [], + "label": "sendUsageFrom", + "description": [ + "Should the telemetry payloads be sent from the server or the browser?" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 56 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 96 }, "signature": [ - "boolean | null" + "\"browser\" | \"server\"" ] }, { - "id": "def-public.TelemetryService.userHasSeenOptedInNotice", - "type": "CompoundType", - "label": "userHasSeenOptedInNotice", "tags": [], - "description": [], + "id": "def-public.TelemetryPluginConfig.telemetryNotifyUserAboutOptInDefault", + "type": "CompoundType", + "label": "telemetryNotifyUserAboutOptInDefault", + "description": [ + "Should notify the user about the opt-in status?" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 60 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 98 }, "signature": [ "boolean | undefined" ] }, { - "id": "def-public.TelemetryService.userHasSeenOptedInNotice", - "type": "CompoundType", - "label": "userHasSeenOptedInNotice", "tags": [], - "description": [], + "id": "def-public.TelemetryPluginConfig.userCanChangeSettings", + "type": "CompoundType", + "label": "userCanChangeSettings", + "description": [ + "Does the user have enough privileges to change the settings?" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 64 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 100 }, "signature": [ "boolean | undefined" ] - }, - { - "id": "def-public.TelemetryService.getCanChangeOptInStatus", - "type": "Function", - "children": [], - "signature": [ - "() => boolean" - ], - "description": [], - "label": "getCanChangeOptInStatus", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 68 - }, - "tags": [], - "returnComment": [] - }, + } + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 82 + }, + "initialIsOpen": false + }, + { + "id": "def-public.TelemetryServicePublicApis", + "type": "Interface", + "label": "TelemetryServicePublicApis", + "description": [ + "\nPublicly exposed APIs from the Telemetry Service" + ], + "tags": [], + "children": [ { - "id": "def-public.TelemetryService.getOptInStatusUrl", - "type": "Function", - "children": [], - "signature": [ - "() => string" - ], - "description": [], - "label": "getOptInStatusUrl", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 73 - }, "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryService.getTelemetryUrl", + "id": "def-public.TelemetryServicePublicApis.getIsOptedIn", "type": "Function", - "children": [], - "signature": [ - "() => string" + "label": "getIsOptedIn", + "description": [ + "Is the cluster opted-in to telemetry?" ], - "description": [], - "label": "getTelemetryUrl", "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 78 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 38 }, - "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryService.getUserShouldSeeOptInNotice", - "type": "Function", - "label": "getUserShouldSeeOptInNotice", "signature": [ - "() => boolean" - ], - "description": [ - "\nReturns if an user should be shown the notice about Opt-In/Out telemetry.\nThe decision is made based on whether any user has already dismissed the message or\nthe user can't actually change the settings (in which case, there's no point on bothering them)" - ], - "children": [], - "tags": [], - "returnComment": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 88 - } + "() => boolean | null" + ] }, { - "id": "def-public.TelemetryService.userCanChangeSettings", - "type": "boolean", - "label": "userCanChangeSettings", "tags": [], - "description": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 95 - } - }, - { - "id": "def-public.TelemetryService.userCanChangeSettings", + "id": "def-public.TelemetryServicePublicApis.userCanChangeSettings", "type": "boolean", "label": "userCanChangeSettings", - "tags": [], - "description": [], + "description": [ + "Is the user allowed to change the opt-in/out status?" + ], "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 99 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 40 } }, { - "id": "def-public.TelemetryService.getIsOptedIn", - "type": "Function", - "children": [], - "signature": [ - "() => boolean | null" - ], - "description": [], - "label": "getIsOptedIn", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 103 - }, "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryService.fetchExample", + "id": "def-public.TelemetryServicePublicApis.getCanChangeOptInStatus", "type": "Function", - "children": [], - "signature": [ - "() => Promise" + "label": "getCanChangeOptInStatus", + "description": [ + "Is the cluster allowed to change the opt-in/out status?" ], - "description": [], - "label": "fetchExample", "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 107 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 42 }, - "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryService.fetchTelemetry", - "type": "Function", - "children": [ - { - "id": "def-public.TelemetryService.fetchTelemetry.$1", - "type": "Object", - "label": "{ unencrypted = false }", - "isRequired": true, - "signature": [ - "{ unencrypted?: boolean | undefined; }" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 111 - } - } - ], "signature": [ - "({ unencrypted }?: { unencrypted?: boolean | undefined; }) => Promise" - ], - "description": [], - "label": "fetchTelemetry", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 111 - }, - "tags": [], - "returnComment": [] + "() => boolean" + ] }, { - "id": "def-public.TelemetryService.setOptIn", - "type": "Function", - "children": [ - { - "id": "def-public.TelemetryService.setOptIn.$1", - "type": "boolean", - "label": "optedIn", - "isRequired": true, - "signature": [ - "boolean" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 119 - } - } - ], - "signature": [ - "(optedIn: boolean) => Promise" - ], - "description": [], - "label": "setOptIn", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 119 - }, "tags": [], - "returnComment": [] - }, - { - "id": "def-public.TelemetryService.setUserHasSeenNotice", + "id": "def-public.TelemetryServicePublicApis.fetchExample", "type": "Function", - "children": [], - "signature": [ - "() => Promise" + "label": "fetchExample", + "description": [ + "Fetches an unencrypted telemetry payload so we can show it to the user" ], - "description": [], - "label": "setUserHasSeenNotice", - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 153 - }, - "tags": [], - "returnComment": [] - } - ], - "source": { - "path": "src/plugins/telemetry/public/services/telemetry_service.ts", - "lineNumber": 21 - }, - "initialIsOpen": false - } - ], - "functions": [], - "interfaces": [ - { - "id": "def-public.TelemetryPluginConfig", - "type": "Interface", - "label": "TelemetryPluginConfig", - "description": [], - "tags": [], - "children": [ - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.enabled", - "type": "boolean", - "label": "enabled", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 46 - } - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.url", - "type": "string", - "label": "url", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 47 - } - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.banner", - "type": "boolean", - "label": "banner", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 48 - } - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.allowChangingOptInStatus", - "type": "boolean", - "label": "allowChangingOptInStatus", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 49 - } - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.optIn", - "type": "CompoundType", - "label": "optIn", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 50 - }, - "signature": [ - "boolean | null" - ] - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.optInStatusUrl", - "type": "string", - "label": "optInStatusUrl", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 51 - } - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.sendUsageFrom", - "type": "CompoundType", - "label": "sendUsageFrom", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 52 - }, - "signature": [ - "\"browser\" | \"server\"" - ] - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.telemetryNotifyUserAboutOptInDefault", - "type": "CompoundType", - "label": "telemetryNotifyUserAboutOptInDefault", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 53 - }, - "signature": [ - "boolean | undefined" - ] - }, - { - "tags": [], - "id": "def-public.TelemetryPluginConfig.userCanChangeSettings", - "type": "CompoundType", - "label": "userCanChangeSettings", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 54 - }, - "signature": [ - "boolean | undefined" - ] - } - ], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 45 - }, - "initialIsOpen": false - } - ], - "enums": [], - "misc": [], - "objects": [], - "start": { - "id": "def-public.TelemetryPluginStart", - "type": "Interface", - "label": "TelemetryPluginStart", - "description": [], - "tags": [], - "children": [ - { - "tags": [], - "id": "def-public.TelemetryPluginStart.telemetryService", - "type": "Object", - "label": "telemetryService", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 38 - }, - "signature": [ - { - "pluginId": "telemetry", - "scope": "public", - "docId": "kibTelemetryPluginApi", - "section": "def-public.TelemetryService", - "text": "TelemetryService" - } - ] - }, - { - "tags": [], - "id": "def-public.TelemetryPluginStart.telemetryNotifications", - "type": "Object", - "label": "telemetryNotifications", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 39 - }, - "signature": [ - { - "pluginId": "telemetry", - "scope": "public", - "docId": "kibTelemetryPluginApi", - "section": "def-public.TelemetryNotifications", - "text": "TelemetryNotifications" - } - ] - }, - { - "tags": [], - "id": "def-public.TelemetryPluginStart.telemetryConstants", - "type": "Object", - "label": "telemetryConstants", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 40 - }, - "signature": [ - "{ getPrivacyStatementUrl: () => string; }" - ] - } - ], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 37 - }, - "lifecycle": "start", - "initialIsOpen": true - }, - "setup": { - "id": "def-public.TelemetryPluginSetup", - "type": "Interface", - "label": "TelemetryPluginSetup", - "description": [], - "tags": [], - "children": [ - { - "tags": [], - "id": "def-public.TelemetryPluginSetup.telemetryService", - "type": "Object", - "label": "telemetryService", - "description": [], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 34 - }, - "signature": [ - { - "pluginId": "telemetry", - "scope": "public", - "docId": "kibTelemetryPluginApi", - "section": "def-public.TelemetryService", - "text": "TelemetryService" - } - ] - } - ], - "source": { - "path": "src/plugins/telemetry/public/plugin.ts", - "lineNumber": 33 - }, - "lifecycle": "setup", - "initialIsOpen": true - } - }, - "server": { - "classes": [], - "functions": [ - { - "id": "def-server.buildDataTelemetryPayload", - "type": "Function", - "label": "buildDataTelemetryPayload", - "signature": [ - "(indices: ", - { - "pluginId": "telemetry", - "scope": "server", - "docId": "kibTelemetryPluginApi", - "section": "def-server.DataTelemetryIndex", - "text": "DataTelemetryIndex" - }, - "[]) => ", - { - "pluginId": "telemetry", - "scope": "server", - "docId": "kibTelemetryPluginApi", - "section": "def-server.DataTelemetryPayload", - "text": "DataTelemetryPayload" - } - ], - "description": [], - "children": [ - { - "id": "def-server.buildDataTelemetryPayload.$1", - "type": "Array", - "label": "indices", - "isRequired": true, - "signature": [ - { - "pluginId": "telemetry", - "scope": "server", - "docId": "kibTelemetryPluginApi", - "section": "def-server.DataTelemetryIndex", - "text": "DataTelemetryIndex" - }, - "[]" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 122 - } - } - ], - "tags": [], - "returnComment": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 122 - }, - "initialIsOpen": false - }, - { - "id": "def-server.getClusterUuids", - "type": "Function", - "children": [ - { - "id": "def-server.getClusterUuids.$1", - "type": "Object", - "label": "{ esClient }", - "isRequired": true, - "signature": [ - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.StatsCollectionConfig", - "text": "StatsCollectionConfig" - } - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_cluster_stats.ts", - "lineNumber": 25 - } - } - ], - "signature": [ - "({ esClient }: ", - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.StatsCollectionConfig", - "text": "StatsCollectionConfig" - }, - ") => Promise<{ clusterUuid: string; }[]>" - ], - "description": [ - "\nGet the cluster uuids from the connected cluster." - ], - "label": "getClusterUuids", - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_cluster_stats.ts", - "lineNumber": 25 - }, - "tags": [], - "returnComment": [], - "initialIsOpen": false - }, - { - "id": "def-server.getLocalStats", - "type": "Function", - "children": [ - { - "id": "def-server.getLocalStats.$1", - "type": "Array", - "label": "clustersDetails", - "isRequired": true, - "signature": [ - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.ClusterDetails", - "text": "ClusterDetails" - }, - "[]" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts", - "lineNumber": 60 - } - }, - { - "id": "def-server.getLocalStats.$2", - "type": "Object", - "label": "config", - "isRequired": true, - "signature": [ - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.StatsCollectionConfig", - "text": "StatsCollectionConfig" - } - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts", - "lineNumber": 61 - } - }, - { - "id": "def-server.getLocalStats.$3", - "type": "Object", - "label": "context", - "isRequired": true, - "signature": [ - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.StatsCollectionContext", - "text": "StatsCollectionContext" - } - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts", - "lineNumber": 62 - } - } - ], - "signature": [ - "(clustersDetails: ", - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.ClusterDetails", - "text": "ClusterDetails" - }, - "[], config: ", - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.StatsCollectionConfig", - "text": "StatsCollectionConfig" - }, - ", context: ", - { - "pluginId": "telemetryCollectionManager", - "scope": "server", - "docId": "kibTelemetryCollectionManagerPluginApi", - "section": "def-server.StatsCollectionContext", - "text": "StatsCollectionContext" - }, - ") => Promise<{ timestamp: string; cluster_uuid: string; cluster_name: string; version: string; cluster_stats: Pick<{ nodes: { usage: { nodes: ", - { - "pluginId": "telemetry", - "scope": "server", - "docId": "kibTelemetryPluginApi", - "section": "def-server.NodeUsage", - "text": "NodeUsage" - }, - "[] | {}[]; }; count: ", - "ClusterNodeCount" - ], - "description": [ - "\nGet statistics for all products joined by Elasticsearch cluster." - ], - "label": "getLocalStats", - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts", - "lineNumber": 59 - }, - "tags": [], - "returnComment": [], - "initialIsOpen": false - }, - { - "id": "def-server.handleOldSettings", - "type": "Function", - "label": "handleOldSettings", - "signature": [ - "(savedObjectsClient: Pick<", - { - "pluginId": "core", - "scope": "server", - "docId": "kibCoreSavedObjectsPluginApi", - "section": "def-server.SavedObjectsClient", - "text": "SavedObjectsClient" - }, - ", \"get\" | \"delete\" | \"create\" | \"bulkCreate\" | \"checkConflicts\" | \"find\" | \"bulkGet\" | \"resolve\" | \"update\" | \"addToNamespaces\" | \"deleteFromNamespaces\" | \"bulkUpdate\" | \"removeReferencesTo\" | \"openPointInTimeForType\" | \"closePointInTime\" | \"createPointInTimeFinder\" | \"errors\">, uiSettingsClient: ", - { - "pluginId": "core", - "scope": "server", - "docId": "kibCorePluginApi", - "section": "def-server.IUiSettingsClient", - "text": "IUiSettingsClient" - }, - ") => Promise" - ], - "description": [], - "children": [ - { - "id": "def-server.handleOldSettings.$1", - "type": "Object", - "label": "savedObjectsClient", - "isRequired": true, - "signature": [ - "Pick<", - { - "pluginId": "core", - "scope": "server", - "docId": "kibCoreSavedObjectsPluginApi", - "section": "def-server.SavedObjectsClient", - "text": "SavedObjectsClient" - }, - ", \"get\" | \"delete\" | \"create\" | \"bulkCreate\" | \"checkConflicts\" | \"find\" | \"bulkGet\" | \"resolve\" | \"update\" | \"addToNamespaces\" | \"deleteFromNamespaces\" | \"bulkUpdate\" | \"removeReferencesTo\" | \"openPointInTimeForType\" | \"closePointInTime\" | \"createPointInTimeFinder\" | \"errors\">" - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/handle_old_settings/handle_old_settings.ts", - "lineNumber": 25 - } - }, - { - "id": "def-server.handleOldSettings.$2", - "type": "Object", - "label": "uiSettingsClient", - "isRequired": true, - "signature": [ - { - "pluginId": "core", - "scope": "server", - "docId": "kibCorePluginApi", - "section": "def-server.IUiSettingsClient", - "text": "IUiSettingsClient" - } - ], - "description": [], - "source": { - "path": "src/plugins/telemetry/server/handle_old_settings/handle_old_settings.ts", - "lineNumber": 26 - } - } - ], - "tags": [], - "returnComment": [], - "source": { - "path": "src/plugins/telemetry/server/handle_old_settings/handle_old_settings.ts", - "lineNumber": 24 - }, - "initialIsOpen": false - } - ], - "interfaces": [ - { - "id": "def-server.DataTelemetryIndex", - "type": "Interface", - "label": "DataTelemetryIndex", - "description": [], - "tags": [], - "children": [ - { - "tags": [], - "id": "def-server.DataTelemetryIndex.name", - "type": "string", - "label": "name", - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 39 - } - }, - { - "tags": [], - "id": "def-server.DataTelemetryIndex.packageName", - "type": "string", - "label": "packageName", - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 40 - }, - "signature": [ - "string | undefined" - ] - }, - { - "tags": [], - "id": "def-server.DataTelemetryIndex.managedBy", - "type": "string", - "label": "managedBy", - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 41 - }, - "signature": [ - "string | undefined" - ] - }, - { - "tags": [], - "id": "def-server.DataTelemetryIndex.dataStreamDataset", - "type": "string", - "label": "dataStreamDataset", - "description": [], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 42 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 44 }, "signature": [ - "string | undefined" + "() => Promise" ] }, { "tags": [], - "id": "def-server.DataTelemetryIndex.dataStreamType", - "type": "string", - "label": "dataStreamType", - "description": [], + "id": "def-public.TelemetryServicePublicApis.setOptIn", + "type": "Function", + "label": "setOptIn", + "description": [ + "\nOverwrite the opt-in status.\nIt will send a final request to the remote telemetry cluster to report about the opt-in/out change." + ], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 43 + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 50 }, "signature": [ - "string | undefined" + "(optedIn: boolean) => Promise" ] + } + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 36 + }, + "initialIsOpen": false + } + ], + "enums": [], + "misc": [], + "objects": [], + "start": { + "id": "def-public.TelemetryPluginStart", + "type": "Interface", + "label": "TelemetryPluginStart", + "description": [ + "\nPublic's start exposed APIs by the telemetry plugin" + ], + "tags": [], + "children": [ + { + "tags": [], + "id": "def-public.TelemetryPluginStart.telemetryService", + "type": "Object", + "label": "telemetryService", + "description": [ + "{@link TelemetryServicePublicApis}" + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 66 + }, + "signature": [ + { + "pluginId": "telemetry", + "scope": "public", + "docId": "kibTelemetryPluginApi", + "section": "def-public.TelemetryServicePublicApis", + "text": "TelemetryServicePublicApis" + } + ] + }, + { + "tags": [], + "id": "def-public.TelemetryPluginStart.telemetryNotifications", + "type": "Object", + "label": "telemetryNotifications", + "description": [ + "Notification helpers" + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 68 + }, + "signature": [ + "{ setOptedInNoticeSeen: () => Promise; }" + ] + }, + { + "tags": [], + "id": "def-public.TelemetryPluginStart.telemetryConstants", + "type": "Object", + "label": "telemetryConstants", + "description": [ + "Set of publicly exposed telemetry constants" + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 73 + }, + "signature": [ + "{ getPrivacyStatementUrl: () => string; }" + ] + } + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 64 + }, + "lifecycle": "start", + "initialIsOpen": true + }, + "setup": { + "id": "def-public.TelemetryPluginSetup", + "type": "Interface", + "label": "TelemetryPluginSetup", + "description": [ + "\nPublic's setup exposed APIs by the telemetry plugin" + ], + "tags": [], + "children": [ + { + "tags": [], + "id": "def-public.TelemetryPluginSetup.telemetryService", + "type": "Object", + "label": "telemetryService", + "description": [ + "{@link TelemetryService}" + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 58 }, + "signature": [ + { + "pluginId": "telemetry", + "scope": "public", + "docId": "kibTelemetryPluginApi", + "section": "def-public.TelemetryServicePublicApis", + "text": "TelemetryServicePublicApis" + } + ] + } + ], + "source": { + "path": "src/plugins/telemetry/public/plugin.ts", + "lineNumber": 56 + }, + "lifecycle": "setup", + "initialIsOpen": true + } + }, + "server": { + "classes": [], + "functions": [], + "interfaces": [ + { + "id": "def-server.DataTelemetryBasePayload", + "type": "Interface", + "label": "DataTelemetryBasePayload", + "description": [ + "\nCommon counters for the {@link DataTelemetryDocument}s" + ], + "tags": [], + "children": [ { "tags": [], - "id": "def-server.DataTelemetryIndex.shipper", - "type": "string", - "label": "shipper", - "description": [], + "id": "def-server.DataTelemetryBasePayload.index_count", + "type": "number", + "label": "index_count", + "description": [ + "How many indices match the declared pattern" + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 44 - }, - "signature": [ - "string | undefined" - ] + "lineNumber": 22 + } }, { "tags": [], - "id": "def-server.DataTelemetryIndex.isECS", - "type": "CompoundType", - "label": "isECS", - "description": [], + "id": "def-server.DataTelemetryBasePayload.ecs_index_count", + "type": "number", + "label": "ecs_index_count", + "description": [ + "How many indices match the declared pattern follow ECS conventions" + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 45 + "lineNumber": 24 }, "signature": [ - "boolean | undefined" + "number | undefined" ] }, { "tags": [], - "id": "def-server.DataTelemetryIndex.docCount", + "id": "def-server.DataTelemetryBasePayload.doc_count", "type": "number", - "label": "docCount", - "description": [], + "label": "doc_count", + "description": [ + "How many documents are among all the identified indices" + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 49 + "lineNumber": 26 }, "signature": [ "number | undefined" @@ -1129,13 +417,15 @@ }, { "tags": [], - "id": "def-server.DataTelemetryIndex.sizeInBytes", + "id": "def-server.DataTelemetryBasePayload.size_in_bytes", "type": "number", - "label": "sizeInBytes", - "description": [], + "label": "size_in_bytes", + "description": [ + "Total size in bytes among all the identified indices" + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 50 + "lineNumber": 28 }, "signature": [ "number | undefined" @@ -1144,154 +434,161 @@ ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 38 + "lineNumber": 20 }, "initialIsOpen": false }, { - "id": "def-server.NodeUsage", + "id": "def-server.DataTelemetryDocument", "type": "Interface", - "label": "NodeUsage", - "description": [], + "label": "DataTelemetryDocument", + "signature": [ + { + "pluginId": "telemetry", + "scope": "server", + "docId": "kibTelemetryPluginApi", + "section": "def-server.DataTelemetryDocument", + "text": "DataTelemetryDocument" + }, + " extends ", + { + "pluginId": "telemetry", + "scope": "server", + "docId": "kibTelemetryPluginApi", + "section": "def-server.DataTelemetryBasePayload", + "text": "DataTelemetryBasePayload" + } + ], + "description": [ + "\nDepending on the type of index, we'll populate different keys as we identify them." + ], "tags": [], "children": [ { "tags": [], - "id": "def-server.NodeUsage.node_id", - "type": "string", - "label": "node_id", - "description": [], + "id": "def-server.DataTelemetryDocument.data_stream", + "type": "Object", + "label": "data_stream", + "description": [ + "For data-stream indices. Reporting their details" + ], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 18 + "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", + "lineNumber": 36 }, "signature": [ - "string | undefined" + "{ dataset?: string | undefined; type?: string | undefined; } | undefined" ] }, { "tags": [], - "id": "def-server.NodeUsage.timestamp", - "type": "CompoundType", - "label": "timestamp", - "description": [], + "id": "def-server.DataTelemetryDocument.package", + "type": "Object", + "label": "package", + "description": [ + "When available, reporting the package details" + ], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 19 + "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", + "lineNumber": 43 }, "signature": [ - "React.ReactText" + "{ name: string; } | undefined" ] }, { "tags": [], - "id": "def-server.NodeUsage.since", - "type": "number", - "label": "since", - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 20 - } - }, - { - "tags": [], - "id": "def-server.NodeUsage.rest_actions", - "type": "Object", - "label": "rest_actions", - "description": [], + "id": "def-server.DataTelemetryDocument.shipper", + "type": "string", + "label": "shipper", + "description": [ + "What's the process indexing the data? (i.e.: \"beats\", \"logstash\")" + ], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 21 + "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", + "lineNumber": 48 }, "signature": [ - "{ [key: string]: number; }" + "string | undefined" ] }, { "tags": [], - "id": "def-server.NodeUsage.aggregations", - "type": "Object", - "label": "aggregations", - "description": [], + "id": "def-server.DataTelemetryDocument.pattern_name", + "type": "CompoundType", + "label": "pattern_name", + "description": [ + "When the data comes from a matching index-pattern, the name of the pattern" + ], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 24 + "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", + "lineNumber": 50 }, "signature": [ - "{ [key: string]: ", - { - "pluginId": "telemetry", - "scope": "server", - "docId": "kibTelemetryPluginApi", - "section": "def-server.NodeUsageAggregation", - "text": "NodeUsageAggregation" - }, - "; } | undefined" + "\"search\" | \"logstash\" | \"enterprise-search\" | \"app-search\" | \"magento2\" | \"magento\" | \"shopify\" | \"wordpress\" | \"drupal\" | \"joomla\" | \"sharepoint\" | \"squarespace\" | \"sitecore\" | \"weebly\" | \"acquia\" | \"filebeat\" | \"metricbeat\" | \"apm\" | \"functionbeat\" | \"heartbeat\" | \"fluentd\" | \"telegraf\" | \"prometheusbeat\" | \"fluentbit\" | \"nginx\" | \"apache\" | \"endgame\" | \"logs-endpoint\" | \"metrics-endpoint\" | \"siem-signals\" | \"auditbeat\" | \"winlogbeat\" | \"packetbeat\" | \"tomcat\" | \"artifactory\" | \"aruba\" | \"barracuda\" | \"bluecoat\" | \"arcsight\" | \"checkpoint\" | \"cisco\" | \"citrix\" | \"cyberark\" | \"cylance\" | \"fireeye\" | \"fortinet\" | \"infoblox\" | \"kaspersky\" | \"mcafee\" | \"paloaltonetworks\" | \"rsa\" | \"snort\" | \"sonicwall\" | \"sophos\" | \"squid\" | \"symantec\" | \"tippingpoint\" | \"trendmicro\" | \"tripwire\" | \"zscaler\" | \"zeek\" | \"sigma_doc\" | \"ecs-corelight\" | \"suricata\" | \"wazuh\" | \"meow\" | undefined" ] } ], "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 17 + "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", + "lineNumber": 34 }, "initialIsOpen": false }, { - "id": "def-server.NodeUsageAggregation", + "id": "def-server.NodeUsage", "type": "Interface", - "label": "NodeUsageAggregation", - "description": [], + "label": "NodeUsage", + "signature": [ + { + "pluginId": "telemetry", + "scope": "server", + "docId": "kibTelemetryPluginApi", + "section": "def-server.NodeUsage", + "text": "NodeUsage" + }, + " extends ", + "NodeUsageInformation" + ], + "description": [ + "\nData returned by GET /_nodes/usage, but flattened as an array of {@link estypes.NodeUsageInformation}\nwith the node ID set in the field `node_id`." + ], "tags": [], "children": [ { - "id": "def-server.NodeUsageAggregation.Unnamed", - "type": "Any", - "label": "Unnamed", "tags": [], - "description": [], + "id": "def-server.NodeUsage.node_id", + "type": "string", + "label": "node_id", + "description": [ + "\nThe Node ID as reported by ES" + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 13 - }, - "signature": [ - "any" - ] + "lineNumber": 21 + } } ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts", - "lineNumber": 12 + "lineNumber": 17 }, "initialIsOpen": false } ], "enums": [], "misc": [ - { - "tags": [], - "id": "def-server.DATA_TELEMETRY_ID", - "type": "string", - "label": "DATA_TELEMETRY_ID", - "description": [], - "source": { - "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/constants.ts", - "lineNumber": 9 - }, - "signature": [ - "\"data\"" - ], - "initialIsOpen": false - }, { "id": "def-server.DataTelemetryPayload", "type": "Type", "label": "DataTelemetryPayload", "tags": [], - "description": [], + "description": [ + "\nThe Data Telemetry is reported as an array of {@link DataTelemetryDocument}" + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts", - "lineNumber": 36 + "lineNumber": 56 }, "signature": [ "DataTelemetryDocument[]" @@ -1303,10 +600,12 @@ "type": "Type", "label": "TelemetryLocalStats", "tags": [], - "description": [], + "description": [ + "\nThe payload structure as composed by the OSS telemetry collection mechanism." + ], "source": { "path": "src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts", - "lineNumber": 51 + "lineNumber": 54 }, "signature": [ "{ timestamp: string; cluster_uuid: string; cluster_name: string; version: string; cluster_stats: Pick; collection: string; stack_stats: { data: DataTelemetryPayload | undefined; kibana: { count: number; indices: number; os: {}; versions: { version: string; count: number; }[]; plugins: { [plugin: string]: Record; }; } | undefined; }; }" @@ -1319,7 +618,9 @@ "id": "def-server.TelemetryPluginSetup", "type": "Interface", "label": "TelemetryPluginSetup", - "description": [], + "description": [ + "\nServer's setup exposed APIs by the telemetry plugin" + ], "tags": [], "children": [ { @@ -1332,7 +633,7 @@ ], "source": { "path": "src/plugins/telemetry/server/plugin.ts", - "lineNumber": 53 + "lineNumber": 56 }, "signature": [ "() => Promise<", @@ -1343,7 +644,7 @@ ], "source": { "path": "src/plugins/telemetry/server/plugin.ts", - "lineNumber": 48 + "lineNumber": 51 }, "lifecycle": "setup", "initialIsOpen": true @@ -1352,7 +653,9 @@ "id": "def-server.TelemetryPluginStart", "type": "Interface", "label": "TelemetryPluginStart", - "description": [], + "description": [ + "\nServer's start exposed APIs by the telemetry plugin" + ], "tags": [], "children": [ { @@ -1365,7 +668,7 @@ ], "source": { "path": "src/plugins/telemetry/server/plugin.ts", - "lineNumber": 62 + "lineNumber": 68 }, "signature": [ "() => Promise" @@ -1374,7 +677,7 @@ ], "source": { "path": "src/plugins/telemetry/server/plugin.ts", - "lineNumber": 56 + "lineNumber": 62 }, "lifecycle": "start", "initialIsOpen": true diff --git a/api_docs/telemetry.mdx b/api_docs/telemetry.mdx index f9a58d29ebd86..995c9b22e268a 100644 --- a/api_docs/telemetry.mdx +++ b/api_docs/telemetry.mdx @@ -19,9 +19,6 @@ import telemetryObj from './telemetry.json'; ### Start -### Classes - - ### Interfaces @@ -33,9 +30,6 @@ import telemetryObj from './telemetry.json'; ### Start -### Functions - - ### Interfaces diff --git a/src/plugins/telemetry/public/index.ts b/src/plugins/telemetry/public/index.ts index aef955e228dd3..8d1747d9c33f1 100644 --- a/src/plugins/telemetry/public/index.ts +++ b/src/plugins/telemetry/public/index.ts @@ -6,10 +6,15 @@ * Side Public License, v 1. */ -import { PluginInitializerContext } from 'kibana/public'; -import { TelemetryPlugin, TelemetryPluginConfig } from './plugin'; -export type { TelemetryPluginStart, TelemetryPluginSetup, TelemetryPluginConfig } from './plugin'; -export type { TelemetryNotifications, TelemetryService } from './services'; +import type { PluginInitializerContext } from 'src/core/public'; +import type { TelemetryPluginConfig } from './plugin'; +import { TelemetryPlugin } from './plugin'; +export type { + TelemetryPluginStart, + TelemetryPluginSetup, + TelemetryPluginConfig, + TelemetryServicePublicApis, +} from './plugin'; export function plugin(initializerContext: PluginInitializerContext) { return new TelemetryPlugin(initializerContext); diff --git a/src/plugins/telemetry/public/plugin.ts b/src/plugins/telemetry/public/plugin.ts index f7af01f0190ae..5e85fa7ea2d51 100644 --- a/src/plugins/telemetry/public/plugin.ts +++ b/src/plugins/telemetry/public/plugin.ts @@ -6,7 +6,7 @@ * Side Public License, v 1. */ -import { +import type { Plugin, CoreStart, CoreSetup, @@ -15,10 +15,10 @@ import { SavedObjectsClientContract, SavedObjectsBatchResponse, ApplicationStart, -} from '../../../core/public'; +} from 'src/core/public'; import { TelemetrySender, TelemetryService, TelemetryNotifications } from './services'; -import { +import type { TelemetrySavedObjectAttributes, TelemetrySavedObject, } from '../common/telemetry_config/types'; @@ -30,27 +30,73 @@ import { import { getNotifyUserAboutOptInDefault } from '../common/telemetry_config/get_telemetry_notify_user_about_optin_default'; import { PRIVACY_STATEMENT_URL } from '../common/constants'; +/** + * Publicly exposed APIs from the Telemetry Service + */ +export interface TelemetryServicePublicApis { + /** Is the cluster opted-in to telemetry? **/ + getIsOptedIn: () => boolean | null; + /** Is the user allowed to change the opt-in/out status? **/ + userCanChangeSettings: boolean; + /** Is the cluster allowed to change the opt-in/out status? **/ + getCanChangeOptInStatus: () => boolean; + /** Fetches an unencrypted telemetry payload so we can show it to the user **/ + fetchExample: () => Promise; + /** + * Overwrite the opt-in status. + * It will send a final request to the remote telemetry cluster to report about the opt-in/out change. + * @param optedIn Whether the user is opting-in (`true`) or out (`false`). + */ + setOptIn: (optedIn: boolean) => Promise; +} + +/** + * Public's setup exposed APIs by the telemetry plugin + */ export interface TelemetryPluginSetup { - telemetryService: TelemetryService; + /** {@link TelemetryService} **/ + telemetryService: TelemetryServicePublicApis; } +/** + * Public's start exposed APIs by the telemetry plugin + */ export interface TelemetryPluginStart { - telemetryService: TelemetryService; - telemetryNotifications: TelemetryNotifications; + /** {@link TelemetryServicePublicApis} **/ + telemetryService: TelemetryServicePublicApis; + /** Notification helpers **/ + telemetryNotifications: { + /** Notify that the user has been presented with the opt-in/out notice. */ + setOptedInNoticeSeen: () => Promise; + }; + /** Set of publicly exposed telemetry constants **/ telemetryConstants: { + /** Elastic's privacy statement url **/ getPrivacyStatementUrl: () => string; }; } +/** + * Public-exposed configuration + */ export interface TelemetryPluginConfig { + /** Is the plugin enabled? **/ enabled: boolean; + /** Remote telemetry service's URL **/ url: string; + /** The banner is expected to be shown when needed **/ banner: boolean; + /** Does the cluster allow changing the opt-in/out status via the UI? **/ allowChangingOptInStatus: boolean; + /** Is the cluster opted-in? **/ optIn: boolean | null; + /** Opt-in/out notification URL **/ optInStatusUrl: string; + /** Should the telemetry payloads be sent from the server or the browser? **/ sendUsageFrom: 'browser' | 'server'; + /** Should notify the user about the opt-in status? **/ telemetryNotifyUserAboutOptInDefault?: boolean; + /** Does the user have enough privileges to change the settings? **/ userCanChangeSettings?: boolean; } @@ -80,7 +126,7 @@ export class TelemetryPlugin implements Plugin { const isUnauthenticated = this.getIsUnauthenticated(http); @@ -119,14 +166,27 @@ export class TelemetryPlugin implements Plugin telemetryNotifications.setOptedInNoticeSeen(), + }, telemetryConstants: { getPrivacyStatementUrl: () => PRIVACY_STATEMENT_URL, }, }; } + private getTelemetryServicePublicApis(): TelemetryServicePublicApis { + const telemetryService = this.telemetryService!; + return { + getIsOptedIn: () => telemetryService.getIsOptedIn(), + setOptIn: (optedIn) => telemetryService.setOptIn(optedIn), + userCanChangeSettings: telemetryService.userCanChangeSettings, + getCanChangeOptInStatus: () => telemetryService.getCanChangeOptInStatus(), + fetchExample: () => telemetryService.fetchExample(), + }; + } + /** * Can the user edit the saved objects? * This is a security feature, not included in the OSS build, so we need to fallback to `true` diff --git a/src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts b/src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts index 5caf68b1981ea..0070cf7452767 100644 --- a/src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts +++ b/src/plugins/telemetry/public/services/telemetry_notifications/telemetry_notifications.ts @@ -17,6 +17,9 @@ interface TelemetryNotificationsConstructor { telemetryService: TelemetryService; } +/** + * Helpers to the Telemetry banners spread through the code base in Welcome and Home landing pages. + */ export class TelemetryNotifications { private readonly http: CoreStart['http']; private readonly overlays: CoreStart['overlays']; @@ -30,12 +33,18 @@ export class TelemetryNotifications { this.overlays = overlays; } + /** + * Should the opted-in banner be shown to the user? + */ public shouldShowOptedInNoticeBanner = (): boolean => { const userShouldSeeOptInNotice = this.telemetryService.getUserShouldSeeOptInNotice(); const bannerOnScreen = typeof this.optedInNoticeBannerId !== 'undefined'; return !bannerOnScreen && userShouldSeeOptInNotice; }; + /** + * Renders the banner that claims the cluster is opted-in, and gives the option to opt-out. + */ public renderOptedInNoticeBanner = (): void => { const bannerId = renderOptedInNoticeBanner({ http: this.http, @@ -46,12 +55,18 @@ export class TelemetryNotifications { this.optedInNoticeBannerId = bannerId; }; + /** + * Should the banner to opt-in be shown to the user? + */ public shouldShowOptInBanner = (): boolean => { const isOptedIn = this.telemetryService.getIsOptedIn(); const bannerOnScreen = typeof this.optInBannerId !== 'undefined'; return !bannerOnScreen && isOptedIn === null; }; + /** + * Renders the banner that claims the cluster is opted-out, and gives the option to opt-in. + */ public renderOptInBanner = (): void => { const bannerId = renderOptInBanner({ setOptIn: this.onSetOptInClick, @@ -61,6 +76,10 @@ export class TelemetryNotifications { this.optInBannerId = bannerId; }; + /** + * Opt-in/out button handler + * @param isOptIn true/false whether the user opts-in/out + */ private onSetOptInClick = async (isOptIn: boolean) => { if (this.optInBannerId) { this.overlays.banners.remove(this.optInBannerId); @@ -70,6 +89,9 @@ export class TelemetryNotifications { await this.telemetryService.setOptIn(isOptIn); }; + /** + * Clears the banner and stores the user's dismissal of the banner. + */ public setOptedInNoticeSeen = async (): Promise => { if (this.optedInNoticeBannerId) { this.overlays.banners.remove(this.optedInNoticeBannerId); diff --git a/src/plugins/telemetry/public/services/telemetry_sender.test.ts b/src/plugins/telemetry/public/services/telemetry_sender.test.ts index 82dbdb49f38f5..4dd1fe37a7569 100644 --- a/src/plugins/telemetry/public/services/telemetry_sender.test.ts +++ b/src/plugins/telemetry/public/services/telemetry_sender.test.ts @@ -71,20 +71,20 @@ describe('TelemetrySender', () => { const telemetryService = mockTelemetryService(); telemetryService.getIsOptedIn = jest.fn().mockReturnValue(false); const telemetrySender = new TelemetrySender(telemetryService); - const shouldSendRerpot = telemetrySender['shouldSendReport'](); + const shouldSendReport = telemetrySender['shouldSendReport'](); expect(telemetryService.getIsOptedIn).toBeCalledTimes(1); - expect(shouldSendRerpot).toBe(false); + expect(shouldSendReport).toBe(false); }); it('returns true if lastReported is undefined', () => { const telemetryService = mockTelemetryService(); telemetryService.getIsOptedIn = jest.fn().mockReturnValue(true); const telemetrySender = new TelemetrySender(telemetryService); - const shouldSendRerpot = telemetrySender['shouldSendReport'](); + const shouldSendReport = telemetrySender['shouldSendReport'](); expect(telemetrySender['lastReported']).toBeUndefined(); - expect(shouldSendRerpot).toBe(true); + expect(shouldSendReport).toBe(true); }); it('returns true if lastReported passed REPORT_INTERVAL_MS', () => { @@ -94,8 +94,8 @@ describe('TelemetrySender', () => { telemetryService.getIsOptedIn = jest.fn().mockReturnValue(true); const telemetrySender = new TelemetrySender(telemetryService); telemetrySender['lastReported'] = `${lastReported}`; - const shouldSendRerpot = telemetrySender['shouldSendReport'](); - expect(shouldSendRerpot).toBe(true); + const shouldSendReport = telemetrySender['shouldSendReport'](); + expect(shouldSendReport).toBe(true); }); it('returns false if lastReported is within REPORT_INTERVAL_MS', () => { @@ -105,8 +105,8 @@ describe('TelemetrySender', () => { telemetryService.getIsOptedIn = jest.fn().mockReturnValue(true); const telemetrySender = new TelemetrySender(telemetryService); telemetrySender['lastReported'] = `${lastReported}`; - const shouldSendRerpot = telemetrySender['shouldSendReport'](); - expect(shouldSendRerpot).toBe(false); + const shouldSendReport = telemetrySender['shouldSendReport'](); + expect(shouldSendReport).toBe(false); }); it('returns true if lastReported is malformed', () => { @@ -114,8 +114,8 @@ describe('TelemetrySender', () => { telemetryService.getIsOptedIn = jest.fn().mockReturnValue(true); const telemetrySender = new TelemetrySender(telemetryService); telemetrySender['lastReported'] = `random_malformed_string`; - const shouldSendRerpot = telemetrySender['shouldSendReport'](); - expect(shouldSendRerpot).toBe(true); + const shouldSendReport = telemetrySender['shouldSendReport'](); + expect(shouldSendReport).toBe(true); }); describe('sendIfDue', () => { diff --git a/src/plugins/telemetry/public/services/telemetry_service.ts b/src/plugins/telemetry/public/services/telemetry_service.ts index a3232a42d6b73..4ae2956902092 100644 --- a/src/plugins/telemetry/public/services/telemetry_service.ts +++ b/src/plugins/telemetry/public/services/telemetry_service.ts @@ -18,6 +18,10 @@ interface TelemetryServiceConstructor { reportOptInStatusChange?: boolean; } +/** + * Handles caching telemetry config in the user's session and requests the + * backend to fetch telemetry payload requests or notify about config changes. + */ export class TelemetryService { private readonly http: CoreStart['http']; private readonly reportOptInStatusChange: boolean; @@ -25,6 +29,7 @@ export class TelemetryService { private readonly defaultConfig: TelemetryPluginConfig; private updatedConfig?: TelemetryPluginConfig; + /** Current version of Kibana */ public readonly currentKibanaVersion: string; constructor({ @@ -41,40 +46,54 @@ export class TelemetryService { this.http = http; } + /** + * Config setter to locally persist the updated configuration. + * Useful for caching the configuration throughout the users' session, + * so they don't need to refresh the page. + * @param updatedConfig + */ public set config(updatedConfig: TelemetryPluginConfig) { this.updatedConfig = updatedConfig; } + /** Returns the latest configuration **/ public get config() { return { ...this.defaultConfig, ...this.updatedConfig }; } + /** Is the cluster opted-in to telemetry **/ public get isOptedIn() { return this.config.optIn; } + /** Changes the opt-in status **/ public set isOptedIn(optIn) { this.config = { ...this.config, optIn }; } + /** true if the user has already seen the opt-in/out notice **/ public get userHasSeenOptedInNotice() { return this.config.telemetryNotifyUserAboutOptInDefault; } + /** Changes the notice visibility options **/ public set userHasSeenOptedInNotice(telemetryNotifyUserAboutOptInDefault) { this.config = { ...this.config, telemetryNotifyUserAboutOptInDefault }; } + /** Is the cluster allowed to change the opt-in/out status **/ public getCanChangeOptInStatus = () => { const allowChangingOptInStatus = this.config.allowChangingOptInStatus; return allowChangingOptInStatus; }; + /** Retrieve the opt-in/out notification URL **/ public getOptInStatusUrl = () => { const telemetryOptInStatusUrl = this.config.optInStatusUrl; return telemetryOptInStatusUrl; }; + /** Retrieve the URL to report telemetry **/ public getTelemetryUrl = () => { const telemetryUrl = this.config.url; return telemetryUrl; @@ -92,22 +111,30 @@ export class TelemetryService { ); } + /** Is the user allowed to change the opt-in/out status **/ public get userCanChangeSettings() { return this.config.userCanChangeSettings ?? false; } + /** Change the user's permissions to change the opt-in/out status **/ public set userCanChangeSettings(userCanChangeSettings: boolean) { this.config = { ...this.config, userCanChangeSettings }; } + /** Is the cluster opted-in to telemetry **/ public getIsOptedIn = () => { return this.isOptedIn; }; + /** Fetches an unencrypted telemetry payload so we can show it to the user **/ public fetchExample = async () => { return await this.fetchTelemetry({ unencrypted: true }); }; + /** + * Fetches telemetry payload + * @param unencrypted Default `false`. Whether the returned payload should be encrypted or not. + */ public fetchTelemetry = async ({ unencrypted = false } = {}) => { return this.http.post('/api/telemetry/v2/clusters/_stats', { body: JSON.stringify({ @@ -116,6 +143,11 @@ export class TelemetryService { }); }; + /** + * Overwrite the opt-in status. + * It will send a final request to the remote telemetry cluster to report about the opt-in/out change. + * @param optedIn Whether the user is opting-in (`true`) or out (`false`). + */ public setOptIn = async (optedIn: boolean): Promise => { const canChangeOptInStatus = this.getCanChangeOptInStatus(); if (!canChangeOptInStatus) { @@ -150,6 +182,9 @@ export class TelemetryService { return true; }; + /** + * Discards the notice about usage collection and stores it so we don't bother any other users. + */ public setUserHasSeenNotice = async (): Promise => { try { await this.http.put('/api/telemetry/v2/userHasSeenNotice'); diff --git a/src/plugins/telemetry/server/index.ts b/src/plugins/telemetry/server/index.ts index 005f50721e778..530f7c499c3f2 100644 --- a/src/plugins/telemetry/server/index.ts +++ b/src/plugins/telemetry/server/index.ts @@ -8,10 +8,8 @@ import { PluginInitializerContext, PluginConfigDescriptor } from 'kibana/server'; import { TelemetryPlugin } from './plugin'; -import * as constants from '../common/constants'; import { configSchema, TelemetryConfigType } from './config'; -export { handleOldSettings } from './handle_old_settings'; export type { TelemetryPluginSetup, TelemetryPluginStart } from './plugin'; export const config: PluginConfigDescriptor = { @@ -29,18 +27,12 @@ export const config: PluginConfigDescriptor = { export const plugin = (initializerContext: PluginInitializerContext) => new TelemetryPlugin(initializerContext); -export { constants }; -export { - getClusterUuids, - getLocalStats, - DATA_TELEMETRY_ID, - buildDataTelemetryPayload, -} from './telemetry_collection'; +export { getClusterUuids, getLocalStats } from './telemetry_collection'; export type { TelemetryLocalStats, - DataTelemetryIndex, DataTelemetryPayload, + DataTelemetryDocument, + DataTelemetryBasePayload, NodeUsage, - NodeUsageAggregation, } from './telemetry_collection'; diff --git a/src/plugins/telemetry/server/plugin.ts b/src/plugins/telemetry/server/plugin.ts index 46b7bc89ca6f9..40714bf4cf2be 100644 --- a/src/plugins/telemetry/server/plugin.ts +++ b/src/plugins/telemetry/server/plugin.ts @@ -45,6 +45,9 @@ interface TelemetryPluginsDepsStart { telemetryCollectionManager: TelemetryCollectionManagerPluginStart; } +/** + * Server's setup exposed APIs by the telemetry plugin + */ export interface TelemetryPluginSetup { /** * Resolves into the telemetry Url used to send telemetry. @@ -53,6 +56,9 @@ export interface TelemetryPluginSetup { getTelemetryUrl: () => Promise; } +/** + * Server's start exposed APIs by the telemetry plugin + */ export interface TelemetryPluginStart { /** * Resolves `true` if the user has opted into send Elastic usage data. diff --git a/src/plugins/telemetry/server/telemetry_collection/get_cluster_stats.ts b/src/plugins/telemetry/server/telemetry_collection/get_cluster_stats.ts index 122fee5667bdf..dd5f4f97c6b02 100644 --- a/src/plugins/telemetry/server/telemetry_collection/get_cluster_stats.ts +++ b/src/plugins/telemetry/server/telemetry_collection/get_cluster_stats.ts @@ -21,6 +21,8 @@ export async function getClusterStats(esClient: ElasticsearchClient) { /** * Get the cluster uuids from the connected cluster. + * @internal only used externally by the X-Pack Telemetry extension + * @param esClient Scoped Elasticsearch client */ export const getClusterUuids: ClusterDetailsGetter = async ({ esClient }) => { const { body } = await esClient.cluster.stats({ timeout: TIMEOUT }); diff --git a/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts b/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts index c79c46072e11b..8a0b86cf3b0f0 100644 --- a/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts +++ b/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/get_data_telemetry.ts @@ -14,25 +14,45 @@ import { DataTelemetryType, } from './constants'; +/** + * Common counters for the {@link DataTelemetryDocument}s + */ export interface DataTelemetryBasePayload { + /** How many indices match the declared pattern **/ index_count: number; + /** How many indices match the declared pattern follow ECS conventions **/ ecs_index_count?: number; + /** How many documents are among all the identified indices **/ doc_count?: number; + /** Total size in bytes among all the identified indices **/ size_in_bytes?: number; } +/** + * Depending on the type of index, we'll populate different keys as we identify them. + */ export interface DataTelemetryDocument extends DataTelemetryBasePayload { + /** For data-stream indices. Reporting their details **/ data_stream?: { + /** Name of the dataset in the data-stream **/ dataset?: string; + /** Type of the data-stream: "logs", "metrics", "traces" **/ type?: DataTelemetryType | string; // The union of types is to help autocompletion with some known `data_stream.type`s }; + /** When available, reporting the package details **/ package?: { + /** The package's name. Typically populated in the indices' _meta.package.name by Fleet. **/ name: string; }; + /** What's the process indexing the data? (i.e.: "beats", "logstash") **/ shipper?: string; + /** When the data comes from a matching index-pattern, the name of the pattern **/ pattern_name?: DataPatternName; } +/** + * The Data Telemetry is reported as an array of {@link DataTelemetryDocument} + */ export type DataTelemetryPayload = DataTelemetryDocument[]; export interface DataTelemetryIndex { diff --git a/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/index.ts b/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/index.ts index c93b7e872924b..c5219e419efe7 100644 --- a/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/index.ts +++ b/src/plugins/telemetry/server/telemetry_collection/get_data_telemetry/index.ts @@ -8,4 +8,8 @@ export { DATA_TELEMETRY_ID } from './constants'; export { getDataTelemetry, buildDataTelemetryPayload } from './get_data_telemetry'; -export type { DataTelemetryPayload, DataTelemetryIndex } from './get_data_telemetry'; +export type { + DataTelemetryPayload, + DataTelemetryDocument, + DataTelemetryBasePayload, +} from './get_data_telemetry'; diff --git a/src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts b/src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts index 72f6ba855096c..7fdcb50b704af 100644 --- a/src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts +++ b/src/plugins/telemetry/server/telemetry_collection/get_local_stats.ts @@ -48,13 +48,17 @@ export function handleLocalStats; /** * Get statistics for all products joined by Elasticsearch cluster. - * @param {Array} cluster uuids array of cluster uuid's - * @param {Object} config contains the usageCollection, callCluster (deprecated), the esClient and Saved Objects client scoped to the request or the internal repository, and the kibana request - * @param {Object} StatsCollectionContext contains logger and version (string) + * @internal only used externally by the X-Pack Telemetry extension + * @param clustersDetails uuids array of cluster uuid's + * @param config contains the usageCollection, callCluster (deprecated), the esClient and Saved Objects client scoped to the request or the internal repository, and the kibana request + * @param context contains logger and version (string) */ export const getLocalStats: StatsGetter = async ( clustersDetails, diff --git a/src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts b/src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts index 544142c8d742f..c35b8a3d24498 100644 --- a/src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts +++ b/src/plugins/telemetry/server/telemetry_collection/get_nodes_usage.ts @@ -6,36 +6,22 @@ * Side Public License, v 1. */ -import { ElasticsearchClient } from 'src/core/server'; +import type { ElasticsearchClient } from 'src/core/server'; +import type { estypes } from '@elastic/elasticsearch'; import { TIMEOUT } from './constants'; -export interface NodeUsageAggregation { - [key: string]: number; -} - -// we set aggregations as an optional type because it was only added in v7.8.0 -export interface NodeUsage { - node_id?: string; - timestamp: number | string; - since: number; - rest_actions: { - [key: string]: number; - }; - aggregations?: { - [key: string]: NodeUsageAggregation; - }; -} - -export interface NodesFeatureUsageResponse { - cluster_name: string; - nodes: { - [key: string]: NodeUsage; - }; +/** + * Data returned by GET /_nodes/usage, but flattened as an array of {@link estypes.NodeUsageInformation} + * with the node ID set in the field `node_id`. + */ +export interface NodeUsage extends estypes.NodeUsageInformation { + /** + * The Node ID as reported by ES + */ + node_id: string; } -export type NodesUsageGetter = ( - esClient: ElasticsearchClient -) => Promise<{ nodes: NodeUsage[] | Array<{}> }>; +export type NodesUsageGetter = (esClient: ElasticsearchClient) => Promise<{ nodes: NodeUsage[] }>; /** * Get the nodes usage data from the connected cluster. * @@ -45,11 +31,10 @@ export type NodesUsageGetter = ( */ export async function fetchNodesUsage( esClient: ElasticsearchClient -): Promise { +): Promise { const { body } = await esClient.nodes.usage({ timeout: TIMEOUT, }); - // @ts-expect-error TODO: Does the client parse `timestamp` to a Date object? Expected a number return body; } @@ -61,7 +46,7 @@ export async function fetchNodesUsage( export const getNodesUsage: NodesUsageGetter = async (esClient) => { const result = await fetchNodesUsage(esClient); const transformedNodes = Object.entries(result?.nodes || {}).map(([key, value]) => ({ - ...(value as NodeUsage), + ...value, node_id: key, })); return { nodes: transformedNodes }; diff --git a/src/plugins/telemetry/server/telemetry_collection/index.ts b/src/plugins/telemetry/server/telemetry_collection/index.ts index f55147a0a083f..1126cbd1aa189 100644 --- a/src/plugins/telemetry/server/telemetry_collection/index.ts +++ b/src/plugins/telemetry/server/telemetry_collection/index.ts @@ -7,9 +7,13 @@ */ export { DATA_TELEMETRY_ID, buildDataTelemetryPayload } from './get_data_telemetry'; -export type { DataTelemetryIndex, DataTelemetryPayload } from './get_data_telemetry'; +export type { + DataTelemetryPayload, + DataTelemetryDocument, + DataTelemetryBasePayload, +} from './get_data_telemetry'; export { getLocalStats } from './get_local_stats'; export type { TelemetryLocalStats } from './get_local_stats'; -export type { NodeUsage, NodeUsageAggregation } from './get_nodes_usage'; +export type { NodeUsage } from './get_nodes_usage'; export { getClusterUuids } from './get_cluster_stats'; export { registerCollection } from './register_collection';