Usage-Tracker.nvim

The plugin is in ⚠️ active development, and you can expect breaking changes in the future.

Also the code is kind of 💩, refactoring is required.

NeoVim plugin with which you can track your usage. The examples speak for themselves. Logs are stored locally, so no sensitive data leaves your machine.

Install

Use your favourite package installer, there are no parameters at the moment. For example:

Plug 'gaborvecsei/usage-tracker.nvim'

Setup

require('usage-tracker').setup({
    keepeventlogdays = 14,
    cleanupfreqdays = 7,
    eventwaitperiodinsec = 5,
    inactivitythresholdin_min = 5,
    inactivitycheckfreqinsec = 5,
    verbose = 0,
    telemetry_endpoint = "" -- you'll need to start the restapi for this feature
})

| Variable | Description | Type | Default | | ------------------------------ | --------------------------------------------------------------------------------- | ---- | ------- | | keepeventlogdays | How much days of data should we keep in the event log after a cleanup | int | 14 | | cleanupfreqdays | Frequency of the cleanup job for the event logs | int | 7 | | eventwaitperiodinsec | Event logs are only recorded if this much seconds are elapsed while in the buffer | int | 5 | | inactivitythresholdin_min | If the cursor is not moving for this much time, the timer will be stopped | int | 5 | | inactivitycheckfreqinsec | How frequently check for inactivity | int | 1 | | verbose | Debug messages are printed if it's >0 | int | 1 | | telemetry_endpoint | If defined data will be stored in a sqlite db via the restapi | str | '' |

(The variables are in the global space with the prefix usagetracker_)

Usage

A timer starts when you enter a buffer and stops when you leave the buffer (or quit nvim). Both normal and insert mode is counted.

There is inactivity detection, which means that if you don't have any keys pressed down (normal, insert mode) then the timer is stopped automatically. Please see the configuration to set your personal preference.

Commands

• UsageTrackerShowAgg <aggregationtype> [startdate] [end_date]

• UsageTrackerShowFilesLifetime
• UsageTrackerShowVisitLog [filepath]

• UsageTrackerShowDailyAggregation
• UsageTrackerShowDailyAggregationByFiletypes [filetypes]

• UsageTrackerShowDailyAggregationByProject [project_name]
• :UsageTrackerRemoveEntry <filepath> <entry timestamp> <exit timestamp>

• :UsageTrackerClenup <thresholdinmin>

Telemetry (separately storing data in a DB)

Usage data saved locally (in the json file) is cleaned up after the set days, but if you'd like to keep it longer in a separate SqliteDB, then this is why this feature exists.

You can use it for custom analysis, just make sure the endpoint is live.

How to enable it

$ git clone https://github.com/gaborvecsei/usage-tracker.nvim.git
$ cd usage-tracker.nvim/telemetry_api
$ docker-compose up -d

If you'd like to use a different volume mount then change it in the docker-compose.yml file

Then you should define the telemetry_endpoint="http://<HOST>:<PORT>" (if you did not changed a thing the endpoint is http://localhost:8000) parameter in the setup({..., telemetry_endpoint="http://<HOST>:<PORT>"}).

Examples

Use :UsageTrackerShowAgg filetype 2023-07-07 2023-07-08

Total usage in minutes from 2023-07-07 00:00 to 2023-07-08 00:00

python          | ############################################################ | 155.33
lua             | ##################################################### | 138.9
html            | ####### | 20.35
markdown        | ###### | 16.01
vim             | # | 4.01
javascriptreact |  | 0.15

You can view the file-specific stats with :UsageTrackerShowFilesLifetime.

Filepath                                             Keystrokes  Time (min)  Project
---------------------------------------------------  ----------  ----------  ------------------
/work/usage-tracker.nvim/lua/usage-tracker/init.lua  9876        69.61       usage-tracker.nvim
/work/usage-tracker.nvim/README.md                   3146        12.35       usage-tracker.nvim
/.config/nvim/init.vim                               200         1.56

You can view the file-specific event (entry, exit) with :UsageTrackerShowVisitLog [filepath]. Call the function when you are at the file you are interested in without any arguments or you can provide the filename as an argument. An event pair is only saved when more time elapsed than eventwaitperiodinsec seconds between the entry and the exit. Here is an example output:

Enter                Exit                 Time (min)
-------------------  -------------------  ----------
2023-06-27 13:47:27  Present
2023-06-27 13:47:13  2023-06-27 13:47:17  0.06
2023-06-27 13:44:48  2023-06-27 13:47:05  2.28

Use :UsageTrackerShowDailyAggregationByFiletypes lua python markdown to get daily usage stats

Daily usage in minutes

2023-07-03 | ######################################## | 166.05
2023-07-04 | ###################### | 94.16
2023-07-05 | ################################################################################ | 333.1

The data is stored in a json file called usagedata.json in the neovim config folder (vim.fn.stdpath("config") .. "/usagedata.json")

Troubleshooting

Know issues

These are some of the issues I found when using the plugin. Bughunters are always welcome to check on these. 🤗

• Local data does not match up with the telemetry DB 100%
• Some items in the visit logs are not "closed" - there is no exit time
• For some visit logs the elapsed time is just too big (you can't code 25 hours in a day)

Issues & Solutions

Wrongly logged visit entry

If you find a wrongly logged entry then you'll need to remove it from the json file and from the sqlite db (if you've enabled telemetry)

• Use the UsageTrackerRemoveEntry <filepath> <entry> <exit> utility command to remove the item form the json file
• As a 2nd step remove it from the sqlite DB with