1.. _module-pw_cli_analytics: 2 3---------------- 4pw_cli_analytics 5---------------- 6This module collects and transmits analytics on usage of the ``pw`` command line 7interface. This will help the Pigweed team improve its command line utilities. 8By default this will be enabled, but it can be disabled on a per-project, 9per-user, or per-project/per-user basis. Individuals can completely opt-out by 10running ``pw cli-analytics --opt-out``, and can opt-in by running 11``pw cli-analytics --opt-in``. 12 13Analytics 14========= 15Pigweed collects analytics on the use of the ``pw`` command. For projects using 16Pigweed the default is to just collect details about the host machine 17(operating system, CPU architecture, and CPU core count), but no data about the 18exact command run or the project in question. This can be disabled by setting 19``enabled`` to false in the files listed below. The default values for all the 20project-specific analytics options are below. 21 22For development on Pigweed itself, these options are all specifically enabled. 23 24``debug_url`` 25 Google Analytics URL to use when debugging. Defaults to 26 https://www.google-analytics.com/debug/mp/collect. 27 28``prod_url`` 29 Google Analytics URL to use in production. Defaults to 30 https://www.google-analytics.com/mp/collect. 31 32``report_command_line`` 33 If ``true``, the report will include the full command line with all arguments. 34 The home directory and any references to the username will be masked. 35 36``report_project_name`` 37 If ``true``, the ``root_variable`` entry from ``pigweed.json`` will be 38 reported. This is the name of the root variable, not its value. 39 40``report_remote_url`` 41 If ``true``, the remote URL will be reported. 42 43``report_subcommand_name`` 44 ``never`` 45 The subcommand name will not be reported. 46 47 ``limited`` 48 The subcommand name will be reported if and only if it's one of the 49 subcommands defined in Pigweed itself. These are ``analytics``, ``bloat``, 50 ``build``, ``console``, ``doctor``, ``emu``, ``format``, ``heap-viewer``, 51 ``help``, ``ide``, ``keep-sorted``, ``logdemo``, ``module``, ``package``, 52 ``presubmit``, ``python-packages``, ``requires``, ``rpc``, ``test``, 53 ``update``, and ``watch``. 54 55 ``always`` 56 The subcommand name will always be reported. 57 58.. code-block:: json 59 60 { 61 "pw": { 62 "pw_cli_analytics": { 63 "prod_url": "https://www.google-analytics.com/mp/collect", 64 "debug_url": "https://www.google-analytics.com/debug/mp/collect", 65 "report_command_line": false, 66 "report_project_name": false, 67 "report_remote_url": false, 68 "report_subcommand_name": "limited" 69 } 70 } 71 } 72 73There are three places these configs can be set, with increasing precedence: 74 75* The project config, at ``<project-root>/pigweed.json``, 76* The user/project config, at ``<project-root>/.pw_cli_analytics.user.json``, 77 and 78* The user config, at ``~/.pw_cli_analytics.json``. 79 80The user config contains a UUID for the user. It's set to a new value when 81opting in (manually or by running ``pw cli-analytics --opt-in``) and cleared 82when opting out (with ``pw cli-analytics --opt-out``). 83 84In general, decisions about what is shared about the project must come from the 85project config, the unique id of the user must come from the user config, and 86other details can be set in any config. Also, a ``false`` value for ``enabled`` 87can't be overridden. 88 89In addition, if ``PW_DISABLE_CLI_ANALYTICS`` is set, then all reporting is 90disabled. 91