README.html

<!DOCTYPE html>
<meta charset="utf-8">
<!--markdown .md to HTML conversion courtesy of https://markdowntohtml.com/ -->
<html lang="en">
<head>
    <title>README count-tasks and gcount-tasks</title>
</head>
<h1 id="countboinctasks">Project: countBOINCtasks</h1>
<p><img src="images/count_logo_sm.png" alt="count_logo"></p>
<h2 id="count-tasks">count-tasks</h2>
<p>A utility for monitoring task data reported by the boinc-client.
It may be useful for comparing task productivity between different computers or configurations. See further below for GUI and standalone implementations.</p>
<p>Developed with Python 3.8, under Ubuntu 20.04, Windows 10 and macOS 10.13. Unless running one of the standalones, you
 may need to download or update to Python 3.6 or later. Recent Python
  packages can be downloaded from <a href="https://www.python.org/downloads/">https://www.python.org/downloads/</a>.</p>
<h3 id="usage-for-the-gui-version-gcount-tasks">Usage for The GUI version: gcount-tasks</h3>
<p>Download the .zip package from the Code download button and extract to your
 favorite folder. From within the resulting countBOINCtasks-main folder, open a Terminal or Command Prompt window. The exact invocation on the command line may slightly differ depending on how your PATH environment variable is set. As with any downloaded Python program, it is recommended that it be run in a virtual environment to avoid conflicts with other Python programs.</p>
<p>Download and run as described under Usage, but launch the program with these Terminal or Command Prompt commands from within the parent folder:</p>
<ul>
<li>Linux or Mac OS: <code>python3 -m gcount-tasks</code>
<li>Windows: <code>python -m gcount-tasks</code> or <code>py -m gcount-tasks</code>
</ul>

<p>For a brief description and version number, use the <code>--about</code> command line option.</p>
<p>Features in the GUI version:</p>
<ul>
<li>View the log file in a pop-up window.
<li>Backup the log file.
<li>Analysis and plotting of data recorded in the log file.
<li>Archive the log and analysis files from File menu.
<li>Pop-up Help menu.
</ul>

<p><img src="images/gcount-tasks_scrnshot.png" alt="gcount-tasks main window">
<p><img src="images/gcount-tasks_analysis.png" alt="log-analysis"></p>
<p>Iniitial plot of task time data in the log file.
<p><img src="images/gcount-tasks_plot.png" alt="time-plot"></p>
<p>Use of magnifier tool to zoom in on average task times.
<p><img src="images/gcount-tasks_plot_Yzoom.png" alt="zoom-plot"></p>
<p>Zoom in again for two weeks of task time data.
<p><img src="images/gcount-tasks_plot_XYzoom.png" alt="zoom-plot"></p>
<p>Initial view showing all logged task count data.
<p><img src="images/gcount-tasks_plot_counts.png" alt="zoom-plot"></p>
<p>If the plotting function does not seem to be working, it can be tested with example log data provided with this distribution. From the Help menu, select &quot;Test example data&quot; to produce this plot window:
<p><img src="images/gcount-tasks_testplot.png" alt="example-plot"></p>
<h3 id="usage-for-the-command-line-version-count-tasks">Usage for the command line version: count-tasks</h3>
<p>From the downloaded main folder, described above, open a Terminal and call up the help option with the following command:</p>
<p><ul>
<p><li>Linux or Mac OS: <code>./count-tasks --help</code> -or- <code>python3 count-tasks --help</code>
<p><li>Windows: <code>python count-tasks --help</code> -or- <code>py count-tasks --help</code>
</ul>
<p>Depending on your Python path settings in Windows, double-clicking on
the count-tasks file icon may automatically launch the program, with its default settings, in a Terminal window.</p>
<p>Default settings assume a default location of the BOINC folder from the
 BOINC installer. If you have put the BOINC folder in a different location,
  then there will be a command line option to enter that custom path to run
   boinc-client&#39;s boinccmd (or boinccmd.exe) executable. A custom command
    path can also be added to the countCFG.txt configuration file to avoid
     entering the path on the command line.</p>
