[metrics-team] Blog post about contributing to the Tor metrics timeline
David Fifield
david at bamsoftware.com
Tue Feb 23 21:15:45 UTC 2021
I want to make a blog post explaining how to contribute to the metrics
timeline. By this, I hope to attract new people to working with Tor
Metrics and helping maintain the timeline. This is a draft of the post I
hope to make.
- The timeline used to be imported into the Tor Metrics site so that a
table of events could be displayed below graphs. From
https://metrics.torproject.org/news.html, it looks like the timeline
has not been imported since December 2020. I presume this is because
Karsten used to do it himself.
- Is is all right to recommend that people contact the metrics team if
they have trouble registering an account or using Git? Or should that
go to support?
- I want to include screenshots in the tutorial. In the past I've hosted
blog graphics under people.torproject.org/~dcf/, but I've been told
it's better, for the blog, to host them at extra.torproject.org. What
is the process for getting files placed on extra.torproject.org?
----
# How to contribute to the Tor metrics timeline
The [metrics timeline](https://gitlab.torproject.org/tpo/metrics/timeline)
is a database of news and events that may affect
[Tor Metrics](https://metrics.torproject.org/) graphs. This post is
about how you can contribute to the timeline and help keep it up to
date.
A timeline of events helps in interpreting graphs. For example, you may
look at a graph and ask, "Why did the number of Tor users in Sri Lanka
increase for a week in 2018?"
[<graph>](https://metrics.torproject.org/userstats-relay-country.html?start=2018-02-01&end=2018-04-15&country=lk&events=off)
Checking the timeline, we find that at that time in Sri Lanka there was
a block of Facebook and other services. A likely explanation for the
increase of users is that people were using Tor to access the blocked
services.
|start date|end date|places|protocols|description|links|? |
|----------|--------|------|---------|-----------|-----|---|
|2018-03-07|2018-03-15|lk||Sri Lanka blocks Facebook, Instagram, WhatsApp, and Viber.|[relay graph](https://metrics.torproject.org/userstats-relay-country.html?start=2018-01-01&end=2018-04-01&country=lk) [bridge graph](https://metrics.torproject.org/userstats-bridge-country.html?start=2018-01-01&end=2018-04-01&country=lk) [article](https://www.reuters.com/article/us-sri-lanka-clashes-socialmedia/sri-lanka-lifts-ban-on-facebook-imposed-after-spasm-of-communal-violence-idUSKCN1GR31R)||
Or you may look at the graph of relays' advertised bandwidth and ask,
"What accounts for the bump in August 2018?"
[<graph>](https://metrics.torproject.org/bandwidth.html?start=2019-07-01&end=2019-09-01)
The timeline has an explanation: it was the result of a temporary
scientific experiment to test the accuracy of relays' bandwidth reports.
|start date|end date|places|protocols|description|links|? |
|----------|--------|------|---------|-----------|-----|---|
|2019-08-06|2019-08-09 01:00:00|||Experiment to test the accuracy of relays' advertised bandwidth estimation.|[description of experiment](https://lists.torproject.org/pipermail/tor-relays/2019-July/017535.html) [post announcing start](https://lists.torproject.org/pipermail/tor-relays/2019-August/017599.html) [post announcing end](https://lists.torproject.org/pipermail/tor-relays/2019-August/017617.html) [advertised bandwidth graph](https://metrics.torproject.org/bandwidth.html?start=2019-07-01&end=2019-09-01) [relay flags graph](https://metrics.torproject.org/bandwidth-flags.html?start=2019-07-01&end=2019-09-01)||
The metrics timeline is useful but incomplete—for example, it tends to
only include events that make international news. Some past events have
a start date but are missing an end date. And some events mark unusual
graph features, but do not have an explanation. You can help the Tor
Project and people trying to understand use of the Tor network by
contributing your knowledge to the metrics timeline.
## Data format
The timeline is a
[text file](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
in the Tor Project's GitLab.
Entries are stored in a table under the `## Timeline` heading. The table
has seven columns:
```
|start date|end date|places|protocols|description|links|? |
|----------|--------|------|---------|-----------|-----|---|
```
* **start date**: The date, in the format `2020-12-31`, when the event
began (for long-term events) or occurred (for instantaneous events).
* **end date**: The date when a long-term event ended. This can be blank
for instantaneous events, or the special value `ongoing` for an event
that has started but not ended yet.
* **places**: A list of
[country codes](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes),
separated by spaces. This field may be blank for events that are not
limited to a specific geographic region.
* **protocols**: Some events only affect one or a few of the many
protocols used by Tor. For example, this field might contain `obfs4`,
`meek`, or `snowflake` if the event affects only one
[pluggable transport](https://tb-manual.torproject.org/circumvention/);
`bridge` if [bridges](https://tb-manual.torproject.org/bridges/) but
not relays are affected; or `onion` if the event involves
[onion services](https://tb-manual.torproject.org/onion-services/).
Leave the field blank if the event is not specific to a protocol.
* **description**: A freeform text description of the event.
* **links**: A list of links to references or other evidence, in
[Markdown](https://en.wikipedia.org/wiki/Markdown) format:
`[link label](https://example.com)`.
* **?**: This field indicates whether the event is adequately explained.
An `X` in the **?** field means that there is an unusual feature on
the graph, but we do not know what caused it. The field is blank when
a likely cause is known.
Here are two examples. The first one had to do with Iran (country code
`ir`) and is considered adequately explained, with links to two reports.
The second one affected only the meek pluggable transport in Brazil
(country code `br`). Its cause is unknown, so it only has a link to a
graph, and an `X` in the **?** field.
```
|2019-11-16|2019-11-23|ir||Internet blackout in Iran.|[report](https://ooni.org/post/2019-iran-internet-blackout/) [NTC thread](https://ntc.party/t/a-new-kind-of-censoship-in-iran/237)||
|2017-06-07|2017-12-14|br|meek|Sustained increase of meek users in Brazil, similar to the one that took place between 2016-07-21 and 2017-03-03.|[graph](https://metrics.torproject.org/userstats-bridge-combined.html?start=2016-06-01&end=2018-01-15&country=br)|X|
```
Here are some specific ways you can help:
* Find an event with `ongoing` in the **end date** field, and see if it
really is still ongoing. If it is not, fill in the end date.
* Think of Tor-related or Internet-related events that have happened in
the country you live in, and make sure there is an entry for each of
them.
* Find an event with `X` in the **?** field and search for references or
online discussion that may explain it.
* Search the graphs for unusual features and add entries for them with
`X` in the **?** field.
## How to contribute
To add an entry to the metrics timeline, or edit an existing entry, you
will have to create a Tor GitLab account, edit the file, and make a
[merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-by-adding-editing-and-uploading-a-file).
Merge requests are the most convenient way for us to accept changes, but
if you prefer not to create an account, or if you have trouble with the
merge request, we still want you to be able to contribute. Contact the
[metrics team](https://gitlab.torproject.org/tpo/metrics/team) and we
will try to help.
1. Create a GitLab account at https://gitlab.onionize.space/. Where it
says "Please explain why you want to collaborate with the Tor
community," you can enter "I want to help with the metrics timeline."
Then wait until the new account is approved.
2. Log in with your account and go to
[README.md](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
file in the metrics timeline repository.
3. Click the blue "Edit" button. The first time you do this, you will
see a message:
> You're not allowed to edit files in this project directly. Please
> fork this project, make your changes there, and submit a merge
> request.
Click the "Fork" button.
4. Now you may edit the text file. You may want to change the "No wrap"
setting to "Soft wrap" to make it easier to read. Scroll down, below
the the `## Timeline` heading, and make your change. In the "Commit
message" box, enter a one-sentence summary of the change, like "March
2021 outage in <country>." Click the green "Commit changes" button.
5. At the "New Merge Request" page, leave the default options and click
the green "Submit merge request" button.
Now the merge request is created. You will get a notification by email
when it is approved, or if the maintainers have questions.
## Step-by-step example
Let's go step by step through the process of finding something to
improve, making the change, and starting a merge request. We will look
for an ongoing event without an end date and find out when it actually
ended.
First we go to the file
[README.md](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
and do a Ctrl+F search for "ongoing". This finds a shutdown event in
Ethiopia in mid-2020, which was ongoing at the time the event was added:
|2020-06-30 05:00:00|ongoing|et||Internet shutdown in Ethiopia.|[article](https://edition.cnn.com/2020/06/30/africa/ethiopia-singer-killing-sparks-protest-intl/) [IODA](https://ioda.caida.org/ioda/dashboard#view=inspect&entity=country/ET&lastView=overview&from=1593192460&until=1593797260) [relay users graph](https://metrics.torproject.org/userstats-relay-country.html?start=2020-06-01&end=2020-07-31&country=et&events=off)||
Looking at the
[graph of directly connecting users](https://metrics.torproject.org/userstats-relay-country.html?start=2020-06-01&end=2020-07-31&country=et&events=off)
from that time, the effect of the shutdown on June 30 is obvious,
but it looks like the number of users recovers a few weeks later:
[<graph>](https://metrics.torproject.org/userstats-relay-country.html?start=2020-06-01&end=2020-07-31&country=et&events=off)
Then we do a web search for terms like "Ethiopia Internet shutdown
2020". We find
[an article](https://qz.com/africa/1884387/ethiopia-internet-is-back-on-but-oromo-tensions-remain/)
saying that Internet access was partially restored on July 15 and the
shutdown ended on July 23, which is consistent with the Tor Metrics
graph. We will make three changes to the entry:
1. Change the **end date** field to `2020-07-23`.
2. Note the 2020-07-15 partial restoration of access in the
**description** field.
3. Add a link to the article to the **links** field.
Still at the
[README.md](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
page, we click the blue "Edit" button, then the green "Fork" button.
<screenshot>
We scroll down to find the entry we are interested in:
<screenshot>
And then we make the changes:
1. Set **end date** to `2020-07-23`.
2. Add to **description** `Restrictions were partially lifted
2020-07-15.`.
3. Add to **links**
`[article](https://qz.com/africa/1884387/ethiopia-internet-is-back-on-but-oromo-tensions-remain/)`.
<screenshot>
In the "Commit message" box, we enter "June 2020 shutdown in Ethiopia
ended in July," the click the green "Commit changes" button.
<screenshot>
We arrive at a page titled "New Merge Request." We leave all the options
unchanged and click the green "Submit merge request" button.
<screenshot>
Now the merge request is created and you are done. Just wait for the
maintainer to merge the change or leave a comment. You will get an email
notification when something in the merge request changes.
You can see the merge request that was created and merged for this
example at
[tpo/metrics/timeline!2](https://gitlab.torproject.org/tpo/metrics/timeline/-/merge_requests/2).
More information about the metrics-team
mailing list