DeTraS 0.3.5 User Manual
About this document
©2010 Edmundo Álvarez Jiménez.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
Latest revision: May 15, 2010.
DeTraS is a set of tools to track developers activities by registering its applications’ usage. It can be also used as a personal time manager on computer, allowing to know how much time we spend performing tasks on the computer. As a lot of networking applications, it has two parts: a client (part of the application that runs on your computer) and a server (usually runs in a remote computer). This manual describes utils under client side of DeTraS (so I will use DeTraS referring to client side of DeTraS from now on). DeTraS includes these utilities:
- TempusFugit. It’s a tool to track your applications’ usage under X11 Window.
- Squealer. A tool to filter and upload your data to a machine running DeTraS server.
- DeTraS applet. A Gnome applet that allows you to configure and use DeTraS’ tools more easily.
2. Getting started
2.1. DeTraS installation
In order to use DeTraS, you have to download it from this page and install it on your system. As this is not an installation guide, I will only give some brief steps to perform installation. There are three methods to install DeTraS on your system:
- Installing from a tarball. Basically, you have to download detras-0.3.5.tar.gz file, extract it, install packages listed on DEPENDENCIES file, run autogen.sh, make and make install.
- Installing from a deb package. Download detras_0.3.5-1_i386.deb or detras_0.3.5-1_amd64.deb depending on your system architecture. Then install package double clicking on it or opening a terminal and typing sudo dpkg -i .
- Installing from a repository. This is the best option if you want to get automatically updates. To install from a repository, go to this page, and follow instructions under Technical details about this PPA. Although that page only shows information about configuring software sources on Ubuntu distros, you should be able to use this repository for almost any recent Debian based distro. Once you have configured your software sources properly, you only have to execute sudo aptitude update and sudo aptitude install detras to get DeTraS installed on your system.
2.2. What information track DeTraS?
DeTraS will store and upload this information about usage of your system:
- When you change windows focus, it will take the time, application name and its window title (you can filter windows titles before upload data).
- Time when your session become active or inactive.
- Your name (optional).
- Projects you are working on (optional).
2.3. What should I do if I have any question or a problem?
If you prefer not joining Launchpad, you can write me an e-mail to e[dot]alvarezj[at]gmail[dot]com.
2.4. What should I do if I find a bug?
As I told you previously, if you prefer not joining Launchpad, you can write me an e-mail to e[dot]alvarezj[at]gmail[dot]com.
You can interact with TempusFugit using a command line interface or DeTraS applet.
- Run TempusFugit on a shell. To execute TempusFugit on a shell, you have to run tempusfugit command. By default, it will store all events on a file called tempusfugit.xml under $HOME/.detras folder. As you will see, TempusFugit run as a daemon, so you have to send a SIGTERM signal (Ctrl+C) to stop its execution. Be sure you send it a SIGTERM signal, because SIGKILL can break events file. To see more details about TempusFugit execution you can check tempusfugit manual page.
- Run TempusFugit using DeTraS applet. See Using DeTraS applet section.
Squealer can be invoked from a shell or using DeTraS applet to upload tracked information.
- Run Squealer on a shell. To execute Squealer from a terminal, you must execute squealer command. It will apply any filter defined on preferences and will send data to configured server. Squealer will not show any output unless it encounter any problem. You can find more details on squealer manpage.
- Run Squealer using DeTraS applet. See Using DeTraS applet section.
DeTraS stores your preferences in a file called detras.ini under $HOME/.detras folder. If this file does not exist, DeTraS will get its preferences from /usr/share/detras/detras.ini, which contains system default preferences. Please read detras.ini manual page before editing these files manually.
6. Using DeTraS applet
6.1. Adding DeTraS applet to panel
To add DeTraS applet to panel, right-click on the panel and choose Add to panel. Then select DeTraS applet from applets’ list and click on Add button. You should see a pencil icon in the panel that represents DeTraS applet.
6.2. DeTraS applet menu
You can perform many actions right clicking on DeTraS applet. As you can see on figure 3, you are able to see an overview of latest events tracked, toggle tracking status, upload data and change your preferences.
6.3. Work with TempusFugit
You can start or stop TempusFugit in two ways: clicking on DeTraS applet or choosing Toggle tracking status from DeTraS applet menu. DeTraS applet icon shows you current TempusFugit’s status. A grey scale icon indicates that TempusFugit is stopped, so it is not tracking your data. A colored one indicates that TempusFugit is running.
6.4. Work with Squealer
To upload data tracked by TempusFugit you have to select Upload data now option from DeTraS applet menu. DeTraS applet will run quietly if everything goes well or will show an error in other case.
6.5. Overview window
Selecting Overview option on DeTraS applet menu will show you a window with latest events tracked on your system. This dialog will show you events tracked since the last time you upload your data, and you can order them by date, length, name…
6.6. Preferences dialog
When you click on Preferences item on DeTraS applet menu, you can edit DeTraS preferences in an easier way than editing $HOME/.detras/detras.ini file manually.
6.6.1. General tab
Here you can configure general preferences:
- Start tracking data on applet init. If you check this box, TempusFugit will start automatically to track your activity when the applet is loaded. (Default: disabled).
- Stop tracking data on applet exit. If you check this box, TempusFugit will stop tracking your activity automatically when the applet is unloaded. (Default: enabled).
6.6.2. Client tab
This window allows you to change client’s preferences:
- Client’s name. Type client’s name on this text box.
- Projects is working on. Configure projects in which the client is working on. Click on Add button to add a new project, select a project and click Delete button to remove a project, or double-click on a project to edit it.
6.6.4. Privacy tab
This window lets you modify privacy preferences:
- Upload client’s name. Check this box to upload client’s name together with your tracked data. (Default: disabled).
- Filter tracked information before its upload. Check this box to enable filtering of your data. (Default: disabled).
- Filter windows titles using these regular expressions. Check this button to enable filtering of windows titles. You can add regular expressions clicking on Add button, delete one of them selecting it and clicking on Delete button and edit a regular expression double clicking on it. If you want help to build regular expressions, you can check this guide.
- Do not upload windows titles. Check this button to hide all information about windows titles before its uploaded.
6.6.5. Server tab
Configure server parameters from this window. By default, this window contains parameters of a server that is tracking data to help me doing my thesis. I really appreciate if you send your data there.
- Address. Type server URL. (Default: https://126.96.36.199).
- Port. Type port where the server is listening. (Default: 8080).
- Service name. Connection service name. Please don’t change this preference unless you know what you are doing. (Default: DeTraS).
Filed under: Help | Leave a Comment