actlog

ActLog

ActLog is an activity log that shows you what you did when. It logs when you were active on your desktop and takes periodic screenshots so you later can see what you did.

This helps with mental health (I did actually do something!) and with e.g. filling out time sheets.

It runs under Xorg. It does not (yet?) run under Windows, Mac or under Wayland.

Screenshots

Features

• Track active time using an "active detector". Use the defaults or roll your own.
• Periodically store sceenshots so you can see what you did when.
  • They can be pruned/expired so we don't use massive disk space.
• A web interface and CLI for seeing your activity.
• Open Source MIT license.

User documentation

Quick version: Installation and running from PyPI:

First you'll need to install some prerequisites. We need these Debian/Ubuntu packages:

sudo apt install scrot imagemagick pngquant xprintidle

Either scrot or imagemagick are needed to create screenshots. imagemagick and pngquant are optional and reduce screenshot size. xprintidle is only required if you're not running under a new GNOME.

For other distros, you may need to modify the package names. (Weirdly, there is no xprintidle package for Fedora, but it can be compiled manually.)

$ python3 -m venv /path/to/my/virtual/environment
$ /path/to/my/virtual/environment/bin/pip install actlog
# This starts the monitor (that stores logs and creates screenshots)
# and the web server.
$ /path/to/my/virtual/environment/bin/actlog daemon

Now wait 15-20 minutes while you're using your computer and then open your browser at http://localhost:1248 to see some activity.

Instead of using the web interface, you can also use the cli:

$ /path/to/my/virtual/environment/bin/actlog log --help
# This will show you a log of your activity from last Thursday
$ /path/to/my/virtual/environment/bin/actlog log --from "last Thursday"

$ /path/to/my/virtual/environment/bin/actlog view --help
# This will show screenshots from yesterday and today
# in `eog`, GNOME's image viewer
$ /path/to/my/virtual/environment/bin/actlog view --viewer eog

Starting with systemd

• Stop any running actlog instance.
• Copy actlog.service to ~/.config/systemd/user/actlog.service and modify the ExecStart path to be /path/to/my/virtual/environment/bin/actlog daemon.
• systemctl --user daemon-reload
• systemctl --user enable actlog
• systemctl --user start actlog

And to check it is running:

• systemctl --user status actlog

Config file

Actlog uses a config file: ~/.actlog/config.yaml or you can specify one with actlog --config-file FILE. It lets you set all the same options as you see with --help. E.g.:

global:
  storage: /my/custom/actlog-storage
view:
  viewer: eog

will set the global --storage option and the --viewer option for the view subcommand. See actlog --help and help for the subcommands, e.g. actlog view --help.

Future enhancements

• Top Priority: Password protection of Web UI - Otherwise screenshots are available to all on http://localhost:1250.
  • scrypt password generation, checking, editing
  • sessions and gunicorn
  • https://pypi.org/project/python-pam/
• Reducing the number of external/non-python dependencies, to make it easier to install.
  dbus-python on fedora: sudo dnf install @development-tools dbus-devel cmake glib2-devel python3-devel
• Visualize everything on a timeline - vis.js - A dynamic, browser based visualization library.
• Also store title of active window
  • and title/url of current browser tab e.g. re-using ActivityWatch browser plugin?
• Use screenshot metadata for more features?
• Support more desktop environments than Debian/Ubuntu GNOME.
• Wayland support: Tricky since there is no API for taking screenshots without the desktop blinking, but it appears to be possible in principle at least.
• Somehow pin python dependencies, (like would be done with package-lock.json with npm). As a start, the dependencies that we know work are stored in requirements-that-work.txt, created with pip-compile in Makefile. But if I manually downgrade a package, pip-compile still shows the newest package, not the one actually installed, so I don't really trust it.

Related projects

• Similar ideas ActivityWatch - Open-source time tracker
  • Getting started
• GitHub - selfspy/selfspy: Log everything you do on the computer, for statistics, future reference and all-around fun!
• GitHub - karpathy/ulogme: Automatically collect and visualize usage statistics in Ubuntu/OSX environments.
• Relies on the user to input activity Kimai - Open Source time-tracker
• Closed source
  • RescueTime: Fully Automated Time Tracking Software
  • Time Tracker Management Tracking Software

Developer documentation

Project organization and how to run with a git checkout

The project consists of a python "backend" and a JavaScript/svelte/nodejs frontend with the web user interface (under ./frontend/).

The python backend contains the monitor and the web server. The monitor does the actual logging and creating screenshots, and the webserver serves the svelte frontend and provides APIs for it to get log and screenshot information.

