actlog 0.0.4

Description:

actlog 0.0.4

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