uManage

uManage is a time-monitoring application to operate under the X Window System. If you're looking for something similar to Windows, I managed to turn up my prototype for this idea Track Time, which might be of interest.

Maybe I didn't look hard enough, but every time I try to monitor my computer usage, the best the software seems to be able to do is ask me every few minutes. The problems with this are many, but the biggies:

• You just broke my train of thought.
• You're making me do clerical work that a computer can do better.
• If I really wanted to write down what I was doing, I don't need special software for that.
• You're not catching windows I only have open for a couple of minutes.

In other words, I would rather the computer do the work for me, rather than having me do the work for the computer. So, uManage is a simple application to do the tedious monitoring for you.

Two Builds

Two versions of uManage are built with this package.

• uManage is purely a command-line program.

• uManageUi uses the same code and operation described, but adds an application notification ("system tray icon") menu to configure options and exit the program.

Usage

Run uManage from the command line (for now) as follows:

uManage [-a airport] [-b database] [-d loop_delay] [-f log_file] [-i idle_threshold] [-j jiggle_delay] [-n] [-s] [-t time_format] [-w on/off] [-x distance]

The options are:

• -a/--airport code: The ICAO airport code from which to pull weather data.

• -b/--database database: Name of an SQLite3 database file, which uManage will create, if it doesn't already exist. Note that uManage will automatically set the time format (see -t, below) to %Y-%m-%dT%T (ISO 8601, which is required for SQLite's date and time functions) and block attempts to change the format. Items in the CSV will also be quoted (including the entire date, regardless of format) for compatibility with the database.

• -d/--delay delay: Delay (in seconds) between looks at the current window. The default and minimum are both one second (1s).

• -f/--filename filename: The name of the file to log timing information. If no file is specified, the program directs output to stdout. If --no-output is set, then it overrides writing to both stdout and the specified file.

• -i/--idle idle: Time (in seconds) before idle time counts as idle, to limit racking up "idle" time looking away from the screen. The default is three minutes (180s).

• -j/--jiggle delay: Time (in seconds) between automatic mouse movements, if active. The default is one minute (60s). The option has no effect in the non-GUI version of uManage.

• -n/--no-output: Block console/file output.

• -s/--save: Save current configuration options to the configuration file. Warning: This option will overwrite the existing options.

• -t/--time-format format: Time and date format for log entries. Passed through directly to strftime(); quote if necessary. If --database is used, an ISO 8601 format overrides this selection, for compatibility with SQLite.

• -w/--weather on/off: Turn weather data acquisition on and off at the beginnings of months. Default is on.

• -x/--jiggle-distance distance: Distance to move the mouse pointer when the Jiggle Mouse feature is active.

uManageUi can be invoked the same way. However, there is potential to also run it without the command-line, provided the output is logged to a file, since the options can be configured and the user can exit graphically.

Alternate Configuration

You can also set options with a configuration file in your home directory. At this time, there are equivalent options to the above, divided into two categories.

For obvious reasons, there is no equivalent to -s. However, there is the menu configuration here that isn't available otherwise.

The following is an example ~/.uManage file with all available options set:

[File]
log=/home/you/logs/useractivity.csv
database=/home/you/logs/useractivity.db
notext=1

[Timing]
idle=240
poll=2
format=%c
jiggle=23

[User]
airport=KIAD

[Menu]
Cooking=
Morning Exercise=

The aforementioned defaults are still in effect if they are not replaced by the file, and command-line options override the file's options.

Also, as suggested earlier, uManageUi can also change the configuration with a graphical interface.

Note that log is unused if notext is set.

GUI Features

In addition to easier configuration and exit, uManageUi also provides the following:

• About uManage...: Shows information on licensing and sources.

• Show Options...: Provides a simple graphical interface to change the program's configuration options.

• Quit: Terminates uManage on the next polling cycle.

There are also two features that log information.

• Pause: Suspends data collection while active.

• Jiggle Mouse: Moves the mouse back and forth regularly, 25 pixels diagonally, to simulate input activity, thereby avoiding system time-outs. (Use with care, if the jiggle period is low, since turning it off becomes challenging.)

