[metrics-web/master] Add About page with questions and answers. - tor-commits

1 Jul 2014

commit 7bad7bbde718680c06a4458fe241af22feaf12c2
Author: Karsten Loesing karsten.loesing@gmx.net
Date:   Sun Jun 29 17:33:35 2014 +0200
Add About page with questions and answers.
---
 website/etc/web.xml                                |   11 ++
 .../org/torproject/metrics/web/AboutServlet.java   |   24 +++
 website/web/WEB-INF/about.jsp                      |  186 ++++++++++++++++++++
 website/web/WEB-INF/banner.jsp                     |    2 +
 website/web/WEB-INF/error.jsp                      |    1 +
 website/web/WEB-INF/index.jsp                      |    4 +
 6 files changed, 228 insertions(+)

diff --git a/website/etc/web.xml b/website/etc/web.xml
index c187315..ee439f3 100644
--- a/website/etc/web.xml
+++ b/website/etc/web.xml
@@ -241,6 +241,17 @@
     <url-pattern>/consensus-health.html</url-pattern>
   </servlet-mapping>
+  <servlet>
+    <servlet-name>AboutServlet</servlet-name>
+    <servlet-class>
+      org.torproject.metrics.web.AboutServlet
+    </servlet-class>
+  </servlet>
+  <servlet-mapping>
+    <servlet-name>AboutServlet</servlet-name>
+    <url-pattern>/about.html</url-pattern>
+  </servlet-mapping>
+
   <welcome-file-list>
     <welcome-file>index.html</welcome-file>
   </welcome-file-list>