The python code by default runs under the assumption that there is a venv environment under ./venv.

make will build such a venv, build both the python backend and the frontend so they're ready to use. ./dev will set up some environment variables that allow you to easily run from a non-installed directory. So:

$ make
$ ./dev actlog daemon

And then open your browser at http://localhost:1248. Allow for 15-20 minutes to see some data. Again, you can

$ ./dev actlog log --from "last Thursday"
$ ./dev actlog view --viewer eog

Running developer versions of monitor and webserver(s)

By default actlog daemon runs the montior and a production webserver (under gunicorn). Using this setup, if you change any code in either the frontend or backend, you need to stop the daemon, perhaps rebuild the frontend and then restart the daemon.

Thankfully there are better ways.

Start the monitor separately from everything else with:

$ ./dev actlog daemon --monitor-start-only

Now start the python webserver in a development version with hot reloading so code changes are visible immediately:

$ ./dev actlog daemon --dev-web-server-start-only

This still serves a built version of the frontend. If you want to modify the frontend as well, run the development frontend webserver with frontend hot reloading:

$ cd frontend
$ npm run dev

Now use the web user interface at http://localhost:5173/ (notice the different port number).

This only works with the dev web server (--dev-web-server-start-only), since it also disables CORS, a requirement for the npm run dev web server to access the backend API.

(I use tmux for keeping these three running so I don't need three terminals, but that is up to you.)

Data: SQL and screenshots files

$ sqlite3 ~/.actlog/storage/actlog.db '.tables'
activity_log

$ sqlite3 ~/.actlog/storage/actlog.db '.schema activity_log'
CREATE TABLE activity_log (
    time REAL,
    activity TEXT,
    details TEXT
);

$ cat select.sql
SELECT
  id,
  DATETIME(time, 'unixepoch', 'localtime') as t,
  time,
  activity,
  details
FROM activity_log
LIMIT 2

$ sqlite3 ~/.actlog/storage/actlog.db < select.sql
2023-10-01 07:47:51|1696160871.11847|startup|{"pid": 279556}
2023-10-01 07:47:51|1696160871.12261|active|

$ ls -1 ~/.actlog/storage/screenshots | head -n 4
2023-10-05_10:00:19+0200.png
2023-10-05_10:15:22+0200.png
2023-10-05_10:30:24+0200.png
2023-10-05_10:45:28+0200.png

Extension points

screenshot_metadata.py

Here is a sample ~/.actlog/screenshot_metadata.py that checks to see if there is a window running with a secret title, and if so, creates screenshot metadata {"secret": true}.

import subprocess

def metadata():
    result = subprocess.run("wmctrl -l | grep -q 'Secret Window Title'", shell=True);
    if result.returncode == 0:
        return {
            "secret": True
        }
    else:
        return {}

Activity detection

Detecting user activity an be done in multiple ways. Whether the screensaver is active is one reliable signal, but xprintidle is another.

By default, we first see if we can detect the screensaver status. This is currently done for Gnome (tested on Gnome 43.6). But you can also add your own activity detector. See help for the --active-detector option for the daemon subcommand, and see an example in examples/detect_active.py. Bug reports and PRs for other (tested) detection mechanisms, or even just testing for other desktop environments are welcome. This discussion could be a starting point.

So first we try to see if the user has a custom active detector, if not we try to detect the GNOME screensaver, and fallback to using xprintidle and declare inactivity after --inactivity-time minutes (default: 5) of inactivity.

Releasing

• Bump version:
  vi pyproject.toml frontend/package.json frontend/package-lock.json
• Commit everything
• make package
• Upload to testpypi:
  ./venv/bin/python3 -m twine upload --repository testpypi dist/*
  • Username: __token__
  • Password: pypi-.* (for testpypi token)
• Test install

  rm -rf /tmp/venv-test && python3 -m venv /tmp/venv-test
  /tmp/venv-test/bin/pip install -r $w/actlog/requirements-that-work.txt
  /tmp/venv-test/bin/pip install --index-url https://test.pypi.org/simple/ --no-deps actlog
  

• git tag $version
• git push --tags origin main
• Upload to pypi:
  ./venv/bin/python3 -m twine upload dist/*
  • Username: __token__
  • Password: pypi-.* (for pypi token)
• Test install

  rm -rf /tmp/venv-test && python3 -m venv /tmp/venv-test
  /tmp/venv-test/bin/pip install actlog
  

TODO

• Use logger instead of print()
• Try running this on Windows
• Try Wayland with hacked gnome-screenshot