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.

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

fix(telemetry): Update README.md for opt-out model #790

Merged
56 changes: 25 additions & 31 deletions kedro-telemetry/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,50 +20,44 @@ for further information on the intent of the data collection and what data is co
For technical information on how the telemetry collection works, you can browse
[the source code of `kedro-telemetry`](https://github.com/kedro-org/kedro-plugins/tree/main/kedro-telemetry).

## How do I consent to the use of Kedro-Telemetry?

Kedro-Telemetry is a Python plugin. To install it:
## How is the data collected

```console
pip install kedro-telemetry
```
Kedro-Telemetry uses [`pluggy`](https://pypi.org/project/pluggy/) hooks and [`requests`](https://pypi.org/project/requests/) to send data to [Heap Analytics](https://heap.io/). Project maintainers have access to the data and can create dashboards that show adoption and feature usage.

> _Note:_ If you are using an official [Kedro project template](https://kedro.readthedocs.io/en/stable/02_get_started/06_starters.html) then `kedro-telemetry` is included in the [project-level `requirements.txt`](https://kedro.readthedocs.io/en/stable/04_kedro_project_setup/01_dependencies.html#kedro-install) of the starter. `kedro-telemetry` is activated after you have a created a new project with a [Kedro project template](https://kedro.readthedocs.io/en/stable/02_get_started/06_starters.html) and have run `kedro install` from the terminal.
## How do I withdraw consent?
ElenaKhaustova marked this conversation as resolved.
Show resolved Hide resolved

When you next run the Kedro CLI you will be asked for consent to share usage analytics data for the purposes explained in the privacy notice, and a `.telemetry` YAML file will be created in the project root directory. The variable `consent` will be set according to your choice in the file, e.g. if you consent:
Data collection for telemetry is enabled by default. To withdraw consent, you have a few options:

```yaml
consent: true
```
1. **Set Environment Variables**:
Copy link
Contributor

Choose a reason for hiding this comment

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

Shall we also add some explanation on what happens if several options are applied at the same time, how they redefine each other?

Relates to: #785

Copy link
Member Author

Choose a reason for hiding this comment

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

Good catch with that bug. I added a description about the priority of the environment variables and overriding the .telemetry file. I believe we will fix the bug.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yep, let's wait until the fix and then revisit this paragraph to make sure they align.

Set the environment variables `DO_NOT_TRACK` or `KEDRO_DISABLE_TELEMETRY` to any value. The presence of any of these environment variables will disable telemetry for all Kedro projects in that environment and will override any consent specified in the `.telemetry` file of the specific project.

>*Note:* The `.telemetry` file should not be committed to `git` or packaged in deployment. In `kedro>=0.17.4` the file is git-ignored.
2. **CLI Option When Creating a New Project**:
When creating a new project, you can use the command:

## How do I withdraw consent?
```console
kedro new --telemetry=no
```
This will create a new project with a `.telemetry` file in its root folder, containing `consent: false`. This file will be used when executing Kedro commands within that project folder. Note that telemetry data about the execution of the `kedro new` command will still be sent if telemetry has not been disabled using environment variables.

To withdraw consent, you can change the `consent` variable to `false` in `.telemetry` YAML by editing the file in the following way:
>*Note:* The `.telemetry` file should not be committed to `git` or packaged in deployment. In `kedro>=0.17.4` the file is git-ignored.

```yaml
consent: false
```
You can also set `DO_NOT_TRACK` or `KEDRO_DISABLE_TELEMETRY` environment variable to `True`.
3. **Modify or Create the `.telemetry` file manually**:
If the `.telemetry` file exists in the root folder of your Kedro project, set the `consent` variable to `false`. If the file does not exist, create it with the following content:
```yaml
consent: false
```

Or you can uninstall the plugin:
4. **Uninstall the plugin**:
Remove the `kedro-telemetry` plugin:

```console
pip uninstall kedro-telemetry
```
```console
pip uninstall kedro-telemetry
```
>*Note:* This is a last resort option, as it will break the dependencies of Kedro (for example, `pip check` will report issues).

## What happens when I withdraw consent?

Data will only be collected if consent is given. Otherwise, if consent was explicitly denied or withdrawn, the message below will be printed out on every Kedro CLI invocation. If you explicitly deny consent from the beginning, no data will be collected. If you withdraw consent later, the processing of data will be stopped from that moment on.

```
Kedro-Telemetry is installed, but you have opted out of sharing usage analytics so none will be collected.
```

## How is the data collected

Kedro-Telemetry uses [`pluggy`](https://pypi.org/project/pluggy/) hooks and [`requests`](https://pypi.org/project/requests/) to send data to [Heap Analytics](https://heap.io/). Project maintainers have access to the data and can create dashboards that show adoption and feature usage.
If you explicitly deny consent from the beginning, no data will be collected. If you withdraw consent later, the processing of data will be stopped from that moment on.

## What licence do you use?

Expand Down