diff --git a/website/src/org/torproject/metrics/web/AboutServlet.java b/website/src/org/torproject/metrics/web/AboutServlet.java
new file mode 100644
index 0000000..5a59ce0
--- /dev/null
+++ b/website/src/org/torproject/metrics/web/AboutServlet.java
@@ -0,0 +1,24 @@
+/* Copyright 2014 The Tor Project
+ * See LICENSE for licensing information */
+package org.torproject.metrics.web;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+public class AboutServlet extends HttpServlet {
+
+  private static final long serialVersionUID = 97168997894664L;
+
+  public void doGet(HttpServletRequest request,
+      HttpServletResponse response) throws IOException, ServletException {
+
+    /* Forward the request to the JSP that does all the hard work. */
+    request.getRequestDispatcher("WEB-INF/about.jsp").forward(request,
+        response);
+  }
+}
+
diff --git a/website/web/WEB-INF/about.jsp b/website/web/WEB-INF/about.jsp
new file mode 100644
index 0000000..886db80
--- /dev/null
+++ b/website/web/WEB-INF/about.jsp
@@ -0,0 +1,186 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+  <title>Tor Metrics: About</title>
+  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
+  <link href="../css/stylesheet-ltr.css" type="text/css" rel="stylesheet">
+  <link href="/images/favicon.ico" type="image/x-icon" rel="shortcut icon">
+</head>
+<body>
+  <div class="center">
+    <%@ include file="banner.jsp"%>
+    <div class="main-column">
+<h2>Tor Metrics: About</h2>
+<br>
+
+<div style="line-height: 18pt;">
+<p>
+<b>Q: How do you obtain all these facts in an anonymity network without
+hurting user privacy?</b><br>
+A: The metrics on this website are based on different data sources in the
+Tor network.
+Some of these data sources are not sensitive at all, like properties and
+capabilities of a relay.
+Others are more sensitive, like statistics on fetched directory listings
+by country.
+But others are simply too sensitive to gather at all, like contents of
+unencrypted connections leaving the Tor network, so we don't have metrics
+on those.<br>
+We wrote a
+<a href="http://freehaven.net/anonbib/#wecsr10measuring-tor">research
+paper</a> where we describe how we measure potentially sensitive data in
+the Tor network.
+Whenever we plan to add new data, this plan needs to go through a rigorous
+process of writing a
+<a href="https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/001-process.txt">proposal
+document</a>, which is usually discussed on the
+<a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev">public
+development list</a>, and publicly reviewing code patches on the
+<a href="https://trac.torproject.org/projects/tor">bug tracker</a>.
+Furthermore, as a core principle, we only use data for metrics that have
+been made publicly available:
+if the raw data are too sensitive to publish, then we shouldn't even
+publish aggregate statistics of it.
+See the <a href="https://collector.torproject.org/">CollecTor service</a>
+that we use as single data source for all graphs and tables on this
+website.
+</p>
+<p>
+<b>Q: How do you know <a href="network.html">how many servers there are in
+the network</a>, how many of them permit exiting, etc.?<br></b>
+A: The servers in the Tor network, called relays and bridges, send a
+document with properties and capabilities to a set of central directory
+servers.
+These directory servers perform some reachability tests and publish a list
+of running servers.
+All we have to do is throw these documents into a database and run
+aggregation functions on it.
+</p>
+<p>
+<b>Q: How do you know <a href="bandwidth.html">how much bandwidth is
+advertised and consumed</a> in the network?</b>
+<br>
+A: Relays and bridges report bandwidth numbers to the central directory
+servers, both how much bandwidth they advertise and how much is used up by
+clients.
+</p>
+<p>
+<b>Q: How do you measure <a href="bubbles.html">diversity of relays</a> in
+the network?</b>
+<br>
+A: We resolve relay IP addresses to country codes and autonomous system
+numbers using <a href="https://www.maxmind.com/en/opensource">MaxMind's
+open source databases</a>.
+That gives us a rough idea whether there are certain countries or Internet
+providers running larger parts of the Tor network than others.
+</p>
+<p>
+<b>Q: How do you know <a href="users.html">how many users</a> there are in
+the network?</b>
+<br>
+A: We don't actually count users but directory traffic induced by Tor
+clients.
+Clients periodically need to update their view on the network, and by
+counting those requests we can make some rough estimates how many users
+there are.
+If you want to learn more, there's a more detailed document available
+dubbed
+<a href="https://gitweb.torproject.org/metrics-web.git/blob/HEAD:/doc/users-q-and-a.txt">Questions
+and answers about user statistics</a>.
+We also wrote a technical report titled
+<a href="https://research.torproject.org/techreports/counting-daily-bridge-users-2012-10-24.pdf">Counting
+daily bridge users</a> which is very related.
+</p>
+<p>
+<b>Q: How do you <a href="performance.html">measure performance</a> in the
+network?</b>
+<br>
+A: We run our own measurements using a tool called
+<a href="https://gitweb.torproject.org/torperf.git">Torperf</a>.
+This tool fetches files of three different sizes over the Tor network and
+measures how long that takes.
+</p>
+<p>
+<b>Q: How often are graphs updated?</b>
+<br>
+A: The graphs and tables on this website are updated multiple times per
+day.
+However, some graphs have the last few days cut off, because we don't have
+enough data available yet.
+It simply takes time to report, collect, and process all the data.
+</p>
+<p>
+<b>Q: Are the raw numbers behind graphs available for download?</b>
+<br>
+A: Yes, all raw numbers are available in comma-separated value files
+(.csv), which have their own
+<a href="https://gitweb.torproject.org/metrics-web.git/blob/HEAD:/doc/stats-spec.txt">specification
+document</a>.
+In addition to that, the raw data behind those .csv files are available
+via the <a href="https://collector.torproject.org/">CollecTor service</a>.
+If you do something cool with either the .csv files or the raw data,
+please drop us a note, so that we may add a link here.
+</p>
+<p>
+<b>Q: How can I request a new graph or table?</b>
+<br>
+A: Please open a ticket in the
+<a href="https://trac.torproject.org/projects/tor">bug tracker</a> using
+component "Metrics Website".
+But please understand that adding a new graph or table may be harder than
+it seems.
+The following categories of feature requests may help you assess how
+likely it is that we implement your suggestion and how long it may take.
+Of course, you can always influence both likelihood and time to get your
+graph or table added by helping out!
+<ol>
+<li>Adding a link to a related project that does something cool with Tor
+network data is easiest.
+These links can be pretty useful, because somebody might pick up the idea
+and write a patch to include a fully customizable graph or table for this
+website.
+Adding a link is usually done within a day or two.</li>
+<li>Improving an existing graph or table is slightly more work.
+For example, you might suggest to add a new parameter or put another line
+on a graph.
+If the data for that is already available, this can be done within a
+couple of days, assuming somebody is free to do it.</li>
+<li>Adding a new graph or table based on existing, already processed data
+requires writing some graphing code in R and some HTML around it.
+This may take a few weeks.</li>
+<li>Adding a new graph or table based on raw data that needs processing
+takes quite some more work.
+This may require us to do some heavy database lifting, because we need to
+be sure that the processing code scales in the next few years.
+So, expect this to take a couple of months.</li>
+<li>Finally, adding a new metric based on newly gathered raw data, that
+is, new fields in descriptors or even new descriptors types, is most
+time-consuming.
+And to be honest, it is least likely to happen without your help.
+In addition to the significant development work, we may have to wait one
+or even two Tor release cycles to get the new code running on relays
+and/or bridges.
+Everything under one year is optimistic for this type of enhancement
+request.</li>
+</ol>
+</p>
+<p>
+<b>Q: Are there open feature requests or other issues related to this
+website, and where do I start writing code for it?</b>
+<br>
+A: The bug tracker has a list of
+<a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Metrics+Website&order=priority">open
+tickets in the Metrics Website component</a>.
+The sources are
+<a href="https://gitweb.torproject.org/metrics-web.git/">available via
+Git</a>.
+</p>
+</div>
+
+    </div>
+  </div>
+  <div class="bottom" id="bottom">
+    <%@ include file="footer.jsp"%>
+  </div>
+</body>
+</html>
diff --git a/website/web/WEB-INF/banner.jsp b/website/web/WEB-INF/banner.jsp
index 3a3cf5d..07c09b2 100644
--- a/website/web/WEB-INF/banner.jsp
+++ b/website/web/WEB-INF/banner.jsp
@@ -20,6 +20,8 @@
     <a <% if (currentPage.endsWith("performance.jsp")) {
         %>class="current"<%} else {%>href="/performance.html"<%}
         %>>Performance</a>
