- Better understand your network routing, fix anycast issues, monitor your CDN and DNS performance,
- do uptime monitoring and build your own network tools for personal or public use.
+ 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.
[Edis Global](https://www.edisglobal.com) |
|---|---|---|
-Consider [running our probe software](https://github.com/jsdelivr/globalping-probe) on your network of servers or [sponsor a batch of hardware probes](https://docs.google.com/document/d/1xIe-BaZ-6mmkjN1yMH5Kauw3FTXADrB79w4pnJ4SLa4/edit#heading=h.tmcgof2zm3yh) with your own stickers and swag included to ship to your users or distribute at conferences.
-Stand out among the sea of water bottles and pens!
+### 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 test
+- [Run multiple probes](https://github.com/jsdelivr/globalping-probe): Globalping relies on a globally distributed network of probes for running network measurement requests. We're happy to list anyone who can host at least six probes as a donor on GitHub and our website.
+- [Become a GitHub sponsor](https://github.com/sponsors/jsdelivr): By becoming a GitHub sponsor of [jsDelivr](https://github.com/jsdelivr), you are supporting both the jsDelivr CDN and the Globalping platform. Sponsors contributing $10 or more per month can request a hardware probe to install in their home or office.
+- [Become a hardware probe provider](https://docs.google.com/document/d/1xIe-BaZ-6mmkjN1yMH5Kauw3FTXADrB79w4pnJ4SLa4/edit#heading=h.tmcgof2zm3yh): Sponsor a batch of co-branded hardware probes, including your own stickers and swag, to ship to your users or hand out at conferences.
-You can begin using the platform in a few different ways:
+## 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](https://www.jsdelivr.com/globalping)
+### [Web-based tools - Globalping website](https://www.jsdelivr.com/globalping)
[](https://www.jsdelivr.com/globalping)
-Our website is the best way to get started. You can start running tests immediatly and learn more about how different parts of the system work.
-For example our magic location field can accept not just locations but also cloud regions, ISP providers and even combine filters using the + symbol.
+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](https://github.com/jsdelivr/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 our CLI tool to upgrade your network debugging capabilities. Get access to a global network of probes without leaving your command line!
+Install the CLI on Linux, macOS, or Windows using the command for your package manager:
```
#Ubuntu
@@ -70,7 +77,7 @@ OR
choco install globalping
```
-And then run your tests in a familiar way:
+And then run your tests:
```
$ globalping traceroute google.com from Western Europe --limit 2
@@ -90,12 +97,12 @@ traceroute to google.com (142.250.185.78), 20 hops max, 60 byte packets
...
```
-[Learn more about Globalping CLI in the dedicated repo](https://github.com/jsdelivr/globalping-cli)
+Learn more about the Globalping CLI [in its repository](https://github.com/jsdelivr/globalping-cli)
### 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.
-If you're building something custom or simply want to learn more about all the available options and data we provide check out the Globalping REST API.
-It's as simple as:
+Creating a new measurement test is as simple as:
```
POST https://api.globalping.io/v1/measurements
@@ -114,77 +121,117 @@ POST https://api.globalping.io/v1/measurements
### Slack App
-
-Install our Slack App to interact with the Globalping platform without ever leaving Slack. Allow your NOC, OPS and Support teams to quickly debug networking issues and discuss the results.
+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.
-It supports a human friendly interface for issuing commands. To begin simply type `/globalping help`.
+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`.
-Examples:
+Example commands to try:
```
-/globalping {command} {target} from {location} --limit {number of probes}
+
/globalping ping 8.8.8.8 from Germany
+
/globalping traceroute jsdelivr.com from South America --limit 2
-/globalping help
+
```
-The location field can process all kinds of different types of location matching, including continents, regions, countries, cities, US states and ASNs. ASNs must be prefixed by "AS", e.g. `from AS80085`.
-You can also combine filters, e.g. `from hetzner+Finland` will ensure the results come from a probe that matches both parameters.
-Providing no location will default to "world" which will match a probe from a random location in the world.
+>[!Important]
+> To make the app post test results in Slack Threads, mention it using `@globalping`. For example, `@globalping ping google.com`
-You can even mention it in threads using `@globalping ping google.com`
+Learn more about the Slack app [on our blog](https://www.jsdelivr.com/blog/network-troubleshooting-in-slack-made-easy-with-globalping/).
### 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.
-Our GitHub bot can by triggered by simply mentioning it in any public GitHub issue. It supports a human friendly format of issuing commands and follows the existing Slack and CLI formatting logic allowing you to easily move between integrations.
-
-Examples:
+Example commands to try:
```
@globalping ping 8.8.8.8 from Germany
@globalping traceroute jsdelivr.com from South America --limit 2
```
-The location field can process all kinds of different types of location matching, including continents, regions, countries, cities, US states and ASNs. ASNs must be prefixed by "AS", e.g. `from AS80085`.
+Learn more about the GitHub bot [on our blog](https://dev.to/globalping/supercharge-your-gitops-workflows-with-the-globalping-github-bot-341a).
-## Best practices and Tips
+## 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.
-Learn to use Globalping in the most optimal way! All examples below are based on our CLI tool for simplicity.
+Follow this structure when writing measurement commands:
-### Magic field
-All of our integrations are using the same API and our "magic" field as location input.
+`globalping [command] [target] from [location] [flags]`
-This means that when you type that you want to run a ping from Germany in our CLI or our website, your input (Germany) gets processed by the magic parser of our API.
+Examples:
+- `globalping ping google.com from aws`
+- `globalping ping google.com from Berlin, South America --limit 2`
-This is the best way to interact with the Globalping platform as it maintains a consistent and simple user experience and allows you to reuse the same logic and parameters across all of our tools.
+Let's look at the components:
+##### Available test types
+Globalping supports the following:
+- ping
+- traceroute
+- mtr
+- dns (similar to dig)
+- http (similar to curl GET and HEAD)
+##### Target
+The target represents the destination for your test. This can be a domain name or an IP address for most test types.
+##### Location
+The location field can process different locations, including continents, regions, countries, cities, US states, and ASNs (prefixed by "AS," e.g., `from AS80085`). You can also specify measurement IDs from previous tests to reuse the same probes.
+>[!TIP]
+>Check out our [best pracises and tips](#basic-location-targeting-) to learn how to define locations effectively.
-> If you as a developer want a stricter and more predictable control over the selected probes and user input, then you have the option to use [the strict parser](https://www.jsdelivr.com/docs/api.globalping.io#post-/v1/measurements) that expects you to define every city, country and tag in a standardized way.
+## Best practices and tips
+Learn to use Globalping in the most optimal way!
-The magic field supports a wide range of possible parameters and location combinations logic, including but not limited to continents, regions, countries, cities, ASNs, ISP names, cloud region names as well as system and user defined tags.
+### 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.
-### The World
-The `world` location is special and uses a pseudo-random algorithm to select probes randomly while [maintaining certain proportions](https://github.com/jsdelivr/globalping/blob/master/config/default.cjs#L47) per continent.
+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 that when you provide no location at all then the system will use "world" internally by default.
+> [!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](https://www.jsdelivr.com/docs/api.globalping.io#post-/v1/measurements), which expect you to provide each city, country, and tag in a standardized way.
-This means that if you request a measurement `from world --limit 100` the system will try to return back: 5 probes from Africa, 15 from Asia, 30 from Europe, 10 from Oceania, 30 from North America and 10 from South America.
+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).
-### Basic location targeting
+### 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.
-It's very simple to get started, in most cases you can simply type whatever feels right.
-Some examples:
+For example:
+- `from WZIAtMx4LLhzit02`
-- `from usa` or `from united states` - This will result in a random probe in USA
-- `from new york` - A random probe in NYC
-- `from aws` - A random probe hosted with Amazon
+> [!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:
+- Increase the reliability of network endpoint comparisons, such as CDN, DNS, and edge compute benchmarking, as well as provider comparisons.
+- Support troubleshooting by preselecting the probes in problematic networks and running different tests, with different parameters if needed but with the same probes, until your issue is solved.
+- Emulate a continuously running ping or mtr by reusing probes and stitching together the output of different measurements into a single output.
+
+### Understand the "world" location 🌍
-In the above cases since no limit parameter is specified you will only get 1 probe. In most cases when you select a large region you will expect to get multiple answers, make sure you set your limit accordingly.
+The `world` location is special and uses a pseudo-random algorithm to select probes while [maintaining certain proportions](https://github.com/jsdelivr/globalping/blob/master/config/default.cjs#L47) per continent.
-- `from north america` will return either USA or Canada. But:
-- `from north america --limit 2` will return both
+> [!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:
+- `from usa` or `from united states` - A random probe in the USA
+- `from new york` - A random probe in NYC
+- `from aws` - A random probe hosted with Amazon
+- `from WZIAtMx4LLhzit02` - Selects the same probes that were used for the specified measurement
-Other acceptable location 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:
+- `from north america` selects one probe in either USA or Canada.
+- `from north america --limit 2` selects one probe in USA **and** one in Canada.
+
+Other location examples:
- europe, africa, asia
- east asia, north europe, eastern europe
- greece, canada, mexico, japan
@@ -192,125 +239,122 @@ Other acceptable location examples:
- frankfurt, dallas, sydney
- as396982, as16509
- comcast, google, ovh, orange, t-mobile
+- eyeball, datacenter
-### Stack filters
-
-You can also combine multiple locations and use them as filters to increase the accuracy of your tests. For this purpose we use the plus symbol +.
+> [!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.
-- `from comcast+california` will return a probe that is both hosted with Comcast and located in CA.
-- `from google+europe` will return a random probe hosted with Google Cloud in Europe, or if you want to be more specific but dont remember the cloud region name:
-- `from google+germany` will return a probe with Google Cloud Germany
-
-You can combine as many parameters as you want too
-
-- `from cogent+europe+datacenter` will return a probe hosted with Cogent, located in Europe and tagged as a datacenter probe. Or you could use `eyeball` to do the opposite.
-
-### Multiple locations
-
-To select multiple locations in a single request you can use a comma. And of course you can combine filters and multiple locations at the same time.
-
-- `from amazon+france,ovh+france --limit 2` will return a probe hosted with AWS in France and a probe hosted with OVH in France
+Examples:
+- `from comcast+california` returns a probe on the Comcast network in California.
+- `from google+europe` returns a Google Cloud probe in Europe.
+- `from google+germany` returns a Google Cloud probe in Germany (useful if you forget the cloud region name!).
-You can use this functionality to also define your own "world".
+You can combine as many parameters as you like:
+- `from cogent+europe+datacenter` returns a probe hosted at Cogent in Europe, tagged as a data center probe. Or you could use the `eyeball` tag to target probes that aren't part of a data center.
+### Define multiple locations 🌐
+To run tests at multiple locations in a single request, list them with a comma, for example:
-- `from germany, greece, uk, usa, canada, japan, china, south africa --limit 20` will return probes from all of the above countries in roughly equal proportions to fit the limit of 20.
+- `from Berlin,South America,Idaho --limit 4`.
-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 need to define custom limits per location you need to use our API directly instead of the magic field.
+Naturally, you can combine filters and multiple locations at the same time:
+- `from amazon+france,ovh+france --limit 2` returns a probe hosted on AWS in France and a probe hosted on OVH in France.
-### System tags (eyeball networks and more)
+You can also define your own "world" location, for example:
-Many probes are going to be tagged by our system. At the moment this includes:
+- `from germany, greece, uk, usa, canada, japan, china, south africa --limit 20`
-- Cloud regions for Google Cloud and AWS. e.g. `aws-eu-west-1` and `gcp-us-south1` They follow each provider's naming scheme and are prefixed by their name.
-- Eyeball and datacenter networks. e.g. `eyeball-network` and `datacenter-network` Unlike datacenter hosted probes, eyeball network are probes hosted with ISP providers that offer internet access to regular people and small businesses.
+returns probes from these countries in roughly equal proportions to meet the limit of 20.
-### No UUIDs
+>[!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.
-Our probes don't expose any unique IDs to target. The recommended way to narrow down your results is to use filters and even stack them together.
+### Leverage system tags (eyeball networks and more) 🏷️
+Many probes are going to be tagged by our system. At the moment, this includes:
-This way popular locations such as `from Amsterdam` or `from AWS` will be automatically load-balanced among multiple probes in the same location and avoid overloading any specific one.
+- **Google Cloud and AWS cloud region names**. For example, `aws-eu-west-1` and `gcp-us-south1`. These tags follow the respective provider's naming scheme and are prefixed with their name.
+- **Eyeball and data center network tags**. `eyeball` and `datacenter`. `eyeball` probes are hosted with ISPs that provide internet access to regular people and small businesses. As the name suggests, `datacenter` tags are intended for probes hosted in a data center.
-### Best effort results
+### Things to keep in mind
-When requesting a specific number of probes there is no guarantee that the API will respond back with the exact same amount. Keep this in mind and use it to your benefit.
+#### 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.
-### Probe availability
+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.
-Globalping only exposes and allows users to interact with online probes. A probe is considered online and becomes available via our API when:
+#### Best-effort results
+When requesting a specific number of probes, there is no guarantee that the API will respond with the exact amount.
-- It's up-to-date. A probe running an older version will be forced to auto-update before it becomes available.
-- Passes quality control tests. Every probe must first pass a test to ensure it's connected to a reasonably stable network with no packet loss. This test is then repeated on a schedule and will take a probe offline if it fails the QA test.
+#### Probe availability rules
+Globalping exposes and lets you interact with probes that are currently **online**.
-This is completely automated and managed by our platform.
+Here's when a probe is considered online and available through our API:
+- **It's up-to-date.** A probe running an older version will be forced to auto-update before it becomes available.
+- **It passes quality control tests.** Every probe must pass a test, ensuring it's connected to a reasonably stable network without packet loss. This test is done regularly; if a probe fails, it gets taken offline.
+- **It's not behind a VPN**. We block probes that we detect are hosted behind VPNs or other proxying techniques, as they would report incorrect latency and routing data, making them unusable.
+This whole process is completely automated and managed by our platform.
-## Join the Network - Run a probe
+## 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](https://github.com/jsdelivr/globalping-probe) and help make the internet faster for everyone by running a probe (or several).
-Globalping relies on the community to help us expand our network of probes. So while we run our own probes in key locations we still need help from both corporate partners and individials. Consider joining our network and helping everyone by running a probe (or many).
-You can do it on a rented VPS or Dedicated server that has available capacity or even on a locally hosted Raspberry pi. The only requirement is having an internet accessible device able to run docker containers.
+### 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.
-It's as simple as running this command:
+Use this command to create and run the Globalping probe container:
```
docker run -d --log-driver local --network host --restart=always --name globalping-probe ghcr.io/jsdelivr/globalping-probe
```
-And it works for both x86 and ARM architectures.
-[Podman related instructions.](https://github.com/jsdelivr/globalping-probe#podman-alternative)
-
-Notes:
-- The probe doesn't open any ports or accept any incoming connections. It can only establish a connection with our API.
-- We include regularly updated lists and databases of domains and IPs that are associated with malware or potentially dangerous content and completely ban them on the API level
-- The tests scale to the amount of available CPU cores. Our code is very lightweight and shouldn't use too many of your resources, so in most cases we recommend running our probe as is. But if you're worried you can use `--cpuset-cpus="0-2"` to limit the number of available cores.
-- We rate-limit all users on the API level to avoid the abuse of network
-- No local network tests are allowed, only public endpoints.
+And it works on x86 and ARM architectures. [Podman instructions](https://github.com/jsdelivr/globalping-probe#podman-alternative)
-Read more about the [Globalping Probe](https://github.com/jsdelivr/globalping-probe) in the dedicated repo.
+Notes on probe security and customization
+- Probes don't open any ports or accept any incoming connections. They can only establish a connection with our API.
+- We include regularly updated lists and databases of domains and IPs associated with malware or potentially dangerous content and completely ban them at the API level.
+- Tests scale to the amount of available CPU cores. Our code is very lightweight and shouldn't use too many of your resources. Therefore, in most cases, we recommend running our probe as is. However, if you're worried, you can use `--cpuset-cpus="0-2"` with your Docker command to limit the number of available cores.
+- We rate-limited all users on the API level to prevent the abuse of the network.
+- No local network tests are allowed, only public endpoints.
+Learn more in the [Globalping Probe respository](https://github.com/jsdelivr/globalping-probe).
## Limits | WIP
-
-Our platform has multiple limits to avoid abusive behaviour and at the same time motivate people to contribute to the sustainability of our platform.
+Our platform has multiple limits to prevent abusive behaviour while motivating people to contribute to the sustainability of our platform. Here's an overview:
#### Global limits
+These limits apply per IP address for all Globalping users:
-These limits are applied per IP address regardless if an API key supplied or not.
-
-- 100 POST requests per minute per IP. No GET limits are implemented to support "real-time" use-cases.
-- A single measurement is limited to 200 probes per location and 500 total probes
+- 100 POST requests per minute per IP. No GET limits are implemented to support "real-time" use cases.
+- A single measurement is limited to 200 probes per location and 500 total probes.
+#### Unauthenticated users
+Anyone can connect to and use our API without requiring any credentials.
+For users without authentication, we limit the number of tests an IP address can run:
-#### Un-authenticated users
+- 100 tests per hour
-Anybody can connect to our API and start using it with no credentials required.
-In this case we limit the amount of tests an IP address can run. A single test is defined as a succesful measurement we run and return to the user.
-A limit of 10 tests means the user can run either 10 measurements with the probe limit set to 1 per measurement, or a single measurement with the probe limit set to 10.
+>[!note]
+> A test is defined as a successful measurement the platform runs and returns to the user. 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.
-- 100 tests per hour
+#### Registered jsDelivr users – Free
+All registered jsDelivr users get an API key for authentication, granting them higher limits:
+- 200 tests per hour
-#### Registered jsDelivr users - Free
-
-All registered jsDelivr users get an API key they can use to authenticate themselves and get higher limits
-
-- 200 measurements per hour
-
-
-#### GitHub Sponsors - Contribute to the development of the project
-
-By becoming a sponsor of jsDelivr you automatically help us sustain both the jsDelivr CDN and the Globalping platform.
-Your contributions will be used to help us continue the development of all projects under the [jsDelivr Organization](https://github.com/jsdelivr)
-
-You can do this by registering on jsdelivr.com and becoming a GitHub sponsor.
-We will then automatically upgrade your account to get a higher limit as defined in each of the available plans.
+#### GitHub Sponsors
+As a GitHub Sponsor of jsDelivr, your contributions help us continue the development of all projects under the [jsDelivr Organization](https://github.com/jsdelivr).
+As a thanks, we upgrade your account to receive higher limits.
#### Custom limits
-
Feel free to reach out if you need a custom limit for your API key.
-We're more than happy to provide higher limits to researchers, non-profits and other open source projects.
+We're happy to provide higher limits for researchers, non-profits, and other open-source projects.
-## Development
+## Support and feedback
+If you are stuck or want to give us your feedback, please [open a new issue](https://github.com/jsdelivr/globalping/issues).
+## Development
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more information.