You are here: Home > Analyse > Internet Measurements > RIPE Atlas > Documentation > RIPE Atlas - User-Defined Measurements

RIPE Atlas - User-Defined Measurements

These instructions detail how to use the user-defined measurements (UDMs) interface. To learn more about what UDMs are and how they can be used, refer to Customised Measurements. This document provides greater detail on making use of the system by addressing the following topics:

Getting Started

The UDM interface is structured in three main pages: Probes, Measurements, and Credits. You will find the links to these pages, when you are logged in, under the 'My Atlas' menu. It is assumed that you already have access to UDMs (learn more about who can create customised measurements if this is not the case).

Probes

The Probes page lists the RIPE Atlas probes that are part of the measurement network. This page is organised in tabs: "My Probes", "My Favourites", "My Hidden Probes", "My Sponsored Probes", "My Ambassadored Probes", and "Public Probes". Some of these tabs are available only if you are logged in.

If you are a RIPE Atlas ambassador or a RIPE Atlas sponsor, you will see these related probes on separate tabs. Above these tabs are a search field and a set of predefined filters that allow you to search for probes by status (e.g. connected), IP type (IPv4 or IPv6) and region.

The probes page

An individual probe page

You can get more details about a probe by clicking on a probe's ID. Individual probe pages list uptime, network configuration, location, and the built-in and user-defined measurements in which the probe is involved.

In the case of your own probe, you will be able to edit some important configurations such as the system/user-defined tags, the location, and the network configuration (please be careful and read the related documentation before editing the network configuration).

Credits

On the 'Credit' page you can find information about your credit status, including all the administrative actions undertaken by our staff and some explanatory charts.

Under the 'Transfer' tab you can transfer your credits to another RIPE Atlas user. See the Credit System page for a detailed explanation about how RIPE Atlas manages users' credits.

Measurements

The Measurements page allows you to see scheduled measurements and to create a new one. This page is organised in tabs: "My Measurements", "My Favourite Measurements", "My Hidden Measurements", "Public Measurements" and "All Measurements". Some of these tabs are available only if you are logged in.

The measurements page

The measurements page

The status of each measurement listed is identified by an icon, each of which is defined in the next section. On the upper part of the page is a search field and a set of predefined filters applicable to the measurements list.

"My Measurements" and "My Hidden Measurements" show all the user-defined measurements you scheduled in the past. 'Public Measurements' lists all the public measurements created by the entire RIPE Atlas community.

A measurement will appear under "My Favourite Measurements" if you selected it as a favourite by clicking on the star icon.

From this page you can view a measurement by clicking on one of the measurement IDs or create a new measurement by clicking on the green button on the upper part of the page.

Statuses

Each measurement has a status, defined as one of these:

  • Specified: The measurement has been defined and sent to our infrastructure to be relayed to the probes.
  • Scheduled: The measurement has been relayed to the probes. If the start time is immediate, this status doesn't last very long.
  • Ongoing: The measurement is running on available probes.
  • Stopped: The measurement was stopped either on schedule, by the user requesting an early stop.
  • Forced to Stop: The measurement was killed prematurely due to a lack of available credits.
  • No suitable probes: The measurement cannot currently be executed as defined due to a lack of available probes. This may be because you asked to use probes that don't exist (for example, probes in an AS in which there are no probes) or because all of the probes you requested were too busy to take on new jobs. This latter scenario is very rare however.
  • Failed: If a probe never actually runs a single measurement over the duration of the specified start/stop time (typically due to a lack of available probes), it will be marked as Failed once the stop time has been reached.

In other words, Specified, Scheduled, Ongoing, and No suitable probes are statuses potentially assigned to running measurements (or at least those who may return results at some point), while Stopped, Forced to Stop, and Failed are assigned to measurements that will not be returning any more results.

Creating a New Measurement

On the "Create a New Measurement" page, a wizard will guide you through the creation of a set of measurements.

The measurements creation page

The measurements creation page

The creation process consists of three steps: Definitions, Probe selection and Timing. In the definitions section, you can select the types of measurements you would like to schedule, with the UI showing some configurable parameters, such as the target.