<pre><code>~/countBOINCtasks-main$ ./<span class="hljs-keyword">count</span>-tasks --<span class="hljs-keyword">help</span>
usage: <span class="hljs-keyword">count</span>-tasks [-<span class="hljs-keyword">h</span>] [--<span class="hljs-keyword">about</span>] [--<span class="hljs-keyword">log</span> {yes,<span class="hljs-keyword">no</span>}] [--interval <span class="hljs-keyword">M</span>] [--summary TIMEunit] [--count_lim <span class="hljs-keyword">N</span>]

optional arguments:
  -<span class="hljs-keyword">h</span>, --<span class="hljs-keyword">help</span>          show this <span class="hljs-keyword">help</span> message and <span class="hljs-keyword">exit</span>
  --<span class="hljs-keyword">about</span>             Author, <span class="hljs-keyword">copyright</span>, and GNU license
  --<span class="hljs-keyword">log</span> {yes,<span class="hljs-keyword">no</span>}      Create <span class="hljs-keyword">log</span> <span class="hljs-keyword">file</span> of results or <span class="hljs-keyword">append</span> to existing <span class="hljs-keyword">log</span> (default: yes)
  --interval <span class="hljs-keyword">M</span>        Specify minutes between task counts (default: 60)
  --summary TIMEunit  Specify time between <span class="hljs-keyword">count</span> summaries, <span class="hljs-keyword">e</span>.<span class="hljs-keyword">g</span>., 12h, 7d (default: 1d)
  --count_lim <span class="hljs-keyword">N</span>       Specify number of <span class="hljs-keyword">count</span> reports until <span class="hljs-keyword">program</span> exits (default: 1008); 0 provides current data
</code></pre><p>Options can be abbreviated, e.g., <code>./count-tasks --l --i 15 --s 1h --c 12</code></p>
<p>Running the default settings (no optional arguments), will count the
 number of tasks reported to the BOINC Project server on a repeating
  interval of 1 hour, with summaries provided every 24 hr. Basic statistics
   for task times are also provided for each count interval. The initial
    data report provided immediately upon program launch is for the most recent
     tasks reported by boinc-client during the past hour. Repeating
      counts intervals begin after the initial report (see TIP, below).</p>
<p>Example report results, using default settings:</p>
<pre><code><span class="hljs-symbol">:~/CountBOINCtasks-main</span>$ ./count-tasks
<span class="hljs-number">2021</span>-Jul-<span class="hljs-number">21</span> <span class="hljs-number">06</span><span class="hljs-symbol">:</span><span class="hljs-number">14</span><span class="hljs-symbol">:</span><span class="hljs-number">14</span>; Number of tasks <span class="hljs-keyword">in</span> the most recent BOINC <span class="hljs-symbol">report:</span> <span class="hljs-number">11</span>
                      Task <span class="hljs-symbol">Time:</span> mean <span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">19</span><span class="hljs-symbol">:</span><span class="hljs-number">25</span>, range [<span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">13</span><span class="hljs-symbol">:</span><span class="hljs-number">14</span> - <span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">21</span><span class="hljs-symbol">:</span><span class="hljs-number">05</span>],
                                 stdev <span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">02</span><span class="hljs-symbol">:</span><span class="hljs-number">11</span>, total <span class="hljs-number">03</span><span class="hljs-symbol">:</span><span class="hljs-number">33</span><span class="hljs-symbol">:</span><span class="hljs-number">43</span>
                      Total tasks <span class="hljs-keyword">in</span> <span class="hljs-symbol">queue:</span> <span class="hljs-number">35</span>
                      Number of scheduled count <span class="hljs-symbol">intervals:</span> <span class="hljs-number">1008</span>
                      Counts every <span class="hljs-number">60</span>m, summaries every <span class="hljs-number">1</span>d
