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