search

jsdelivr / globalping

A global network of probes to run network tests like ping, traceroute and DNS resolve
https://globalping.io
274 stars 34 forks source link
api benchmark devops globalping hacktoberfest monitoring mtr network network-analysis network-monitoring performance ping probes ripe-atlas ripeatlas sysops traceroute

readme

Globalping Header

Gain insights into your network routing from any location in the world!
Troubleshoot anycast issues, monitor CDN and DNS performance, perform uptime monitoring,
and build your own network tools for personal or public use.

Invitation to contribute!

Everyone is welcome to contribute – here are some ways you can get involved:

Refer to CONTRIBUTING.md for more information.

The Globalping Platform

Globalping allows anyone to run networking commands such as ping, traceroute, dig, and mtr on probes distributed around the globe. Our goal is to provide a free, user-friendly API for everyone to build interesting networking tools and services.

Many users will likely prefer alternative ways to use the platform rather than working directly with the API. Therefore, to make Globalping accessible to all kinds of users, we're constantly expanding and improving our tools, all of which leverage the full potential of the Globalping API:

Learn more about Globalping on globalping.io

Register on the Globalping Dashboard to increase your limits and adopt probes to earn free credits!

Our major sponsors

We thank our sponsors who contribute to the development of Globalping and help us expand our probe network!

Gcore xTom Edis Global

Support the Globalping community and platform

We welcome any individual or company interested in supporting Globalping's growth and our mission to make the internet a faster place for everyone. Here are some ways you can help:

Quick start – Run your first tests

Whether you're new to network testing or are a seasoned pro, getting started with Globalping is straightforward. Let's check out how you can run your first tests using our various tools and integrations:

Web-based tools - Globalping website

globalping latency test from google cloud

Our website offers the fastest way to get started. Run tests instantly from anywhere and experiment with the different options for different test types. For each test, you can view the probes used on a map and get a detailed view of the individual test results below.

Globalping CLI

Upgrade your network debugging capabilities by installing the Globalping CLI tool. Get access to our global network of probes without leaving your terminal!

Install the CLI on Linux, macOS, or Windows using the command for your package manager:

#Ubuntu
curl -s https://packagecloud.io/install/repositories/jsdelivr/globalping/script.deb.sh | sudo bash
apt install globalping

#RHEL
curl -s https://packagecloud.io/install/repositories/jsdelivr/globalping/script.rpm.sh | sudo bash
dnf install globalping

#MacOS
brew tap jsdelivr/globalping
brew install globalping

#Windows
winget install globalping
OR
choco install globalping

And then run your tests:

$ globalping traceroute google.com from Western Europe --limit 2
> EU, DE, Frankfurt, ASN:210546
traceroute to google.com (142.250.185.78), 20 hops max, 60 byte packets
 1  10.0.0.1 (10.0.0.1)  0.747 ms  0.714 ms
 2  10.2.0.97 (10.2.0.97)  5.482 ms  5.511 ms
 3  10.10.0.1 (10.10.0.1)  613.232 ms  613.268 ms
 4  ae6-ffm21.core2.ffm3.de (45.138.175.101)  9.150 ms  9.188 ms
 5  ae1-core2.core3.ffm3.de (45.138.175.105)  6.027 ms  6.030 ms
 6  142.250.171.196 (142.250.171.196)  5.562 ms  5.749 ms
 7  209.85.244.249 (209.85.244.249)  48.691 ms  48.812 ms
 8  142.250.209.243 (142.250.209.243)  5.742 ms  5.743 ms
 9  fra16s48-in-f14.1e100.net (142.250.185.78)  5.716 ms  5.717 ms

> EU, NL, Zwolle, ASN:50673
...

Learn more about the Globalping CLI in its repository

Globalping REST API

If you want to build something custom or simply learn more about all the available options and data we provide, check out the Globalping REST API.

Creating a new measurement test is as simple as:

POST https://api.globalping.io/v1/measurements
{
    "limit": 10,
    "locations": [],
    "target": "jsdelivr.com",
    "type": "ping",
    "measurementOptions": {
        "packets": 5
    }
}

Read the full API documentation and explore our dev demo

Slack App

Improve collaboration in your workspace by installing our Slack app, enabling everyone to interact with Globalping without leaving Slack. The app is especially handy for NOC, OPS, and Support teams collaborating on debugging networking issues and discussing results.

Add to Slack

To initiate a command with the Globalping Slack app, use the slash command /globalping. Apart from that, you can use the same test command structure as with our other tools and integrations. For example, to get started, type /globalping help.

Example commands to try:


/globalping ping 8.8.8.8 from Germany

/globalping traceroute jsdelivr.com from South America --limit 2

[!Important] To make the app post test results in Slack Threads, mention it using @globalping. For example,  @globalping ping google.com

Learn more about the Slack app on our blog.

GitHub Bot

Automatically post network test results into any public GitHub issue with our GitHub bot. Mention it with @globalping, followed by the command you want to run. Otherwise, you can follow the same test command structure as with our other tools and integrations.

Example commands to try:

@globalping ping 8.8.8.8 from Germany
@globalping traceroute jsdelivr.com from South America --limit 2

Learn more about the GitHub bot on our blog.

Globalping command structure

We make sure that all integrations and tools provide a consistent experience, so writing tests looks almost identical whether you're using the CLI tool, the Slack app, or another official integration.

Follow this structure when writing measurement commands:

globalping [command] [target] from [location] [flags]

Examples:

Let's look at the components:

Available test types

Globalping supports the following:

Best practices and tips

Learn to use Globalping in the most optimal way!

Test with "magic" 🧙

All integrations connect to the same API and use our "magic" field as location input. This is the best way to interact with Globalping, as it maintains a consistent and straightforward user experience, allowing you to reuse logic and parameters across all tools.

So, for example, when you run a test from "Germany" using the CLI, Slack app, or any other official integration, our API's magic parser processes the location.

[!Note] Developers who want stricter and more predictable control over the selected probes and user input can use the individual location parameters when making an API call, which expect you to provide each city, country, and tag in a standardized way.

The magic field supports a wide range of parameters and location combinations, including countries, continents, cities, US states, regions (Western Europe), ASNs, ISP names, eyeball or data center tags, and cloud region names (us-east-2).

Reselect probes ♻️

You can also provide the "magic" field with a measurement ID to have the API select the same probes used in a previous measurement.

For example:

[!IMPORTANT] This is a best-effort action, and if some of the probes are no longer online, they will be missing from the new results. Additionally, as measurements expire (lifetime depends on user type), you should not hard-code measurement IDs, as new tests will break after a measurement expires.

You can obtain the measurement ID through the "share" functionality. For example, use --share in the CLI, find the "Share URL" section at the bottom of the web results or receive it by calling the API directly.

Some practical use cases:

Understand the "world" location 🌍

The world location is special and uses a pseudo-random algorithm to select probes while maintaining certain proportions per continent.

[!Important] If you provide no location, the system defaults to using "world".

For example, when requesting tests from world --limit 100, the system aims to return probes proportionally from Africa (5 probes), Asia (15 probes), Europe (30 probes), Oceania (10 probes), North America (30 probes), and South America (10 probes).

Basic location targeting 📍

Our aim is to enable you to provide whatever location feels right – some examples:

We'd only get one probe in these examples because we didn't specify a limit. But, if you select a large region, for instance, you expect to get multiple results. Use the --limit flag to define the number of tests to run, which is set to one (1) by default.

For example:

Other location examples:

[!NOTE] Providing no location defaults to world, selecting a probe from a random location.

Stack location filters 🍔

You can combine multiple locations using the plus symbol +, and use them as filters to define your desired probe locations more accurately.

Examples:

You can combine as many parameters as you like:

Naturally, you can combine filters and multiple locations at the same time:

You can also define your own "world" location, for example:

returns probes from these countries in roughly equal proportions to meet the limit of 20.

[!Important] The limit parameter is global and applies to the location as a whole, not allowing the API to return more than the limit. If you want to set custom limits per location, use our API directly instead of the "magic" field.

Leverage system tags (eyeball networks and more) 🏷️

Many probes are going to be tagged by our system. At the moment, this includes:

Things to keep in mind

Probes share no UUIDs

Our probes don't expose unique IDs that you can use to target them explicitly. Instead, we recommend fine-tuning the probe selection by using and combining filters or specifying IDs from previous measurements, as described in the best practice section above.

This ensures that popular locations, like from Amsterdam or from AWS, are automatically load-balanced across multiple probes within the same location, preventing the overload of specific probes.

Best-effort results

When requesting a specific number of probes, there is no guarantee that the API will respond with the exact amount.

Probe availability rules

Globalping exposes and lets you interact with probes that are currently online.

Here's when a probe is considered online and available through our API:

This whole process is completely automated and managed by our platform.

Join the network – Run a probe

Globalping relies on the community to expand its probe network. While we maintain our own probes in key locations, we welcome any support from both corporate partners and individuals. Join our network and help make the internet faster for everyone by running a probe (or several).

Setup instructions

You can run a Globalping probe on any internet-accessible device that can run a Docker container. For example, you can use a rented VPS, a dedicated server with spare capacity, or even your locally hosted Raspberry PI.

Use this command to create and run the Globalping probe container:

docker run -d --log-driver local --network host --restart=always --name globalping-probe globalping/globalping-probe

And it works on x86 and ARM architectures. Podman instructions

Notes on probe security and customization

Learn more in the Globalping Probe respository.

Limits

Our platform has multiple limits to prevent abusive behaviour while motivating people to contribute to the sustainability of the project. Here's an overview:

Global limits

These limits apply per IP address to all users:

Unauthenticated users

Anyone can connect to and use our API without credentials. For users without authentication, we limit the number of tests an IP address can run:

[!note] A test is defined as a successful measurement the platform runs from one probe. For example, a limit of 10 tests means that users can either run 10 measurements with the probe limit set to 1 per measurement or a single measurement with the probe limit set to 10.

Registered users – Free

All registered users get an API key for authentication, granting them higher limits - register on our Dashboard:

Additionally, users hosting probes receive 150 credits per day for each probe.

[!note] Credits allow you to run measurements above the hourly limits and are automatically deducted from your account as needed. Each test above the limit costs one credit. Credits have no expiration and keep accumulating in your account when you don't use them.

GitHub Sponsors

As a GitHub Sponsor of jsDelivr, your contributions help us continue the development of all projects under the jsDelivr Organization.

As a thanks, you receive additional 2000 credits for every dollar donated.

Custom limits

Feel free to reach out if you need a custom limit for your API key.

We're happy to provide free credits for researchers, non-profits, and other open-source projects.

Support and feedback

If you are stuck or want to give us your feedback, please open a new issue.

Development

Please refer to CONTRIBUTING.md for more information.