+    <a <% if (currentPage.endsWith("about.jsp")) {
+        %>class="current"<%} else {%>href="/about.html"<%}%>>About</a>
   </td>
   <td class="banner-right"></td>
 </tr>
diff --git a/website/web/WEB-INF/error.jsp b/website/web/WEB-INF/error.jsp
index bd6d442..a0484dc 100644
--- a/website/web/WEB-INF/error.jsp
+++ b/website/web/WEB-INF/error.jsp
@@ -46,6 +46,7 @@ Maybe you find what you're looking for on our sitemap:
 <li><a href="bubbles.html">Diversity</a></li>
 <li><a href="users.html">Users</a></li>
 <li><a href="performance.html">Performance</a></li>
+<li><a href="about.html">About</a></li>
 </ul>
 </p>
diff --git a/website/web/WEB-INF/index.jsp b/website/web/WEB-INF/index.jsp
index 95b10ac..c0e3c15 100644
--- a/website/web/WEB-INF/index.jsp
+++ b/website/web/WEB-INF/index.jsp
@@ -38,6 +38,10 @@
         <a href="performance.html"><h3>Performance</h3></a>
         <p>How long does it take to download a megabyte of data over Tor?
         How about five?</p>
+
+        <a href="about.html"><h3>About</h3></a>
+        <p>How do you obtain all these facts in an anonymity network
+        without hurting user privacy?</p>
     </div>
   </div>
   <div class="bottom" id="bottom">

    