Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Telemetry settings: improve phrasing #158396

Merged
merged 2 commits into from
May 25, 2023
Merged

[DOCS] Telemetry settings: improve phrasing #158396

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
142bf78
[DOCS] Telemetry settings: improve phrasing
afharo May 24, 2023
e865d7d
Fix rogue "+"
afharo May 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 13 additions & 15 deletions docs/settings/telemetry-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,30 @@
<titleabbrev>Telemetry settings</titleabbrev>
++++

By default, Usage Collection (also known as Telemetry) is enabled. This
helps us learn about the {kib} features that our users are most interested in, so we
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mostly removing Kibana features because we also collect telemetry about other Elastic products.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page uses Usage Collection, Usage Data, and Telemetry. It's awkward to see all three terms on one page to mean the same thing. We should choose one term and use it consistently in the docs and UI copy.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point!

@cdanderson98, what do you think?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gchaps, I can see "Usage Data" is only used one (when referring to Kibana's Advanced Settings section.

If that's fine, I'll merge this docs PR so we can backport it to all previous versions, and we can update that to "Usage Collection" for the next release.

Re Usage Collection vs. Telemetry. I tend to prefer Usage Collection because Telemetry is too broad (it can also refer to Observabilty metrics). However, removing telemetry from the settings will introduce Breaking changes. That's the main reason we still handle 2 terms to refer to the same concept.

I hope it makes sense.

can focus our efforts on making them even better.
Usage Collection (also known as Telemetry) is enabled by default. This allows us to learn what our users are most interested in, so we can improve our products and services.

Refer to our https://www.elastic.co/legal/product-privacy-statement[Privacy Statement] to learn more.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved this higher to be closer to the definition of the service.

Then we can jump into the description of the options users can control


You can control whether this data is sent from the {kib} servers, or if it should be sent
from the user's browser, in case a firewall is blocking the connections from the server. Additionally, you can decide to completely disable this feature either in the config file or in {kib} via *Management > Kibana > Advanced Settings > Usage Data*.

Refer to our https://www.elastic.co/legal/product-privacy-statement[Privacy Statement] to learn more.

[float]
[[telemetry-general-settings]]
==== General telemetry settings

`telemetry.sendUsageFrom`::
Set to `'server'` to report the cluster statistics from the {kib} server.
If the server fails to connect to our endpoint at https://telemetry.elastic.co/, it assumes
it is behind a firewall and falls back to `'browser'` to send it from users' browsers
when they are navigating through {kib}. Defaults to `'server'`.
Comment on lines -20 to -24
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved it to the bottom because it feels like it's the least likely setting to be used.

Happy to move it back to the top if you think it's worth highlighting it first.


[[telemetry-optIn]] `telemetry.optIn`::
Set to `true` to send cluster statistics to Elastic. Reporting your
cluster statistics helps us improve your user experience. Set to `false` to stop sending any telemetry data to Elastic. +
Set to `false` to stop sending any telemetry data to Elastic. Reporting your
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's true by default. We think it's clearer if we explain the step to override the default.

cluster statistics helps us improve your user experience. *Default: `true`.*+
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving the default value closer to the flag definition. Being at the end of the extra note in the next paragraph made it harder to find.

+
This setting can be changed at any time in <<advanced-options, Advanced Settings>>.
To prevent users from changing it,
set <<telemetry-allowChangingOptInStatus, `telemetry.allowChangingOptInStatus`>> to `false`. Defaults to `true`.
set <<telemetry-allowChangingOptInStatus, `telemetry.allowChangingOptInStatus`>> to `false`.

`telemetry.allowChangingOptInStatus`::
Set to `true` to allow overwriting the <<telemetry-optIn, `telemetry.optIn`>> setting via the <<advanced-options, Advanced Settings>> in {kib}. Defaults to `true`.
Set to `false` to disallow overwriting the <<telemetry-optIn, `telemetry.optIn`>> setting via the <<advanced-options, Advanced Settings>> in {kib}. *Default: `true`.*

`telemetry.sendUsageFrom`::
Set to `'server'` to report the cluster statistics from the {kib} server.
If the server fails to connect to our endpoint at https://telemetry.elastic.co/, it assumes
it is behind a firewall and falls back to `'browser'` to send it from users' browsers
when they are navigating through {kib}. *Default: `'server'`.*
5 changes: 2 additions & 3 deletions docs/setup/settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -556,14 +556,13 @@ setting this to `true` enables unauthenticated users to access the {kib}
server status API and status page. *Default: `false`*

[[telemetry-allowChangingOptInStatus]] `telemetry.allowChangingOptInStatus`::
When `true`, users are able to change the telemetry setting at a later time in
<<advanced-options, Advanced Settings>>. When `false`, users cannot change the opt-in status through *Advanced Settings*, and
When `false`, users cannot change the opt-in status through <<advanced-options, Advanced Settings>>, and
{kib} only looks at the value of <<settings-telemetry-optIn, `telemetry.optIn`>> to determine whether to send telemetry data or not. *Default: `true`*.

[[settings-telemetry-optIn]] `telemetry.optIn`::
Set to `false` to stop sending any telemetry data to Elastic.
Reporting your cluster statistics helps
us improve your user experience.
Set to `true` to allow telemetry data to be sent to Elastic.
When `false`, the telemetry data is never sent to Elastic. +
+
This setting can be changed at any time in <<advanced-options, Advanced Settings>>.
Expand Down