|
1 | 1 | .. _label-usage-tracking: |
2 | 2 |
|
3 | | -Usage statistics collection |
| 3 | +Usage Statistics Collection |
4 | 4 | =========================== |
5 | 5 |
|
6 | | -Parsl uses an **Opt-in** model to send usage statistics back to the Parsl development team to |
7 | | -measure worldwide usage and improve reliability and usability. The usage statistics are used only for |
8 | | -improvements and reporting. They are not shared in raw form outside of the Parsl team. |
9 | | - |
| 6 | +Parsl uses an **Opt-in** model for usage tracking, allowing users to decide if they wish to participate. Usage statistics are crucial for improving software reliability and help focus development and maintenance efforts on the most used components of Parsl. The collected data is used solely for enhancements and reporting and is not shared in its raw form outside of the Parsl team. |
10 | 7 |
|
11 | 8 | Why are we doing this? |
12 | 9 | ---------------------- |
13 | 10 |
|
14 | | -The Parsl development team receives support from government funding agencies. For the team to continue to |
15 | | -receive such funding, and for the agencies themselves to argue for funding, both the team and the agencies |
16 | | -must be able to demonstrate that the scientific community is benefiting from these investments. To this end, |
17 | | -it is important that we provide aggregate usage data about such things as the following: |
| 11 | +The Parsl development team relies on funding from government agencies. To sustain this funding and advocate for continued support, it is essential to show that the research community benefits from these investments. |
| 12 | + |
| 13 | +By opting in to share usage data, you actively support the ongoing development and maintenance of Parsl. (See:ref:`What is sent? <what-is-sent>` below). |
| 14 | + |
| 15 | +Opt-In Model |
| 16 | +------------ |
| 17 | + |
| 18 | +We use an **opt-in model** for usage tracking to respect user privacy and provide full control over shared information. We hope that developers and researchers will choose to send us this information. The reason is that we need this data - it is a requirement for funding. |
18 | 19 |
|
19 | | -* How many people use Parsl |
20 | | -* Average job length |
21 | | -* Parsl exit codes |
| 20 | +Choose the data you share with Usage Tracking Levels. |
22 | 21 |
|
23 | | -By participating in this project, you help justify continuing support for the software on which you rely. |
24 | | -(see :ref:`What is sent? <what-is-sent>` below). |
| 22 | +**Usage Tracking Levels:** |
25 | 23 |
|
26 | | -Opt-In |
27 | | ------- |
| 24 | +* **Level 1:** Only basic information such as Python version, Parsl version, and platform name (Linux, MacOS, etc.) |
| 25 | +* **Level 2:** Level 1 information and configuration information including provider, executor, and launcher names. |
| 26 | +* **Level 3:** Level 2 information and workflow execution details, including the number of applications run, failures, and execution time. |
28 | 27 |
|
29 | | -We have chosen opt-in collection rather than opt-out with the hope that developers and researchers |
30 | | -will choose to send us this information. The reason is that we need this data - it is a requirement for funding. |
| 28 | +By enabling usage tracking, you support Parsl's development. |
31 | 29 |
|
32 | | -By opting-in, and allowing these statistics to be reported back, you are explicitly supporting the |
33 | | -further development of Parsl. |
| 30 | +**To opt-in, set** ``usage_tracking`` **to the desired level (1, 2, or 3) in the configuration object** (``parsl.config.Config``) **.** |
34 | 31 |
|
35 | | -If you wish to opt in to usage reporting, set ``usage_tracking=True`` in the configuration object (`parsl.config.Config`). |
| 32 | +Example: |
36 | 33 |
|
| 34 | +.. code-block:: python3 |
| 35 | +
|
| 36 | + config = Config( |
| 37 | + executors=[ |
| 38 | + HighThroughputExecutor( |
| 39 | + ... |
| 40 | + ) |
| 41 | + ], |
| 42 | + usage_tracking=3 |
| 43 | + ) |
37 | 44 |
|
38 | 45 | .. _what-is-sent: |
39 | 46 |
|
40 | 47 | What is sent? |
41 | 48 | ------------- |
42 | 49 |
|
43 | | -* IP address |
44 | | -* Run UUID |
45 | | -* Start and end times |
46 | | -* Number of executors used |
47 | | -* Number of failures |
48 | | -* Parsl and Python version |
49 | | -* OS and OS version |
50 | | - |
| 50 | +The data collected depends on the tracking level selected: |
| 51 | + |
| 52 | +* **Level 1:** Only basic information such as Python version, Parsl version, and platform name (Linux, MacOS, etc.) |
| 53 | +* **Level 2:** Level 1 information and configuration information including provider, executor, and launcher names. |
| 54 | +* **Level 3:** Level 2 information and workflow execution details, including the number of applications run, failures, and execution time. |
| 55 | + |
| 56 | +**Example Messages:** |
| 57 | + |
| 58 | +- At launch: |
| 59 | + |
| 60 | + .. code-block:: json |
| 61 | +
|
| 62 | + { |
| 63 | + "correlator":"6bc7484e-5693-48b2-b6c0-5889a73f7f4e", |
| 64 | + "parsl_v":"1.3.0-dev", |
| 65 | + "python_v":"3.12.2", |
| 66 | + "platform.system":"Darwin", |
| 67 | + "tracking_level":3, |
| 68 | + "components":[ |
| 69 | + { |
| 70 | + "c":"parsl.config.Config", |
| 71 | + "executors_len":1, |
| 72 | + "dependency_resolver":false |
| 73 | + }, |
| 74 | + "parsl.executors.threads.ThreadPoolExecutor" |
| 75 | + ], |
| 76 | + "start":1727156153 |
| 77 | + } |
| 78 | +
|
| 79 | +- On closure (Tracking Level 3 only): |
| 80 | + |
| 81 | + .. code-block:: json |
| 82 | +
|
| 83 | + { |
| 84 | + "correlator":"6bc7484e-5693-48b2-b6c0-5889a73f7f4e", |
| 85 | + "execution_time":31, |
| 86 | + "components":[ |
| 87 | + { |
| 88 | + "c":"parsl.dataflow.dflow.DataFlowKernel", |
| 89 | + "app_count":3, |
| 90 | + "app_fails":0 |
| 91 | + }, |
| 92 | + { |
| 93 | + "c":"parsl.config.Config", |
| 94 | + "executors_len":1, |
| 95 | + "dependency_resolver":false |
| 96 | + }, |
| 97 | + "parsl.executors.threads.ThreadPoolExecutor" |
| 98 | + ], |
| 99 | + "end":1727156156 |
| 100 | + } |
| 101 | +
|
| 102 | +**All messages sent are logged in the** ``parsl.log`` **file, ensuring complete transparency.** |
51 | 103 |
|
52 | 104 | How is the data sent? |
53 | 105 | --------------------- |
54 | 106 |
|
55 | | -The data is sent via UDP. While this may cause us to lose some data, it drastically reduces the possibility |
56 | | -that the usage statistics reporting will adversely affect the operation of the software. |
| 107 | +Data is sent using **UDP** to minimize the impact on workflow performance. While this may result in some data loss, it significantly reduces the chances of usage tracking affecting the software's operation. |
57 | 108 |
|
| 109 | +The data is processed through AWS CloudWatch to generate a monitoring dashboard, providing valuable insights into usage patterns. |
58 | 110 |
|
59 | 111 | When is the data sent? |
60 | 112 | ---------------------- |
61 | 113 |
|
62 | | -The data is sent twice per run, once when Parsl starts a script, and once when the script is completed. |
| 114 | +Data is sent twice per run: |
63 | 115 |
|
| 116 | +1. At the start of the script. |
| 117 | +2. Upon script completion (for Tracking Level 3). |
64 | 118 |
|
65 | 119 | What will the data be used for? |
66 | 120 | ------------------------------- |
67 | 121 |
|
68 | | -The data will be used for reporting purposes to answer questions such as: |
| 122 | +The data will help the Parsl team understand Parsl usage and make development and maintenance decisions, including: |
| 123 | + |
| 124 | +* Focus development and maintenance on the most-used components of Parsl. |
| 125 | +* Determine which Python versions to continue supporting. |
| 126 | +* Track the age of Parsl installations. |
| 127 | +* Assess how long it takes for most users to adopt new changes. |
| 128 | +* Track usage statistics to report to funders. |
| 129 | + |
| 130 | +Usage Statistics Dashboard |
| 131 | +-------------------------- |
69 | 132 |
|
70 | | -* How many unique users are using Parsl? |
71 | | -* To determine patterns of usage - is activity increasing or decreasing? |
| 133 | +The collected data is aggregated and displayed on a publicly accessible dashboard. This dashboard provides an overview of how Parsl is being used across different environments and includes metrics such as: |
72 | 134 |
|
73 | | -We will also use this information to improve Parsl by identifying software faults. |
| 135 | +* Total workflows executed over time |
| 136 | +* Most-used Python and Parsl versions |
| 137 | +* Most common platforms and executors and more |
74 | 138 |
|
75 | | -* What percentage of tasks complete successfully? |
76 | | -* Of the tasks that fail, what is the most common fault code returned? |
| 139 | +`Find the dashboard here <https://cloudwatch.amazonaws.com/dashboard.html?dashboard=Parsl-Usage-Tracking-Stats&context=eyJSIjoidXMtZWFzdC0xIiwiRCI6ImN3LWRiLTA0Njc5ODQ4MjQwNiIsIlUiOiJ1cy1lYXN0LTFfNW41R1BwYVd0IiwiQyI6IjN2bzJmbzAxYnI1dm92YjY2dGEwcmo2dmNkIiwiSSI6InVzLWVhc3QtMTplMjYyZGZkMy05NjI2LTQ4YTMtYjBkOC1jYWYwYWU1NzA4M2EiLCJPIjoiYXJuOmF3czppYW06OjA0Njc5ODQ4MjQwNjpyb2xlL3NlcnZpY2Utcm9sZS9DV0RCU2hhcmluZy1QdWJsaWNSZWFkT25seUFjY2Vzcy1UTlBOMk5COSIsIk0iOiJQdWJsaWMifQ==&start=PT3H&end=null>`_ |
77 | 140 |
|
| 141 | +Leaderboard |
| 142 | +----------- |
| 143 | + |
| 144 | +**Opting in to usage tracking also allows you to participate in the Parsl Leaderboard. |
| 145 | +To participate in the leaderboard, you can deanonymize yourself using the** ``project_name`` **parameter in the parsl configuration object** (``parsl.config.Config``) **.** |
| 146 | + |
| 147 | +`Find the Parsl Leaderboard here <https://cloudwatch.amazonaws.com/dashboard.html?dashboard=Parsl-Usage-Tracking-Stats&context=eyJSIjoidXMtZWFzdC0xIiwiRCI6ImN3LWRiLTA0Njc5ODQ4MjQwNiIsIlUiOiJ1cy1lYXN0LTFfNW41R1BwYVd0IiwiQyI6IjN2bzJmbzAxYnI1dm92YjY2dGEwcmo2dmNkIiwiSSI6InVzLWVhc3QtMTplMjYyZGZkMy05NjI2LTQ4YTMtYjBkOC1jYWYwYWU1NzA4M2EiLCJPIjoiYXJuOmF3czppYW06OjA0Njc5ODQ4MjQwNjpyb2xlL3NlcnZpY2Utcm9sZS9DV0RCU2hhcmluZy1QdWJsaWNSZWFkT25seUFjY2Vzcy1UTlBOMk5COSIsIk0iOiJQdWJsaWMifQ==&start=PT3H&end=null>`_ |
| 148 | + |
| 149 | +Example: |
| 150 | + |
| 151 | +.. code-block:: python3 |
| 152 | +
|
| 153 | + config = Config( |
| 154 | + executors=[ |
| 155 | + HighThroughputExecutor( |
| 156 | + ... |
| 157 | + ) |
| 158 | + ], |
| 159 | + usage_tracking=3, |
| 160 | + project_name="my-test-project" |
| 161 | + ) |
| 162 | +
|
| 163 | +Every run of parsl with usage tracking **Level 1** or **Level 2** earns you **1 point**. And every run with usage tracking **Level 3**, earns you **2 points**. |
| 164 | + |
78 | 165 | Feedback |
79 | 166 | -------- |
80 | 167 |
|
81 | | -Please send us your feedback at [email protected]. Feedback from our user communities will be |
| 168 | +Please send us your feedback at [email protected]. Feedback from our user communities will be |
82 | 169 | useful in determining our path forward with usage tracking in the future. |
| 170 | + |
| 171 | +**Please consider turning on usage tracking to support the continued development of Parsl.** |
0 commit comments