Timed intervals beginning now...

<span class="hljs-number">2021</span>-Jul-<span class="hljs-number">21</span> <span class="hljs-number">07</span><span class="hljs-symbol">:</span><span class="hljs-number">14</span><span class="hljs-symbol">:</span><span class="hljs-number">18</span>; Tasks reported <span class="hljs-keyword">in</span> the past <span class="hljs-number">60</span><span class="hljs-symbol">m:</span> <span class="hljs-number">12</span>
                      Task <span class="hljs-symbol">Time:</span> mean <span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">20</span><span class="hljs-symbol">:</span><span class="hljs-number">29</span>, range [<span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">18</span><span class="hljs-symbol">:</span><span class="hljs-number">47</span> - <span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">24</span><span class="hljs-symbol">:</span><span class="hljs-number">41</span>],
                                 stdev <span class="hljs-number">00</span><span class="hljs-symbol">:</span><span class="hljs-number">01</span><span class="hljs-symbol">:</span><span class="hljs-number">33</span>, total <span class="hljs-number">04</span><span class="hljs-symbol">:</span><span class="hljs-number">05</span><span class="hljs-symbol">:</span><span class="hljs-number">48</span>
                      Total tasks <span class="hljs-keyword">in</span> <span class="hljs-symbol">queue:</span> <span class="hljs-number">30</span>

<span class="hljs-number">1007</span> counts remaining <span class="hljs-keyword">until</span> exit.
<span class="hljs-number">13</span>m <span class="hljs-params">||</span><span class="hljs-params">||</span><span class="hljs-params">||</span><span class="hljs-params">||</span><span class="hljs-params">||</span>&lt; ~time to <span class="hljs-keyword">next</span> count
</code></pre><p>A countdown timer displays, in a colored bar, the approximate time remaining until the next task count.</p>
<p>Running with the <code>--log</code> option will save data to the log file in the
 working folder. This file is appended to or created when the program is
  launched.</p>
<p>You can let <code>count-tasks</code> run in an open terminal window with negligible
 impact on system resources. Stop it with <em>Ctrl-C</em> or let it stop
  automatically.  With default settings, it will stop after 6 weeks (1008
   1hr count cycles). A different count cycle limit can be set with the
    <code>--count_lim</code> option.</p>
<p>NOTE: Summary counts may be less than the sum of individual counts because
 of persistence of reported tasks between count intervals. This can be
  expected when the <code>--interval</code>option is set to less than the default 60
   (minutes). The boinc-client command that provides reported task data
   , <code>boinccmd  --get_old_tasks</code>, retrieves tasks reported for the past hour
   , independent of the utility&#39;s count interval. To avoid missing any
    reported tasks, the <code>--interval</code> option has a 60 minutes maximum count
     interval.</p>
<p>TIP: To get only the most recent task count and time metrics without
 running count intervals, run:  <code>count-tasks --c 0</code></p>