An extra panel at the bottom of the page shows you the real-time, API-compatible specification, which can be used to learn how to create measurements directly through the API.

By default, the wizard suggests common values, allowing you to create a measurement with just two clicks by simply specifying the target and submitting the form.

You need to have sufficient credits to create a measurement. If you try to create a new measurement but do not have enough credits, or you have exceeded the rate limits, you will not be allowed to create a new measurement. In addition, a never-ending measurement will no longer be updated with new results if your balance reaches and remains at zero.

A panel on the left side of the page shows you a real-time estimate and projection about the cost of the measurement you're trying to create.

Definitions

The available measurement types are "Ping", "Traceroute", "DNS" and "SSL". "HTTP" measurements are also technically possible but are restricted to researchers and other interested users on a case-by-case basis (see Special Requests, below).

You add measurements by clicking the button of the type of measurement you wish to create.

It is possible to create different types of measurements at the same time.

Basic fields, common to all measurement types, are "Target" and "Resolve on probe".

The target is the remote host that probes will try to measure. It should be specified as a hostname or IP address. Note that, for DNS measurements, the target refers to the resolver that will be used, not the host that the resolver will attempt to resolve (known as the argument).

If a hostname was specified as the 'Target', resolving the hostname into an IP address can be done by the RIPE Atlas back-end, or by each probe. Checking the 'Resolve on probe' box enables probe-side checking.

Following is a list of measurement types and related parameters. (Note that some fields are contained under "Advanced Options" and you must click on this link to reveal them.)

Ping

  • Address Family - Select whether you want to use IPv4 or IPv6.
  • Packets - The number of packets that should be sent in each ping.
  • Size - The size of the packets that are sent.
  • Description - Allows you to give the measurement a description to help you identify it.
  • Interval - The number of seconds each probe participating in the measurement will wait before attempting to perform the measurement again. A drop-down list will suggest some common options.
  • Spread – This distributes the start time of the probes’ measurements throughout the interval so that they are more evenly spaced. If spread is not specified, it will default to half of the interval, with a maximum of 400 seconds.

Traceroute

  • Address Family - select whether you want to use IPv4 or IPv6.
  • Timeout - This option is the maximum time, in miliseconds, to wait for a response.
  • Interval - The number of seconds each probe participating in the measurement will wait before attempting to perform the measurement again.
  • Spread – This distributes the start time of the probes’ measurements throughout the interval so that they are more evenly spaced. If spread is not specified, it will default to half of the interval, with a maximum of 400 seconds.
  • Description - Allows you to give the measurement a description to help you identify it.
  • Protocol - This specifies the protocol to be used, either UDP or ICMP. More information about these protocols as they relate to traceroute can be found on Wikipedia.
  • Packets - The number of packets that should be sent in each traceroute.
  • Size - The size of the packet.
  • First Hop - This is the initial value for the time-to-live counter.
  • Destination Extension Header Size - The size of the destination extension header to include in the IPv6 packet.
  • Port - Destination port for TCP traceroute.
  • Paris - A number greater than 0 will indicate the number of variations to be used for a Paris traceroute. Setting the value to 0 makes the measurement use the standard traceroute.
  • Maximum Hops - This is the final value for the time-to-live counter.
  • Hop-by-Hop Extension Header Size - The size of the hop-by-hop extension header to include in the IPv6 packet.
  • Don't Fragment - Enabling this option avoids fragmentation for outgoing packets. Read about fragmentation for additional details.

