How to contribute to the Tor metrics timeline

The metrics timeline is a database of news and events that may affect Tor Metrics 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?"

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 bridge graph article

Or, you may look at the graph of relays' advertised bandwidth and ask, "What accounts for the bump in August 2018?"

The timeline has an explanation for this, too. It was the result of a temporary 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 post announcing start post announcing end advertised bandwidth graph relay flags graph

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 called 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, 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; bridge if bridges but not relays are affected; or onion if the event involves 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 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 an X in the ? field.

How to contribute

To add an entry to the metrics timeline, or edit an existing entry, you will need to create a Tor GitLab account, edit the file, and make a merge request.

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 support and we will try to help. An alternative to making a merge request is to open a new issue with all the necessary information.

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 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.

We will need a Tor GitLab account, so we go to https://gitlab.onionize.space/ and request an account.

After the account is created, we can go to https://gitlab.torproject.org/ and log in. We go to README.md in the metrics timeline repository 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:

start date	end date	places	protocols	description	links	?
2020-06-30 05:00:00	ongoing	et		Internet shutdown in Ethiopia.	article IODA relay users graph

Looking at the graph of directly connecting users 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:

Then we do a web search for terms like "Ethiopia Internet shutdown 2020". We find an article 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 page, we click the blue "Edit" button, then the green "Fork" button.

We scroll down to find the entry we are interested in:

And then make these 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/).

In the "Commit message" box, we enter "June 2020 shutdown in Ethiopia ended in July," then click the green "Commit changes" button.

We arrive at a page titled "New Merge Request." We leave all the options unchanged and click the green "Submit merge request" button.

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.