Both log their durations to tables in the database, only if available, the pauses and keepalives tables, respectively. They each log the starting and ending time of use.

User Defined

Through the use of the configuration file, uManageUi also tracks the duration of any user-defined activities.

You can define each activity in the .uManage file, with a [Menu] section, followed by each desired item followed by an equal sign (=). For example, the following might handle major daily activities, though I don't know many people with the discipline to fill it all in.

[Menu]
Wash Up=
Exercise=
Eat=
Commute=
Work=
Watch Television=
Go Out=

Notice that the items may be any string (that doesn't have an equal sign in it), including spaces. Those titles (spaces included) become the reason listed in the log, as described below.

Failing to terminate with the equal sign causes the Glib key-file parser some sort of indigestive problem. At best, it skips the name. At worst, it may crash. A this time, no value is read for the key, though future expansion may provide a use.

The menu items can also be configured (though its operation strikes me a suspicious at the moment) through the options screen. The User-Defined Pauses field of the Preferences window is a straightforwardly comma-delimited. So, the above example would appear as:

Wash Up,Exercise,Eat,Commute,Work,Watch Television,Go Out

Currently, the "parsing" code is extremely literal-minded. If there are any extra spaces or commas in this listing, they will appear in the configuration file as extra spacing and empty menu items.

Please also note that changes here will not be reflected in the menu until uManageUi is restarted.

For the moment, all such activities are logged to the pauses table, even though they don't pause operations.

Output

uManage generates data as comma-separated values (CSV), by default formatted as:

YYYY,MM,DD,HH,MM,SS,Window ID,Window Title,Time Used,Time Idle

Breaking that down, we have:

• YYYY: A four digit year, as in 2014. Zero-padded, if for some reason you're using this in AD999 or earlier.

• MM: A two digit month, as in 05.

• DD: A two digit day of the month, as in 08.

• HH: A two digit hour of the day, on a twenty-four hour clock, 00-23.

• MM: A two digit minute of the hour, 00-59.

• SS: A two digit second of the minute, 00-59.

• Window ID: An eight digit hexadecimal value representing the window that currently has focus, such as 0520008D.

• Window Title: Title of the window that currently has focus, such as *README.md (~/Documents/code/uManage.c) - gedit.

• Time Used: Time (in seconds) that the current window has been in use.

• Time Idle: Time (in seconds) that the current window has been open but idle.

If, however, the time format is changed through configuration, that format replaces the first six fields.

Database

uManage will also log to an SQLite database (see the -b command-line option and the [File]/database configuration described above), which has similar fields except for the date, which is a single field by default in C's %Y-%m-%dT%T format (based on %c, which appears to be incompatible with SQLite, itself).

The table for this data is named activity, and has the following fields:

• start, a text field. Again, in %Y-%m-%dT%T format unless configured to do something different in the graphical options interface.

• window, the Window ID, also text. Technically, since it's an eight-digit hexadecimal number, it could obviously be an integer, but it's doubtful that anybody could rationally use it as a number.

• title, obviously text, storing the Window Title.

• used, the Time Used, as an integer, in seconds.

• idle, the Time Idle, as an integer, in seconds.

The difference in date format, of course, reflects SQLite's Date and Time API.

As near as feasible to the new month, if the database is being used, uManage will also download the previous month's worth of weather data from The Weather Underground through their API.

The resulting weather table is as follows.

• date, a text field, the day's date, in the equivalent of %Y-%m-%d format.

• maxTemp, an integer field, the day's high temperature.

• meanTemp, an integer field, the day's average temperature.

• minTemp, an integer field, the day's low temperature.

• maxDew, an integer field, the day's high dewpoint temperature.

• meanDew, an integer field, the day's average dewpoint temperature.

• minDew, an integer field, the day's low dewpoint temperature.

• maxHumid, an integer field, the day's high relative humidity, as a percentage.

• meanHumid, an integer field, the day's average relative humidity, as a percentage.

• minHumid, an integer field, the day's low relative humidity, as a percentage.

• maxPressure, a real field, the day's high pressure reading.

• meanPressure, a real field, the day's average pressure reading.

• minPressure, a real field, the day's low pressure reading.

• maxVisibility, an integer field, the day's maximum distance visible.

• meanVisibility, an integer field, the day's average distance visible.

• minVisibility, an integer field, the day's minimum distance visible.

• maxWind, an integer field, the day's maximum sustained wind speed.

• meanWind, an integer field, the day's average sustained wind speed.

• maxGust, an integer field, the maximum gusting wind speed for the day.

• precipitation, a real field, the day's total precipitation.

• clouds, an integer field, a percentage of cloud coverage for the day.

• events, a text field, a rough description of the day's weather, if anything of interest occurred.

• windDirection, an integer field, degrees from north.

All units (when I try it) are Imperial, temperatures in degrees Fahrenheit, distances in miles, speeds in miles per hour, heights in inches, pressures in inches of mercury. That works out fine for me. Anybody else should hope that different airport codes trigger different units or live with it and convert.

As mentioned, there are two other tables.

The use of the Pause Recording feature is recorded in the pauses table, with the following fields. Again, all date strings are in %Y-%m-%dT%T format unless configured to do something different in the graphical options interface.

• start, a text field representing when the user turned the feature on.

• end, a text field representing when the user deactivated the feature.

• reason, another text field showing what the duration represents. Pauses are marked Pause, while any user-defined options will show under their own titles.

The use of the Jiggle Mouse feature, likewise, is recorded in the keepalives table, with fields mostly similar to the pauses table:

• start, a text field representing when the user turned the feature on.

• end, a text field representing when the user deactivated the feature.

Given that the features are not available without the user interface, no data will be logged to pauses or keepalives using uManage rather than uManageUi.

Notes

The time and date has been split up under the philosophy that it is easier to reassemble than to break apart later.

The Window ID has been included to make it easier to group similar activities (browser tabs, multiple files being edited, etc.) for processing. However, uManage issues a message based on every change in Window Title so that the activity can be separated along critically-different uses (reading versus writing, which web site in the browser, etc.).

The Time Used for each window represents active usage (user input has occurred). It does not include idle time, so that a window that is merely open does not accumulate time.

I should also note that umenu.glade is not a Glade-produced file. Or, rather, it was, but since Glade doesn't appear to support GtkMenus, and certainly not as top-level objects, I did some hand-editing to make it fly. So, don't go loading it up to make changes, or at least don't be surprised if you're attacked by monsters when you do.

Name

Think of uManage as "micro-manage"---the 'u' is close enough to a Greek mu/μ---which is either a pun or accurate, depending on how you use it.

Or think of it as "You Manage," since you can, indeed, do that.

Or I'm running on Ubuntu, and I assume that my eventual goals for a GUI will end up integrating with or at least touching on Unity, somehow. So, maybe it's an abbreviation for it. Probably not, though.

Sources and Requirements

The icon for the application notification menu is adapted from Clock by Olyn LeRoy from The Noun Project, used under a Creative Commons Attribution 3.0 license.

Since idle time is important, we'll need XCB, the X protocol C-language Binding, especially its screensaver libraries.

sudo apt-get install libxcb-screensaver0-dev

We'll also need to know what window we're looking at, and xdotool, or rather its library form, will also be useful.

sudo apt-get install libxdo-dev

Glib provides its key-value file parser to manage the configuration file.

sudo apt-get install libglib2.0-dev

Database support is SQLite.

sudo apt-get install libsqlite3-dev

The graphical interface is handled with GTK+.

sudo apt-get install libgtk-3-dev

The application menu also uses the Application Indicator library.

sudo apt-get install libappindicator-dev

More to come as the application advances, but this should be a good start.

The Future

Some possible options that may eventually be in the works come largely from scripts I already use to monitor certain activity.

• User-defined start/stop states. (Configurable in .uManage)

• Trigger actions when state changes, for example opening a web page or start an application after a long time idle or paused.

• Download and log/insert supplemental data such as weather. (Uses quasi-CSV data from Weather Underground)

• Create installable package.

• Show program state through application icon, especially Pause.

• Allow filing notes from indicator menu. (Possible with GTK+?)

• Report on log entries. (Separate application?) _(Project begun in R on GitHub)