DNS

  • Address Family - Select whether you want to use IPv4 or IPv6.
  • Query Class - Specify if the query will be performed in the IN or CHAOS domain space.
  • Query Type - The type of DNS query to be performed.
  • Query Argument - The domain name (or IP address, in the case of reverse DNS) to look up.
  • Description - Allows you to give the measurement a description to help you identify it.
  • Interval - The number of seconds each probe participating in the measurement will wait before attempting to perform the measurement again.
  • Spread – This distributes the start time of the probes’ measurements throughout the interval so that they are more evenly spaced. If spread is not specified, it will default to half of the interval, with a maximum of 400 seconds.
  • Set DNSSEC OK Flag - Enable DNSSEC DO bit (RFC-3225). Default is off
  • Recursion desired - Enable recursion. This is the RD flag described in RFC1035.
  • Use Probe's Resolver - Ese the probe's list of local resolvers instead of specifying a target to use as the resolver.
  • Protocol - The protocol to use.
  • Retry Times - Number of attempts.
  • UDP Payload Size - The maximum reply size accepted. This field is described in RFC2671.
  • Include the Qbuf - Include a base64 encoded version of the queries made by the probe.
  • Exclude the Abuf - Exclude the full base64 encoded answer.
  • Prepend the Probe's ID - Each probe prepends its probe number and a timestamp to the DNS query argument to make it unique
  • Use NSID - Include DNS nameserver identifier option (RFC5001)

SSL

  • Address Family - Select whether you want to use IPv4 or IPv6.
  • Port - The TCP port of the SSL server. The default is the same as the default for SSL servers: port 443.
  • Description - Allows you to give the measurement a description to help you identify it.
  • Interval - The number of seconds each probe participating in the measurement will wait before attempting to perform the measurement again.
  • Spread – This distributes the start time of the probes’ measurements throughout the interval so that they are more evenly spaced. If spread is not specified, it will default to half of the interval, with a maximum of 400 seconds.

Spread

Spread can be set under “Advanced Options” in Step 1 when creating a new measurement using the web interface, and is also available via the API. Spread creates a distribution of individual measurements throughout the measurement interval, rather than clustering the measurements as closely together as possible. In this way, spread helps to avoid overloading targets with bursts of measurements and creates a more steady flow of packets.

For example, if you use 60 probes for a measurement that is scheduled to take place every 240 seconds without any spread, all 60 probes would perform their measurement at nearly the same time, every 240 seconds. With a spread of 240 seconds, the probes will be assigned random start times throughout each interval. In this example, this would average out to one measurement every four seconds. The fewer the number of probes, the less uniform the distribution will be throughout the interval, since the probes are distributed randomly. However, the probes will stick to the specified frequency, so their distribution will remain the same from one interval to the next.

Spread

Interval control in action. The x-axis is the time of measurement and dots are individual results. The green dots correspond to a frequency of 1,800s and a spread of 30s, while red dots correspond to a frequency of 3,600s and a spread of 3,600s.

Probe Selection

The second step of the wizard helps select the probes that will participate in the UDM. By default, 50 probes worldwide are randomly selected, allowing you to skip this step if you like.

You can specify a set of probes already used in a previously scheduled measurement or a new set of probes, either manually or through the probe selection wizard. The selections are displayed in an editable list.

New Set of Probes - Wizard

The probe selection wizard panel appears on the screen by clicking the related button. The panel is composed of three main components: the search field (upper part of page), the map, and the selections made (right side of panel).

The probe selection wizard

The probe selection wizard

To make a selection, just type in what are you looking for in the search field and the wizard will try to find what you were looking for. The system is able to handle geolocations up to street level (e.g. you can search for probes in a certain city area). The map shows the geographical position of the selected probes in real time. For example, by searching for "Canada IPv6" the map will show all the IPv6 probes in Canada. The default map filter is 'worldwide' (WW). The search field presents some additional clickable fast filters.

Area name Top left latitude, longitude Bottom-right latitude, longitude
WW 90, -180 -90, 180
South-East 45, 45 -90, 180
North-East 90, 45 45, 180
South-Central 30, -30 -90, 45
North-Central 90, -30 30, 45
West 90, -180 -90, 30

Areas used in RIPE Atlas measurements sources

Areas used in RIPE Atlas measurements sources

The probes on the map are clustered, but you can adjust the zoom level to see all of them individually. By clicking on a probe in the map you can get more information, including its status, and select the probe. On the left of the map there are additional selection tools, including the radius selector, which allows you to select all the probes within a certain radius of a specified location.

Depending on the type of selection, you will be prompted by some additional selection steps. For example, you may be required to select the number of probes or the types of probe tags to include or exclude. The number of probes is suggested and bounded according to the maximum number of probes available for the measurement. Probe tags allow you to additionally filter probes based on system/user-defined tags. The system tags are suggested by an autocompletion system.

