Last updated: 18.08.2006 Test Status: pre Alpha Contact: google-soc@genone.de (or genone@gentoo.org) Where to get ============ The latest release of the gentoo-stats code is available at http://dev.gentoo.org/~genone/distfiles/gentoo-stats or via the portage project overlay at http://overlays.gentoo.org/proj/portage If you have access to the portage subversion repository you can also checkout the gentoo-stats/trunk module and build the release tarball with python ./setup.py sdist --formats=bztar How to install ============== Ebuilds for gentoo-stats are available in the portage project overlay at http://overlays.gentoo.org/proj/portage, please refer to the docs on http://overlays.gentoo.org for how to use it. As an alternative you can add a gentoo-stats ebuild to your local overlay by unpacking a gentoo-stats tarball and running python ./setup.py create_ebuild --no-digest --reuse-build inside the unpacked dir (--no-digest is needed as the release tarball can't regenerate itself yet so the distutils script would create a somewhat incomplete tarball, if you use a svn checkout you can omit it and get a one-step release process; --reuse-build is needed to keep the current version number). After that is done you can install the gentoo-stats package simply with emerge gentoo-stats While both client and server code are functional the server code isn't of much use without a proper setup which I haven't completely figured out yet, but when you also want the server code you have to set USE=server to get it (really, unless you study the code in detail you won't be able to use the server in any way yet) If you want to manually install it refer to the distutils docs and template.ebuild. What to test ============ Client registration, data collection and upload should be fully functional except for some optional features (see 'Configuration' below), but in the current state may of course have bugs. The server currently has a few simple pages to show some stats (most popular pakages in world and vdb, most popular portage config items), this will be expanded and improved over time. Configuration for offline testing ================================= Use this if you only want to perform local tests without contacting the testserver or if you don't know any testserver. Otherwise see below. Assuming you installed with the generated ebuild, first switch to /etc/gentoo-stats and create a file id.conf with the following content: clientid=0 authkey= This is a dummy file to fake the client so it doesn't try to get a new id from the (not-existing) server. If you want you can also copy client.conf.default to client.conf and edit it as you want, though not all options there are really used yet (most interesting for now is the "ActiveModules" section). When running the gentoo-stats-client tool always use the --no-upload option. Configuration for online testing ================================ NOTE: if you previously tested gentoo-stats make sure you remove /etc/gentoo-stats/id.conf and /var/lib/gentoo-stats before testing on a new server, otherwise you may see some kind of out-of-sync errors (I'm going to fix that in the future, but for now you have to delete those locations when switching servers) Assuming you installed with the generated ebuild, first switch to /etc/gentoo-stats and copy client.conf.default to client.conf. In client.conf set "Network->Server" to the url of the testserver (including the http:// protocol part) and select the collection modules you want to use in the "ActiveModules" section (NOTE: do not enable the "PackageFileMap" or "MetadataInstalledPackages" modules, they are disabled on the server due to performance problems anyway). If you want you can also change the default "Paths", but don't change anything in the "Data" section (as there are no other choices than the defaults yet) When you first run the gentoo-stats-client tool use the --register option to create an account on the server for your box (if you test on multiple boxes each one needs a separate account). How to test =========== Once you're done with the setup stuff simply run /usr/bin/gentoo-stats-client to create a data record file (short DRF) for your system. For this to work you must have write access to the paths denoted by "Paths->PersistentStorage" and "Paths->TemporaryStorage" in client.conf. If that worked you should have a DRF in /var/lib/gentoo-stats/records/record-000001.list.bz2, the size of that can vary between a few bytes and several megabytes, depending on the activated modules. Also that records was sent to the configured server (unless you used --no-upload) and should show up in its stats pages (unless there was an error during the upload). To test delta-generation you need some change in your system (so you can get a useful delta), without a change we still get a delta but it's quite useless as it only contains protocol info. With the default config the easiest way to force a change is to emerge a new package (or update an existing one). When you then the gentoo-stats-client again it will only send the delta record to the server, reducing both bandwith usage and server load. Feedback ======== I'd appreciate if you notify me if you had success with the above testing and even more if it failed for you. In case of an error please also send me a tarball with the contents of /var/lib/gentoo-stats and /etc/gentoo-stats together with a description of what you did to get to that state and the exact error messages (if any). How to remove ============= A simple emerge -C gentoo-stats rm -rf /var/tmp/gentoo-stats /var/lib/gentoo-stats /etc/gentoo-stats should be sufficient.