use_cases_examples.md

Use cases and examples of probing the searchable metrics archive API

Here are some examples how the Onionoo-like API (See its documentation here) can be used.

Get summary information about relays

Atlas, Globe and others use the Onionoo protocol and backend for getting information about relays that have or had been recently running (present in the consensus.) This system provides a scalable solution to query and get information about relays in the more distant past, too; all within the framework of an Onionoo-derived protocol. It extends the API as well.

This archive can be queried to return the Onionoo-derived Relay Summary and Details documents (bridges are not included, at least not for now), as well as Network Status documents (a new addition.)

The results are always sorted by the date of the network status (associated with each result entry) in which each relay was present (i.e., the consensus valid-after field), in descending order.

• get a list of most recently run(ning) relays (get the Details document without specifying any parameters.) As these documents are constantly updated, it effectively means "get a list of currently running relays." (Note the upper limit detailed in the Onionoo-like API doc.)

• iterate over the document; use result limiting in combination with offset

• get a shorter summary document about recently run(ning) relays

• get a list of relays that have run in a specific date range

We call this kind of usage "Onionoo-like": the types of queries that are run on Onionoo Summary and Details documents can be run on this system.

Search for relays

Like with Onionoo, one can query the system to search for specific relays using various search criteria.

• search for some specific relays (all their fingerprints over time) using their full nickname

• search for all relays matching a full nickname that is shared by many

• search using a part of a nickname

• search by specifying a particular fingerprint

• search by IPv4 address

• search by a part of an IPv4 address

• search by a part of a nickname, in a specific consensus date range, using offset and limit

Generally speaking, the API is flexible enough to support both "look up a specific relay" as well as "have a vague idea / characteristics of relay(s)" searches. A narrowing-down type of search/browse is intended and supported use.

ExoneraTor-type relay participation lookup

• see if a particular IPv4 address is currently participating as a relay in the network

• see what kinds of relays are currently running in the 128.0.0.0/8 CIDR block

• querying for running relays is supported for all the above search parameters, too

• note one of the earlier queries: it is possible to see if a particular IP address has ever been participant in the relay network

Network statuses

One can look up a specific relay to see a list of consensuses that it has been present in (i.e., a list of network statuses for that relay), as well as the IP addresses and nicknames at the time of that consensus.

• look up a summary of some relay - if it is stable enough, the summary should not be long

• on the other hand, more troublesome relays will have a different pattern of network statuses

• browse through the result set using offset

• use date range parameters as before to narrow down results we are interested in

• browse through the full result set form