diff --git a/arbtt.cabal b/arbtt.cabal --- a/arbtt.cabal +++ b/arbtt.cabal @@ -1,5 +1,5 @@ name: arbtt -version: 0.4.1 +version: 0.4.2 license: GPL license-file: LICENSE category: Desktop @@ -22,7 +22,8 @@ extra-source-files: - categorize.cfg, arbtt-capture.desktop, README + categorize.cfg, arbtt-capture.desktop, README, + doc/arbtt.xml, doc/fptools.css, doc/Makefile executable arbtt-capture main-is: capture-main.hs @@ -53,6 +54,16 @@ executable arbtt-dump main-is: dump-main.hs + hs-source-dirs: src + build-depends: + base == 4.*, parsec == 2.*, containers + other-modules: + Data + TimeLog + System.Locale.SetLocale + +executable arbtt-recover + main-is: recover-main.hs hs-source-dirs: src build-depends: base == 4.*, parsec == 2.*, containers diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,33 @@ +all: html man + +XSLTPROC=xsltproc +XSLTPROC_HTML_OUTDIR=users_guide/ +XSLTPROC_HTML_CSS=fptools.css +XSLTPROC_HTML_PARAMS=\ + --stringparam use.id.as.filename 1 \ + --stringparam base.dir $(XSLTPROC_HTML_OUTDIR) \ + --stringparam html.stylesheet $(XSLTPROC_HTML_CSS) +XSLTPROC_HTML_STYLESHEET=/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/profile-chunk.xsl +XSLTPROC_MAN_STYLESHEET=/usr/share/xml/docbook/stylesheet/nwalsh/manpages/profile-docbook.xsl +XSLTPROC_MAN_OUTDIR=man/ +XSLTPROC_MAN_OPTIONS=--stringparam man.output.in.separate.dir 1 --stringparam man.output.base.dir + +# build targets +# +.PHONY: man html pdf +man: + $(XSLTPROC) --xinclude --stringparam profile.condition man $(XSLTPROC_MAN_OPTIONS) $(XSLTPROC_MAN_OUTDIR) $(XSLTPROC_MAN_STYLESHEET) arbtt.xml + +html: + $(XSLTPROC) --xinclude --stringparam profile.condition html $(XSLTPROC_HTML_PARAMS) $(XSLTPROC_HTML_STYLESHEET) arbtt.xml + cp $(XSLTPROC_HTML_CSS) $(XSLTPROC_HTML_OUTDIR) + +pdf: + #dblatex -tpdf arbtt.xml + fop -xml arbtt.xml -xsl /usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl -pdf arbtt.pdf + +# auxiliary targets +# +.PHONY: clean +clean: + -rm -rf users_guide/ man/ arbtt.pdf diff --git a/doc/arbtt.xml b/doc/arbtt.xml new file mode 100644 --- /dev/null +++ b/doc/arbtt.xml @@ -0,0 +1,948 @@ + + + +
+ + arbtt – The Automatic Rule-Base Time Tracker + + + Joachim + Breitner + mail@joachim-breitner.de + Main author of arbtt + + + October 2009 + + + + arbtt is a background daemon that stores which windows are open, which one + has the focus and how long since your last action (and possibly more sources + later), and stores this. It is also a program that will, based on + expressive rules you specify, derive what you were doing, and what for. + + + The log file might contain very sensitive private data. Make sure + you understand the consequences of a full-time logger and be careful with this + data. + + + + Installation + + Building with <command>cabal-install</command> + + arbtt comes in the form of a CabalizedCabal is the common software + packaging for Haskell programs and libraries, see . package, and is + available from hackage. The easiest way of obtaining and installing arbtt is + via cabal-install. If you have + cabal-install available, just run + $ cabal install arbtt + to download, build and install arbtt. + + + + + Building without <command>cabal-install</command> + + You can fetch the latest arbtt source tarball from hackage, at + . Extract the tarball + and run the following commands to build and install the arbtt binaries: + $ runhaskell Setup.hs configure +$ runhaskell Setup.hs build +$ runhaskell Setup.hs install + + + + + Setting up the capture program + + To have arbtt gather useful data, you need to make sure that + arbtt-capture is started with your X session. If you use + GNOME or KDE, you can copy the file + arbtt-capture.desktop to + ~/.config/autostart/. You might need to put the full + path to arbtt-capture in the Exec line there, if you did + not do a system wide installation. + + + By default, arbtt-capture will save one data sample per + minute. If you want to change that, you can pass to arbtt-capture, where + RATE specifies the sample rate in seconds. + + + + + Building the documentation + + Obviously, you can already read the documentation. If you still want to + build it yourself, enter the directory doc/ and run + make for the documentation in HTML and PDF format. + + + + + + Development version + + If you want to try the latest unreleased state of the code, or want to + contribute to arbtt, you can fetch the code with + darcs get + + + + + + + Configuring the arbtt categorizer + + Once arbtt-capture is running, it will start recording, without further + configuration. The configuration is only needed to do an analysis of the + recorded data. Thus, if you improve your categorization later, it will apply + even to previous data samples! + + + + The configuration file needs to be placed in + ~/.arbtt/categorize.cfg. An + example file is included in the source distribution, and reproduced here as + , which should be more enlightening than this rather + formal description. + + + + A complete <filename>categorize.cfg</filename> + + + + + The syntax + + The file categorize.cfg is a plain text file. + Whitespace is insignificant and Haskell-style comments are allowed. A formal + grammar is provided in . + + +
+ The formal grammar of <filename>categorize.cfg</filename> + + + Rules + + [ ] + ( (, + )* | ( ; + )* ) + + + + + AliasSpec + aliases ( (, )* + ) + + + + Alias + Literal -> Literal + + + + Rule + { + } + + + ==> + | if + then + else + + + + tag + + + + + Cond + ( + ) + + ! | + && + | + || + + $ + == String | + $ + /= String + + $ + =~ + $ + Number + + $ + + + $ + + current window + any window + + + + Tag + [ Literal : ] Literal + + + + RegEx + / Literal / | + m c Literal + cWhere + c can be any + character. + + + + CmpOp + <= | < | == + | > | >= + + + + StringVariable + title | program + + + + NumericVariable + idle + + + + BooleanVariable + active + + + + TimeVariable + time | sampleage + + + + TimeSpecification + [ Digit ] Digit : Digit Digit + + + +
+ + A String refers to a double-quoted string of + characters, while a Literal is not quoted. + Tags may only consist of + letters, dashes and underscores, or variable interpolations. A Tag maybe + be optionally prepended with a category, separated by a colon. The + category itself follows he same lexical rules as the tag. A variable + interpolation can be one of the following: + + + $1, $2,... + will be replaced by the respective group in the last + successfully applied regular expression in the conditions enclosing the + current rule. + + + + $current.title + $current.program + will be replaced by title the currently active + window, resp. by the name of the currently active program. + If no window happens to be active, this tag will be ignored. + + + + + + + A regular expression is, like in perl, either enclosed in forward + slashes or, alternatively, in any character of your choice with an + m (for match) in front. This is handy if you need + to use regular expressions that match directory names. Otherwise, the + syntax of the regular expressions is that of perl-compatible regular + expressions. + + + + The semantics + + A data sample consists of the time of recording, the time passed since the + user’s last action and the list of windows. Per window, the following + information is available: + + the window title + the program name + whether the window was the active window + + Base on this information, the categorizer will now assign + tags to each + sample, based on the rules layed out in + categorizer.cfg. + + + + The keyword tag, usually wrapped in a condition, + assigns the tag to the sample. If the tag also contains a + category, it will only be assigned if no other tag of that + category is present. This means that for each sample and each category, + there can only be one tag of that category. Tags can contain references to + matches done of regular expressions in conditions. + + + + The variable $idle contains the idle time of the user, + measured in seconds. Usually, it is used to assign the tag + inactive, which is handled specially by + arbtt-stats, as can be seen in . + + + + While applying the conditions and rules, the categorizer has a notion of + the window in scope, and the variables + $title, $program and + $active always refer to the window in scope. At first, + no window is in scope. Only when evaluating a condition wrapped in + current window or any window, this + changes. + + + + For current window, the currently active window is in + scope. If there is no such window, the condition is false. + + + + For any window, the condition is applied to each + window, in turn, and if any of the windows matches, the result is true. If + more than one window matches it is not defined from which match the + variables $1... are take from. + + + + The variable $time refers to the time-of-day of the + sample (i.e. the time since 0:00 that day), while + $sampleage refers to the + time span from when the sample was created until now, the time of + evaluating the statistics. The latter variable is especially useful when + passed to the option of + arbtt-stats. + They can be compared with expressions of the + type "hh:mm", for example + $time >= 8:00 && $time < 12:00 ==> tag time-of-day:morning + + + + + + Program references + arbtt consists of a few command line tools, the most important one is + arbtt-stats. This overview is followed by their manual + pages. + + + + To generate statistics about the data that + arbtt-capture has gathered, use the program + arbtt-stats. A detailed description of the possible + options is given in . + + The collection of data is done by arbtt-capture. + Usually, you only set it up once to run automatically, as described in , and do not have to + worry about it again. Its command line reference is given in . + + Because the data log file is binary, a tool names + arbtt-dump can bee used to dump the data in + textual form. Its command line reference is given in . + + If arbtt-capture crashes it might be that the log + file is not readable any more. In some cases, this can be fixed using the + (relatively raw) arbtt-recover tool. Its command line + reference is given in . + + + + + + arbtt-stats + 1 + arbtt manual + + + + arbtt-stats + generate statistics from the arbtt data samples + + + + + arbtt-stats + OPTION + + + + Description + + arbtt-stats reads the samples that were recorded so far + by arbtt-capture from the log file, filters them + according to the users specifications and generates one or more reports + from the data. + + + When run without any options, is assumed. + + + The order in which filters (, + , and + ) and reports are passed to the program is + irrelevant: All filters given on the command line are active for all + reports. + + + + Options + + + + + + shows a short summary of the available + options, and exists. + + + + + shows the version number, and exists. + + + Filtering options + + + TAG + TAG + Ignore any data samples that have + been assigned this tag. Can be given more than once. + + + TAG + TAB + Ignore any data samples that have + not been assigned this tag. Can be given more than once. + + + + by default, arbtt-stats ignores + any samples which have been assigned the tag + inactive. This flag disables this behaviour. + + + CONDITION + CONDITION + Only consider samples matching + the given condition, which follows the same syntax as in + categorize.cfg (Nonterminal in + the formal grammar specification found in the user guide). + + + + Report options + + + PERCENTAGE + PERCENTAGE + + In the reports, any tag which occurs rarer than the given + percentage is ignored. The default value is 1. + + + + + Reports + + + + + + Various bits of information about the recorded data, such as total + time recorded, number of records etc. In this report, time + recorded is the sum of all + samples, including inactive and those that are disabled by the + filter, while time selected is the sum of the + samples that are matched by the given filters. + + + + + + For all tag, print the part of the selected time + with this tag applied to, both as an absolute value and a percentage + of the selected time. + + + + CATEGORY + CATEGORY + For the given category, give the textual equivalent + of a pie chart: For each possible value of the category, including + one for no tag of this category present, give the absolute time and + fraction. Entries which are not displayed because of the option + are aggregated. + + + + This is just a shortcut for a series of + options, one for each category found in + the data. + + + + + + + Examples + Some useful examples of what you can do with + arbtt-stats are provided here: + # Only consider the time when I was programming in Haskell +arbtt-stats -o Editing-Haskell + +# Tell me what evolution folders I spend my time in when I actually do +# work with e-Mail +arbtt-stats -o Program:evolution -c Evo-Folder + +# Generate statistics about the last hour +arbtt-stats -f '$sampleage < 1:00' + + + Files + + + ~/.arbtt/capture.log + binary file, storing the arbtt data samples + + + ~/.arbtt/categorize.cfg + specification of the arbtt categorizer syntax. A + detailed description is given in + + + + + See also + See the arbtt manual for more information and the arbtt hackage page for + newer versions of arbtt. + + + + + + arbtt-capture + 1 + arbtt manual + + + + arbtt-capture + collect data samples for arbtt + + + + + arbtt-capture + OPTION + + + + Description + + arbtt-capture runs continuously and saves at the given + sample rate, usually once per minute, the collected data to + ~/.arbtt/capture.log. + + + + Options + + + + + + shows a short summary of the available + options, and exists. + + + + + shows the version number, and exists. + + + RATE + RATE + set the sample rate in seconds (default: 60) + + + + Files + + + ~/.arbtt/capture.log + binary file, storing the arbtt data samples + + + + + + See also + See the arbtt manual for more information and the arbtt hackage page for + newer versions of arbtt. + + + + + + arbtt-dump + 1 + arbtt manual + + + + arbtt-dump + dumps arbtt data samples + + + + + arbtt-dump + OPTION + + + + Description + + arbtt-dump reads the data samples recorded by and writes them so the standard output in an + ascii based format. + + + + Options + + + + + + shows a short summary of the available + options, and exists. + + + + + shows the version number, and exists. + + + + + logfile to use instead of ~/.arbtt/capture.log + + + + Files + + + ~/.arbtt/capture.log + binary file, storing the arbtt data samples + + + + + See also + See the arbtt manual for more information and the arbtt hackage page for + newer versions of arbtt. + + + + + + arbtt-recover + 1 + arbtt manual + + + + arbtt-recover + tries to recover a broken arbtt data log + + + + + arbtt-recover + OPTION + + + + Description + + arbtt-recover tries to readsthe data samples recorded + by , skipping over possible broken entries. A fixed log file is written to ~/.arbtt/capture.log.recovered. + + + + Options + + + + + + shows a short summary of the available + options, and exists. + + + + + shows the version number, and exists. + + + + + logfile to use instead of ~/.arbtt/capture.log + + + + + where to save the recovered file, instead of ~/.arbtt/capture.log + + + + Files + + + ~/.arbtt/capture.log + binary file, storing the arbtt data samples + + + ~/.arbtt/capture.log.recovered + binary file, storing the fixed arbtt data samples + + + + + See also + See the arbtt manual for more information and the arbtt hackage page for + newer versions of arbtt. + + + + + + Copyright and Contact + + arbtt is Copyright © 2009 Joachim Breitner + + + + arbtt does not have a bug tracker or other project infrastructure yet. If + you have bug reports, suggestions or questions, please send an email to + mail@joachim-breitner.de. + + + + arbtt License + + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + + + + + + Release Notes + + The version history with changes relevant for the user are documented here. + + + + Version 0.4.2 + + + Implement option to + arbtt-dump. + + + New command arbtt-recover to rescue data from + a proken data log file. + + + Actually include this documentation in the released tarball. + + + + + + Version 0.4.1 + + + Write this documentation + + + Drop dependency on setlocale: Copy the SetLocale module. + + + Drop dependency on tabular: Implement custom table rendering code. + + + In the absence of _NET_CLIENT_LIST, look for application windows as children of the root windows. This should work for users of window managers like i3 without EWHM support. + + + + + + Version 0.4 + + + Implement option to + arbtt-stats + + + Eliminate one possible cause for crashes of + arbtt-capture. + + + + + + Version 0.3.0 + + + Switch to binary log file format, for greatly increased speed + + + arbtt-capture will automatically detect and + convert log files in the old format. + + + + + + Version 0.2.0 + + + Add option to + arbtt-stats + + + Add option to + arbtt-capture + + + Introduce time-base variables $time and + $sampleage + + + + + + Version 0.1.5 + + + Use setlocale to get umlauts in window titles correctly + + + + + + Version 0.1.4 + + + Be smarter when figuring out what window is active. Thanks to CJ + van den Berg for investigating the issue. + + + + + + Version 0.1.3 + + Read _NET_CLIENT_LIST for the list of + applications, for compatibility with window managers such as metacity + + + + + Version 0.1.2 + + Off-By-Ten error in the time display + Correctly show total number of records in + + + + + + Version 0.1.1 + + Rename files to allow building on MacOS. + + + + + Version 0.1 + + Initial release of arbtt + + + + +
diff --git a/doc/fptools.css b/doc/fptools.css new file mode 100644 --- /dev/null +++ b/doc/fptools.css @@ -0,0 +1,39 @@ +div { + font-family: sans-serif; + color: black; + background: white +} + +h1, h2, h3, h4, h5, h6, p.title { color: #005A9C } + +h1 { font: 170% sans-serif } +h2 { font: 140% sans-serif } +h3 { font: 120% sans-serif } +h4 { font: bold 100% sans-serif } +h5 { font: italic 100% sans-serif } +h6 { font: small-caps 100% sans-serif } + +pre { + font-family: monospace; + border-width: 1px; + border-style: solid; + padding: 0.3em +} + +pre.screen { color: #006400 } +pre.programlisting { color: maroon } + +div.example { + margin: 1ex 0em; + border: solid #412e25 1px; + padding: 0ex 0.4em +} + +div.example, div.example-contents { + background-color: #fffcf5 +} + +a:link { color: #0000C8 } +a:hover { background: #FFFFA8 } +a:active { color: #D00000 } +a:visited { color: #680098 } diff --git a/src/Data.hs b/src/Data.hs --- a/src/Data.hs +++ b/src/Data.hs @@ -89,5 +89,5 @@ put (cLastActivity cd) get = do v <- getWord8 - when (v /= 1) $ error $ "Wrong TimeLogEntry version tag " ++ show v + when (v /= 1) $ error $ "Wrong CaptureData version tag " ++ show v CaptureData <$> get <*> get diff --git a/src/TimeLog.hs b/src/TimeLog.hs --- a/src/TimeLog.hs +++ b/src/TimeLog.hs @@ -12,8 +12,11 @@ import Data.Function import Data.Char import System.Directory +import Control.Exception +import Prelude hiding (catch) import qualified Data.ByteString.Lazy as BS +import Data.Maybe magic = BS.pack $ map (fromIntegral.ord) "arbtt-timelog-v1\n" @@ -38,6 +41,41 @@ writeTimeLog :: Binary a => FilePath -> TimeLog a -> IO () writeTimeLog filename tl = do createTimeLog True filename mapM_ (appendTimeLog filename) tl + +-- | This might be very bad style, and it hogs memory, but it might help in some situations... +recoverTimeLog :: Binary a => FilePath -> IO (TimeLog a) +recoverTimeLog filename = do + content <- BS.readFile filename + start content + where start content = do + let (startString, rest, off) = runGetState (getLazyByteString (BS.length magic)) content 0 + if startString /= magic + then do putStrLn $ "WARNING: Timelog starts with unknown marker " ++ + show (map (chr.fromIntegral) (BS.unpack startString)) + else do putStrLn $ "Found header, continuing... (" ++ show (BS.length rest) ++ " bytes to go)" + go rest off + go input off = do mb <- tryGet False input off + flip (maybe (return [])) mb $ + \(v,rest,off') -> if BS.null rest + then return [v] + else (v :) <$> go rest off' + tryGet retrying input off = catch ( + do -- putStrLn $ "Trying value at offset " ++ show off + let (v,rest,off') = runGetState get input off + evaluate rest + when retrying $ + putStrLn $ "Succesfully read value at position " ++ show off + return (Just (v,rest,off')) + ) ( + \e -> do + putStrLn $ "Failed to read value at position " ++ show off ++ ":" + putStrLn $ " " ++ show (e :: SomeException) + if BS.length input <= 1 + then do putStrLn $ "End of file reached" + return Nothing + else do putStrLn $ "Trying at position " ++ show (off+1) ++ "." + tryGet True (BS.tail input) (off+1) + ) readTimeLog :: Binary a => FilePath -> IO (TimeLog a) readTimeLog filename = do diff --git a/src/dump-main.hs b/src/dump-main.hs --- a/src/dump-main.hs +++ b/src/dump-main.hs @@ -7,13 +7,15 @@ import System.IO import qualified Data.Map as M import Data.Version (showVersion) +import Data.Maybe +import Control.Monad import TimeLog import Data import Paths_arbtt (version) -data Flag = Help | Version +data Flag = Help | Version | LogFile String deriving Eq versionStr = "arbtt-dump " ++ showVersion version @@ -27,13 +29,16 @@ , Option "V" ["version"] (NoArg Version) "show the version number" + , Option "f" ["logfile"] + (ReqArg LogFile "FILE") + "use this file instead of ~/.arbtt/capture.log" ] main = do args <- getArgs - case getOpt Permute options args of - (o,[],[]) | Help `notElem` o && Version `notElem` o -> return () + flags <- case getOpt Permute options args of + (o,[],[]) | Help `notElem` o && Version `notElem` o -> return o (o,_,_) | Version `elem` o -> do hPutStrLn stderr versionStr exitSuccess @@ -46,7 +51,9 @@ dir <- getAppUserDataDirectory "arbtt" - - let captureFilename = dir "capture.log" + let captureFilename = + fromMaybe (dir "capture.log") $ listToMaybe $ + mapMaybe (\f -> case f of { LogFile f -> Just f; _ -> Nothing}) $ + flags captures <- readTimeLog captureFilename :: IO (TimeLog CaptureData) mapM_ print captures diff --git a/src/recover-main.hs b/src/recover-main.hs new file mode 100644 --- /dev/null +++ b/src/recover-main.hs @@ -0,0 +1,67 @@ +module Main where +import System.Directory +import System.FilePath +import System.Console.GetOpt +import System.Environment +import System.Exit +import System.IO +import qualified Data.Map as M +import Data.Version (showVersion) +import Data.Maybe +import Control.Monad + +import TimeLog +import Data + +import Paths_arbtt (version) + +data Flag = Help | Version | InFile String | OutFile String + deriving Eq + +versionStr = "arbtt-recover " ++ showVersion version +header = "Usage: arbtt-recover [OPTIONS...]" + +options :: [OptDescr Flag] +options = + [ Option "h?" ["help"] + (NoArg Help) + "show this help" + , Option "V" ["version"] + (NoArg Version) + "show the version number" + , Option "i" ["infile"] + (ReqArg InFile "FILE") + "read from this file instead of ~/.arbtt/capture.log" + , Option "o" ["outfile"] + (ReqArg OutFile "FILE") + "write to this file instead of ~/.arbtt/capture.log.recovered" + ] + + +main = do + args <- getArgs + flags <- case getOpt Permute options args of + (o,[],[]) | Help `notElem` o && Version `notElem` o -> return o + (o,_,_) | Version `elem` o -> do + hPutStrLn stderr versionStr + exitSuccess + (o,_,_) | Help `elem` o -> do + hPutStr stderr (usageInfo header options) + exitSuccess + (_,_,errs) -> do + hPutStr stderr (concat errs ++ usageInfo header options) + exitFailure + + dir <- getAppUserDataDirectory "arbtt" + + let captureFilename = + fromMaybe (dir "capture.log") $ listToMaybe $ + mapMaybe (\f -> case f of { InFile f -> Just f; _ -> Nothing}) $ + flags + let saveFilename = + fromMaybe (dir "capture.log.recovered") $ listToMaybe $ + mapMaybe (\f -> case f of { OutFile f -> Just f; _ -> Nothing}) $ + flags + + captures <- recoverTimeLog captureFilename :: IO (TimeLog CaptureData) + writeTimeLog saveFilename captures