<h2 id="GcountTasks-standalones">Stand-alone versions: GcountTasks (no Python installation needed)</h2>
<p>Note that these stand-alone programs will only run with the boinccmd binary in its default install location. If you launch a GcountTasks stand-alone and get an error message, you can still run gcount-tasks from the command line once you set up a valid boinccmd path in the countCFG.txt configuration file.</p>
<h4 id="gcount_tasks-exe-windows">GcountTasks.exe - Windows</h4>
<p>A <strong>Windows</strong> standalone of gcount-tasks is available. Download and extract the GitHub distribution package as outlined above. Inside the <code>CountBOINCtasks-main/Standalone_distributables</code> folder is <code>GcountTasks_win.zip</code>. Alternatively, this compressed file can be downloaded directly from  <a href="https://github.com/csecht/CountBOINCtasks/blob/main/Standalone_distributables/GcountTasks_win.zip">https://github.com/csecht/CountBOINCtasks/blob/main/Standalone_distributables/GcountTasks_win.zip</a>. Select &#39;Extract All&#39; for the downloaded ZIP file. After extraction, the .exe extension may not show, depending on your system view settings. Double-click <code>GcountTasks.exe</code> to launch. Because this project is in the beta phase, along with the program GUI, a Command Prompt window will appear to display possible Python error messages. Closing the Command Prompt window will also close the GUI.</p>
<p>You will likely first need to permit Windows to run the .exe file: from the pop-up warning, click on &quot;more info&quot;, then follow the prompts to open the program. </p>
<p>The <code>GcountTasks.exe</code> executable was created with PyInstaller, available from <a href="https://pypi.org/project/pyinstaller/">https://pypi.org/project/pyinstaller/</a></p>
<h4 id="GcountTasks-linux">GcountTasks - Linux</h4>
<p>A <strong>Linux</strong> standalone of gcount-tasks python script is available.  Download and extract the GitHub distribution package as outlined above. Inside CountBOINCtasks-main/Standalone_distributables folder is <code>gcount-tasks_linux.zip</code>. Alternatively, the archived program can be downloaded directly from <a href="https://github.com/csecht/CountBOINCtasks/blob/main/Standalone_distributables/gcount-tasks_linux.zip">https://github.com/csecht/CountBOINCtasks/blob/main/Standalone_distributables/gcount-tasks_linux.zip</a> . Extract the archive and move the gcount-tasks executable file to a convenient location; double-click to launch. You may need to change its permissions to allow it to launch.</p>
<p>The <code>gcount-task</code> single file executable was created with PyInstaller available from <a href="https://pypi.org/project/pyinstaller/">https://pypi.org/project/pyinstaller/</a></p>
<h4 id="gcounttasks-app-macos">GcountTasks.app - MacOS</h4>
<p>A <strong>MacOS</strong> standalone of gcount-tasks is available. Download and extract the GitHub distribution package as outlined above. Inside CountBOINCtasks-main/Standalone_distributables folder is <code>GcountTasks_mac.dmg</code>. Mount that disk image and move the GcountTasks.app to your Applications folder or where ever you like. Alternatively, the distributable app can be downloaded directly from <a href="https://github.com/csecht/CountBOINCtasks/blob/main/Standalone_distributables/GcountTasks_mac.dmg">https://github.com/csecht/CountBOINCtasks/blob/main/Standalone_distributables/GcountTasks_mac.dmg</a>.</p>
<p>The first time you try to open the app, however, you will get a message saying it can&#39;t be opened. Click &quot;Cancel&quot;, go into System Preferences &gt; Security &amp; Privacy, click the &quot;Open anyway&quot; button, then &quot;Open&quot;. It does not open initially because it was not downloaded from the Apple Store or from a recognized Apple developer. </p>
<p>The process of opening apps from unrecognized Apple developers can be somewhat streamlined by re-establishing (as of MacOS Sierra) the &quot;Allow apps downloaded from: Anywhere&quot; option in Security &amp; Preferences. Do this with the following command line in the Terminal: <code>sudo spctl --main-disable</code>. Using the Finder &#39;Open&#39; command directly on the unzipped app in its folder, can also somewhat reduce the hassle of navigating through System Preferences; once that is done, then any alias to the app should work smoothly. With any of these &quot;fixes&quot;, you will, initially and appropriately, be prompted by the MacOS Gatekeeper to open the app. </p>
<p>The <code>GcountTasks.app</code> application was created with PyInstaller, available from <a href="https://pypi.org/project/pyinstaller/">https://pypi.org/project/pyinstaller/</a></p>
<h3 id="development-plans">Development Plans</h3>
<ul>
<li>Wait for user feedback...</li>
</ul>
<h3 id="known-issues">Known Issues</h3>
<ul>
<li><p> Waiting for user feedback...</p>
</li>
</ul>
</html>