By clicking on a selection on the right panel, the map will automatically pan and zoom to show the subset of probes selected.

New Set of Probes - Manual Selection

Manually selecting probes allows you to specify type, value, number of probes, and probe tags. If you are unsure how to select probes manually, please use the wizard.

Type and values

The available types are: Area, Country, Prefix, and ASN:

  • Area: Select from a list of pre-defined areas of the world. Reference the map above for details.
  • Country: Select probes in a specified country. The values are expressed as two-letter ISO country codes.
  • Prefix: Select probes from within a specific prefix. You'll have to type that prefix into to the mandatory field.
  • ASN: Lets you choose probes on the basis of the AS Number in which their addresses originate.

Number of Probes

Allows you to specify how many probes you want from within the area you have selected.

IDs List

Sometimes you just have an arbitrary list of probe ids that you want to use. In these cases, click the IDs List button and input a list of comma-separated probe IDs in the big text box. Note that there shouldn't be any spaces in there, so 1,2,3,4,5 is what you're looking for rather than 1, 2, 3, 4, 5. You can also use the autocomplete box here to find a specific anchor.

Important note: Specifying a probe id does not guarantee that it will be used in your measurement. Your selected probe(s) may be disconnected from our network at the time of scheduling, or they may simply be too busy to handle additional measurements. In most cases, the requested probe(s) will be rolled into the measurement, but you should not assume this to be the case 100% of the time.

Reuse a set from a measurement

A dialogue will guide you through the selection of a measurement and a number of probes. An auto suggestion system will help you find the measurement. When a measurement is selected, the number of probes involved is suggested in the second field.

Timing

The third screen of the UDM wizard allows you to select the measurement's start and stop times. The fields are Start and End time. You can also specify whether it is a One-off measurement.

One-off

One-off measurements, as the name suggests, execute only once. What makes them really attractive is the fact that they are near real time; results are delivered a few seconds (generally 8-10) after specifying the measurement. This makes one-offs an ideal tool for looking into network problems that are perceived "now". If this option is selected, you can specify only the Start time.

Start

For the measurement start time, you can choose between 'as soon as possible' or a specific date and time (in UTC).

End

The measurement's end time can be 'never' (which means it won't stop until you manually stop it) or a specific date and time (in UTC).

Once your measurement is submitted and accepted, you can immediately see it in your measurement list, and can check its results.

Viewing a Measurement

After you click on a measurement ID in Measurements, a new page shows you all the details about the selected measurement. The page is divided into tabs, some of which are available for all the different measurement types. Others tabs show advanced tools for the visualisation and analysis of the data.

The measurement information page

An individual measurement information page

The amount of information available in the 'General Information' tab depends on the status of the measurement. A measurement that has been scheduled will list probe assignments in addition to other information. If the measurement belongs to you, you can terminate it or set it as public or not from within this tab.

The 'Probes' tab shows information about the involved probes, including RTTs, while the 'Modification Log' tab will show all the changes that occurred with the involved probes.

As soon as results are collected, they will be available in the 'Download Results' tab in JSON format. If you wish to make use of these results, you are advised to review the data structure documentation

In the overview of probes which were selected to participate in the measurement, it is possible to click on the autonomous system number (ASN) in order to learn more about the network the probe is a part of (details are handled by RIPEstat). If the probe is public, it is also possible to learn more about the probe's historic and current status. There is also the option of seeing where the probes are geographically located.

Rate Limits

The following rate limits apply for users/measurements:

  • No more than 100 simultaneous measurements
  • No more than 1000 probes may be used per measurement
  • No more than 100,000 results can be generated per day
  • No more than 50 measurement results per second per measurement. This is calculated as the spread divided by the number of probes.
  • No more than 1,000,000 credits may be used each day
  • No more than 25 ongoing and 25 one-off measurements of the same type running against the same target at any time

Special Requests

If you have an especially interesting measurement you think might be of value to the community, but which would exceed the rate limit or the number of credits you have available, please contact us at atlas@ripe.net to propose your study.