The Metrics website can be found at https://metrics.torproject.org/ and is the entry point for users into the Tor Metrics ecosystem.
Statistics and Graphs
The main thing the Tor Metrics website is known for are the graphs. Each of the graphs follows a very similar process for production.
An overview is shown in this diagram:
- Each day at 0840 UTC (by cron job) the statistics updater is started
run-web.shcron job). This updater reads in the latest descriptors from CollecTor, performs some pre-processing where necessary and adds the new data to the SQL database. There are different tables in the database for different things: e.g., relays, users, or webstats.
- At the end of the run, an export of each table is made to a CSV stored on the filesystem.
- When a user requests a graph via the website, the parameters (e.g., country) are provided to RServe which uses the R code to produce a graph.
- The rendered graph is returned to the user by the web server.
Cron Jobs / Scripts
There are three main scripts to control the operation of the website:
run-web.sh- runs the daily updater, scheduled by cron. You should not need to run this manually.
start-web.sh- starts the web server, scheduled to run at reboot by cron. You may need to run this manually when performing upgrades.
start-rserve.sh- starts the RServe process. You may need to run this when the R code has changed.
Setting up the service in production
Maintaining the service
Monitoring the service
Changing logging options
Changing configuration options
Stopping the service (gracefully)
Upgrading and downgrading
Backing up data and settings
Performing recurring tasks
Updating the news page
To update the news page, use the
generate-news-json ant target. Note
that you do need to run the
jar target first, and building the WAR
will require building the metrics-lib JavaDoc and Exonerator servlet.
This means you do require a full clone of the code, all the submodules,
plus all the library dependencies to complete this.
The generated file is at
should check to see that recent entries have been correctly generated
as the updater does depend on quite strict formatting in the wiki.
Commit the new news.json to the repository, and then follow the steps for deployment of a new WAR.
Resolving common issues
Setting up a development environment
The Metrics website follows much the same layout and organisation as the other Metrics codebases. One thing to note with the website repository is that it contains submodules that themselves contain submodules, so a recursive clone is recommended to ensure that all the necessary submodules are checked out.
Other than this, follow the Java survival guide.