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.

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

Plug 'gaborvecsei/usage-tracker.nvim'

require('usage-tracker').setup({
    keep_eventlog_days = 14,
    cleanup_freq_days = 7,
    event_wait_period_in_sec = 5,
    inactivity_threshold_in_min = 5,
    inactivity_check_freq_in_sec = 5,
    verbose = 0,
    telemetry_endpoint = "" -- you'll need to start the restapi for this feature
})

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

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.

• UsageTrackerShowAgg <aggregation_type> [start_date] [end_date]
  • aggregation_type can be filepath, project, filetype
  • start_date and end_date is in format YYYY-MM-DD, range for the aggregation
• UsageTrackerShowFilesLifetime
• UsageTrackerShowVisitLog [filepath]
  • If no filepath is defined then all the logs are visible
• UsageTrackerShowDailyAggregation
• UsageTrackerShowDailyAggregationByFiletypes [filetypes]
  • E.g.: :UsageTrackerShowDailyAggregationByFiletypes lua markdown jsx
• UsageTrackerShowDailyAggregationByProject [project_name]
• :UsageTrackerRemoveEntry <filepath> <entry timestamp> <exit timestamp>
  • This is a utility function with which you can remove a wrongly logged item from the json
• :UsageTrackerClenup <threshold_in_min>

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.

$ 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>"}).

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 event_wait_period_in_sec 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 usage_data.json in the neovim config folder (vim.fn.stdpath("config") .. "/usage_data.json")

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)

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 DELETE FROM visits WHERE filepath = 'your_file_path' AND entry = your_entry_time AND exit = your_exit_time;